[TIP] nose_fixes 1.1 released!

[Jonathan Lange]

On Fri, Nov 25, 2011 at 1:17 AM, Ben Finney <ben+python at benfinney.id.au> wrote:
> Robert Collins <robertc at robertcollins.net> writes:
>
>> On Thu, Nov 24, 2011 at 1:18 AM, Ben Finney <ben+python at benfinney.id.au> wrote:
>
>> > Er, why is that considered silly? When I write a docstring for a
>> > test, it is in the expectation that test reports will use the
>> > synopsis (the first line of the PEP 257 compliant docstring) as the
>> > test description.
>>
>> IIRC there was a thread here that dug into the reason not all that
>> long ago.
>
> URL please?
>
>> Twisted trial, testtools, zope.testrunner - all these runners show
>> just the id by default.
>
> Yes. That's what I'm saying: they should show the synopsis line *also*,
> since that's a significant part of the value of writing it.
>
>> In general the goal of a test failure is to let you identify the
>> failing code so that you can:
>>  - reproduce the failure
>>  - examine the code that caused the failure
>>  - including any parameterisation
>
> Those are all valuable. I'm saying there is *also* value in seeing what
> the test is about in plain language; and a huge fully-qualified test
> function name isn't the best way to show that.
>

I certainly find comments/docstrings on tests to be highly useful[1],
but generally I get all of the utility when I see a failing test, go
look it up in my editor and then read the docstring.

I'm keen to learn if there's a better way though. What sort of
docstrings do you write? Do you like the first line of the docstring
displayed, or the whole thing? How does the content of the docstring
illuminate where the name of the test doesn't? Some test runners show
tests twice: once while running them and once again in a summary if
they fail: does it help to have the docstring in both places?

Sorry to give you the third degree, but you're the first person I know
who likes this behaviour, and I want to know more.

jml

[1] Well, as long as they don't start with "Test that ...". Ugh. I'm
also a bit pedantic about avoiding "should", but we can still be
friends if you sometimes do that.