[py-dev] using docstrings for test descriptions

[holger krekel]

Hi Frederik, 

On Tue, Jul 07, 2009 at 10:30 +0100, Frederik Dohr wrote:
> Hello all,
> 
> Holger's presentations at EuroPython last week convinced me that I 
> should finally start migrating to py.test.

nice to hear :) 
 
> There's only one thing I'm missing: I'm used to providing fairly 
> detailed descriptions for individual tests ("foo returns bar if baz").
> While one could use the assert statement's second argument for this, 
> that seems cumbersome and has some undesired side-effects (e.g. 
> reporting "E    AssertionError: <description>" instead of displaying the 
> respective values).
> Docstrings appear to be the obvious (and pythonic) solution.

makes sense i think. 

> So I imagine a plugin could add docstring support, which might result in 
> output as described here:
>      http://gist.github.com/141977
> (Being new to py.test, it is possible my expectations are misguided - 
> don't hesitate to point out where that's the case.)

Python's unittest.py uses the docstrings to substitute the test
function name with the docstring.  Imitating this "py.test --verbose" 
could look like this: 

    lorem ipsum: PASS 
    dolor sit amet: PASS 
    consectetur adipisic...liqua: FAIL 

The failure tracebacks probably don't need to do anything special
as they anyway report the test function source code including
the docstring usually. 

makes senses?  Anybody else has opinions? 

> I'd be willing to look into how this might be implemented; it shouldn't 
> be too hard (e.g. using a decorator), but some pointers on how to get 
> started would be appreciated.

I think you can just patch py.test proper, more specifically 
py/test/plugin/pytest_terminal.py which is the single file
containing all the terminal reporting and also includes tests.
Please feel free to submit a patch.  

best,
holger