launchpad-dev team mailing list archive

[Julian Edwards <julian.edwards@xxxxxxxxxxxxx>]

On Monday 22 February 2010 23:18:04 Martin Pool wrote:
> On 22 February 2010 20:40, Julian Edwards <julian.edwards@xxxxxxxxxxxxx> 
wrote:
> >> imo you are either writing doc tests or you're writing testable
> >> documentation; they are not the same thing at all and it's hard to
> >> make one document work for both.
> >
> > I have exactly the opposite opinion :)
> >
> > I'd like to see an example of why you think it's hard though?
> 
> A good test suite should exercise every distinct domain of the
> interface, trying to break it, paying attention to edge cases.  You
> expect them to all fail at least once so it's good to make them pretty
> fine grained and perhaps to use validating decorators or something
> else that will check internals or be faster, and perhaps to use
> infrastructure to apply the same test in many different situations.
> Having the output from one test feed into the next is generally poor
> because you get cascading confusion.
> 
> Whereas for documentation you want someone to be able to read it from
> start to end, which means it should have a kind of narrative, show the
> typical cases, not the obscure ones, and showing the typical way to
> use the object, not a special setup for testing.
> 
> At least that's how it seems to me.  If you have an example of a
> something that works really well for both at once I would be happy to
> see it.
> 


Ah, I am absolutely not advocating that a doc test does both, you're basically 
in agreement with me with your first two paragraphs here.  I think our lines 
got crossed somewhere.

For me, a doctest for a model object tells me how to use it.  The obscure 
corner cases can go in the unit tests.

J