Andrew has written about why narrative tests make lousy unit tests and problems with the doctest format. In summary:

  • Unit tests work better if each one has a name that identifies it.
  • Specific, isolated tests give clearer failures, and are easier to debug.
  • Specific, narrow tests are better at communicating intended behaviour.
  • Comparing two objects in doctests is hard.
  • It’s hard to get an overview of what’s tested in a particular doctest file.
  • Doctest is a mini-language that’s worse than Python. It’s got corner-cases and outright bugs.
  • Tests are code, and code works better in .py files than .txt files. In particular:
    • Python has better tool support. Syntax highlighting, code folding, pyflakes, 2to3 etc.
  • It’s easier to build test infrastructure in Python.
    • Test code benefits from refactoring as much as regular code, but doctests make it hard to do this.

Of course, in the end, it comes down to this:

It is just as possible to write incomprehensible tests using doctest as it is using TestCase classes with test methods.