[TIP] Using doctest for functional tests / user stories

[Paul Moore]

I'm just starting to develop a project, and I'd like to use a
test-first development approach. I've been reading Harry Percival's
"Test-Driven Web Development" book (even though my application is not
a web site) and I love the ideas, although I'm finding them hard to
put into practice at the moment.

While I can see the advantage of starting with functional tests
expressing what the user wants to actually do with the application,
I'm not entirely happy with the unittest-based test format for this
type of thing. My mind naturally thinks in terms of "user stories", or
basically a narrative description of the user interaction as it takes
place. To me, this is a perfect fit for a doctest-style approach.
However, I haven't been able to find any discussion of using doctest
in this manner on the web.

Is doctest considered a bad idea for this type of high-level narrative
style of functional test (or spec)? Or is the whole idea of
structuring the user stories as testable documents considered bad
practice? I'm finding it very difficult to formulate good functional
tests in the unittest style, but I don't want to switch to doctest if
it's going to cause me problems as my development gets more complex.

Note - my thought was to have a number of independent doctests, each
of which is a separate, isolated user story, and none of which are
particularly long. So I don't expect test isolation or side-effects to
be a big deal (he said, naively :-)) And I'll have unit tests and more
traditional unittest-based functional tests to supplement the doctests
as I move on. I'm really looking more at doctest as a way to
"bootstrap" my project by having a very clearly documented and
testable interaction that I want to implement, right from the start.

If anyone has any thoughts or suggestions, or better alternatives I'd
be very grateful.

Thanks,
Paul