[TIP] Docstrings in Test methods

[Alfredo Deza]

The other day I had an interesting exchange of ideas at work, were we
discussed about docstrings in test methods.

It all boils down to one end saying that they completely approve and
encourage such a thing because it allows a
better description (context?) of the actual test. This is sometimes
the case when the method signature proves
difficult for a good description. For example:

def test_foo_should_be_true_when_bar_connects_successfully(self):
...

It is most annoying to write, so doing something like this makes sense:

def test_foo_should_be_true(self):
    """ when foo uses bar as a connection it should be True when successful """
....

This in turn, for most test runners, translates into roughly this output:

$ python test_foo.py -v
when foo uses bar as a connection it should be True when successful ... ok

----------------------------------------------------------------------
Ran 1 test in 0.000s

OK

Which brings us to the other end of the discussion, because as you can
see, the output eats the method signature,
so in case you are interested in knowing what method actually ran that
test, you would have to `grep` for such a docstring.

As many other things in Python, I usually see a pattern, best
practice, or "most common idea" to follow when it comes to style,
writing and designing code, but I have failed to see such a thing
regarding docstrings in test methods.

I searched around, and found the same scenario with big projects:
Twisted *requires* developers to submit code with tests that
have docstrings [0], while Pyramid has none. [1] I even found some
slides from Ned [2] but the meaning regarding this docstring
argument was not entirely clear to me.

What do you guys prefer and why (or why not?)


[0] http://twistedmatrix.com/trac/browser/trunk/doc/core/development/policy/coding-standard.xhtml?format=raw
[1] https://github.com/Pylons/pyramid/blob/master/pyramid/tests/test_events.py
[2] http://nedbatchelder.com/text/st.html#44