[TIP] Declarative style acceptance tests (was: Using doctest for functional tests / user stories)

[Ben Finney]

Paul Moore <p.f.moore at gmail.com> writes:

> Is doctest considered a bad idea for this type of high-level narrative
> style of functional test (or spec)?

Doctest is best used for testing examples that already occur in
documentation, such as API references or tutorials.

For constructing rigorous acceptance tests, Doctest is a poor choice.

> 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.

You're right, unit tests are not suited for writing acceptance tests.

There are better options. It's best to have acceptance tests in as close
a form to statements the customer can understand; this means declarative
assertions in something close to natural English. These declarative
assertions can then be parsed and tested by executable test code.

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

One that I recommend is Behave <URL:http://pypi.python.org/pypi/behave>
which reads acceptance tests written in a declarative, formalised, but
plain-to-read English style; and then the programmer writes test
functions which define what the terms in those declarations mean. Behave
then tests the teclarations using your test code, and reports the
result.

-- 
 \       “I disapprove of what you say, but I will defend to the death |
  `\     your right to say it.” —Evelyn Beatrice Hall, _The Friends of |
_o__)                                                  Voltaire_, 1906 |
Ben Finney