There should be some clear documentation on how to document tests.

[tom.prince]

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:

1. Write the first docstring that comes to mind. It will almost certainly be:

     """Test that input is parsed correctly."""
   

2. Get rid of "Test that" or "Check that". We know it's a test.

     """Input should be parsed correctly."""
   

3. Seriously?! Why'd you have to go and add "should"? It's a test, it's all about "should".

     """Input is parsed correctly."""
   

4. "Correctly", "properly", and "as we expect" are all redundant. Axe them too.

     """Input is parsed."""
   

5. 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.
     """
   

[tom.prince]

I wrote some words on #5952:

Generally a test docstring wants to be something like When <some thing is done>, <something else occurs>. Often <something is done> is a method being called. And <something else occurs> is generally what is captured by the assertion(s).

[rwall]

I think you should also mention when / whether and why L{}, C{} @param etc should be included in test docstrings given that the tests are not included in the API docs.

See also: #6318, #6012