[TIP] Docstrings in Test methods

[Jonathan Lange]

On Sat, Nov 5, 2011 at 12:50 PM, Alfredo Deza <alfredodeza at gmail.com> wrote:
> The other day I had an interesting exchange of ideas at work, were we
> discussed about docstrings in test methods.
...
> 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
>
...
>
> 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.

That's because many test runners use TestCase.shortDescription(),
rather than TestCase.id(). I personally think that shortDescription is
bogus for the reasons you suggest, so the runners I've had a hand in
all use id(). That's partly why Twisted can get away with using
docstrings.

Speaking of which, I'd like to pimp a silly little tool I wrote called
"testdoc"[1]. It looks through tests, extracts their comments and/or
docstrings and converts them into rST documentation. I wrote it as a
counter-argument of sorts to the doctest folk.

jml

[1] http://launchpad.net/testdoc