#253 docs: Add more wisdom about writing good tests
Merged 4 years ago by jflory7. Opened 4 years ago by jflory7.

file modified
+22 -4
@@ -7,6 +7,7 @@ 

  Not following these guidelines may make it harder or take longer to review your change.

  If you have questions about any of these guidelines, please ask in the `Community Operations team channels <https://docs.fedoraproject.org/en-US/commops/#find-commops>`__.

  

+ 

  *****

  Goals

  *****
@@ -39,10 +40,20 @@ 

  3. Good code is tested code.

  ============================

  

- Introducing new code means introducing new tests.

- If writing code that could be tested, it is code that should be tested.

- This will be considered for introducing new functionality or unique code to fedora-happiness-packets.

- 

+ Introducing new code means adding unit tests.

+ Fedora Happiness Packets uses the `Django test suite <https://docs.djangoproject.com/en/dev/topics/testing/>`__ and `pytest <https://pytest.org/>`__ for testing.

+ As a rule of thumb, consider this wisdom when writing tests:

+ 

+ * Use test functions and plain-old ``assert`` statements.

+ * Ideally, test functions should be *around* five lines and assert one thing.

+ * If you need multiple test classes, inheritance, or OOP, you might be doing it wrong.

+ * If you need to make imports from other test directories, you might be doing it wrong.

+ * If you need more than two levels of indentation, you might be doing it wrong.

+ * "There's a plugin for that!"

+   Pytest has a rich `plugin community <https://docs.pytest.org/en/latest/plugins.html>`__ with almost anything you can think of.

+   Take advantage of them!

+ * Don't use ``@mock.patch`` or ``with mock.patch``.

+   Use `pytest fixtures <https://pythontesting.net/framework/pytest/pytest-fixtures-nuts-bolts/>`__. [#]_

  

  ********************************

  Create a development environment
@@ -114,5 +125,12 @@ 

  

  *Remember*, using issue templates and answering the above questions in pull requests reduces response time from a maintainer to your ticket / PR.

  

+ 

+ .. [#] You can still use ``mock.patch``.

+        It has more features than pytest's monkeypatch fixture.

+        But don't use it with a decorator, which has a problem of applying at import time nor using it in ``with`` statements.

+        Instead, you would use it with ``pytest-mock``, which exports the Mock API via a ``mocker`` fixture.

+        The fixture ensures the enter/exit context happens at the usual time in pytest setup/teardown.

+ 

  .. |PASSED| image:: https://pagure.io/fedora-commops/fedora-happiness-packets/issue/raw/files/d4820df9449fd61951d807b5fe86231092a31db15932759b2b7b810262c002d0-Screenshot_2019-02-24_Settings_-_fedora-commops_fedora-happiness-packets_-_Pagure_io.png

     :target: https://pagure.io/fedora-commops/fedora-happiness-packets/issues?status=Open&tags=PASSED

This commit adds more wisdom about best practices for writing unit
tests. This mostly comes from what someone shared with me recently about
best practices around pytest. Generally, it's best to keep tests
simple, short, and to the point.

This addition to our docs hopefully makes for a useful reference!

Metadata Update from @jflory7:
- Pull-request tagged with: PASSED, improvement, type - docs, type - quality assurance, type - summer coding

4 years ago

@alishapapun, could you please review this PR some time after Monday? I am curious for your feedback if this is easy to understand or if there is something that could be better explained. I think the previous explanation was a little lacking! (Spoiler: I really knew nothing about testing when I wrote it the first time.)

Mostly I want to make sure this makes sense, but it is also good practice to test it out and make sure it builds too. Since it's been a while since we have worked with the docs, here are two ways to test the docs:

With Pipenv, preferred:

cd docs/
pipenv shell
pipenv install
./test-docs.sh

With regular virtualenv:

# start virtualenv with your preferred method
cd docs/
pip install -r requirements.txt
./test-docs.sh

Once you build the docs, you can open the docs/_build/index.html page in your web browser to see them rendered.

Metadata Update from @jflory7:
- Pull-request tagged with: needs testing
- Request assigned

4 years ago

+1 for the standard practices for writing test cases. Its all set to be merged. :)

rebased onto 9f63123

4 years ago

Metadata Update from @jflory7:
- Pull-request untagged with: needs testing

4 years ago

Super, thanks for the review @alishapapun! :raised_hands:

Merging. :ocean:

Pull-Request has been merged by jflory7

4 years ago