#6301 enhancement new
There should be some clear documentation on how to document tests.
|Reported by:||tom.prince||Owned by:||tom.prince|
branch-diff, diff-cov, branch-cov, buildbot
The current documentation seems to consist be:
All unit test methods should have docstrings specifying at a high level the intent of the test. That is, a description that users of the method would understand.
jml posted the following to Google+, which seems to capture the unstated guidelines that are used in practice:
A lot of projects I contribute to insist that tests have comments or docstrings in them. If ever you're working on a project that has a similar requirement, and you're struggling to write docstrings for your tests, here's a handy five-step guide:
- Write the first docstring that comes to mind. It will almost certainly be:
"""Test that input is parsed correctly."""
- Get rid of "Test that" or "Check that". We know it's a test.
"""Input should be parsed correctly."""
- Seriously?! Why'd you have to go and add "should"? It's a test, it's all about "should".
"""Input is parsed correctly."""
- "Correctly", "properly", and "as we expect" are all redundant. Axe them too.
"""Input is parsed."""
- Look at what's left. Is it saying anything at all? If so, great. If not, consider adding something specific about the test behaviour and perhaps even why it's desirable behaviour to have.
""" Input is parsed into an immutable dict according to the config schema, so we get config info without worrying about input validation all the time. """