Perhaps im not defining my pytests right but im seeing this: enter image description here

Does pep8 demand a docstring for each unit test function too? I cant find pep8 docs specific to this, wondering if pep8/flake8 is unit test aware?

I have many tests so this might be kind of a mess to have docstrings, but maybe I should have fewer tests with many asserts instead of many small tests?

For example I have specific tests like:


But perhaps it should be more like:

... then assert both cases in this single method

So if I have big tests with many cases grouped under them docstrings would be more feasible. Does pep8 or another convention have anything to say about this?

  • You unit test driver, such as nose or python -m unittest will take the first line of the docstring of each test and display that when a test fails, in addition to the test name. This can be really helpful, as it takes the pressure off naming many methods with almost identical test processes. – BobDalgleish Mar 16 '20 at 16:20
  • can someone explain why this was downvoted so I know why I should not be asking it here? – user1028270 Mar 16 '20 at 16:22

The PEP-8 document says:

sometimes style guide recommendations just aren't applicable

Here, the recommendation in question is:

Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does.

I'd argue that tests are not public modules in the sense of this recommendation, even though a test files technically is a module that could be imported and its contents are technically public. This just isn't the case.

The intention for using docstrings is that you know how to call the function. But test functions are never called directly. There's a secondary task of documenting the contents of the function (although normal comments also do the job). However, test functions often have very long and self-documenting names, so this is less of a concern.

Keeping tests somewhat tidy is legitimately important, so it can make sense to run flake8 or other linters over the test code as well. But since testing is a different context from normal code, some values are different. E.g. it is important that tests are independent, less important that tests are DRY. And whereas unused functions indicate a bug in normal code, this is normal in test code.

I would advise one of the following approaches:

  • exclude tests from linting, e.g. via a configuration file or with # flake8: noqa comments. However, this is a fairly drastic approach.
  • disable just this lint within the file, e.g. with # noqa: D103 comments. However, I'm not sure if flake8 allows you to disable a lint for the entire file, or just for the current line.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.