[Python-3000] doctests vs. unittests (was Re: pimp; restructuring the standard library)
Phillip J. Eby
pje at telecommunity.com
Fri Jun 29 17:37:51 CEST 2007
At 01:40 AM 6/29/2007 -0400, Chris McDonough wrote:
>When coverage gets good, "documentation-ness" of tests suffers.
The question is more one of, "documentation for whom?". You can
write separate documents for library users than for library
extenders/developers. I don't put doctests in docstrings, but if I
did, I'd probably only put user doctests there. As it is, I normally
split my doctests into multiple files for different audiences, or
under different headings in one large file.
For example, if you look at the BytecodeAssembler documentation:
You'll see that the assertion and invariant testing is mostly
relegated to a separate section.
Another library I'm working on has two doctest files for users (a
quick intro and a developer guide/reference) and a separate file that
tests all the innards. So, there are a lot of ways to use doctests
effectively, at least if you're doing them in text files, rather than
in your docstrings. I've actually never put a doctest in a
docstring; it always seems like overkill to me. (Especially since
reST doctests can be made into nice HTML pages like the above!)
More information about the Python-3000