|
The first word in ``doctest'' is ``doc,'' and that's why the author wrote doctest: to keep documentation up to
date. It so happens that doctest
makes a pleasant unit testing environment, but that's not its primary purpose.
Choose docstring examples with care. There's an art to this that needs to be learned--it
may not be natural at first. Examples should add genuine value to the documentation. A good
example can often be worth many words. If possible, show just a few normal cases, show
endcases, show interesting subtle cases, and show an example of each kind of exception that
can be raised. You're probably testing for endcases and subtle cases anyway in an interactive
shell: doctest wants to make it as
easy as possible to capture those sessions, and will verify they continue to work as designed
forever after.
If done with care, the examples will be invaluable for your users, and will pay back the
time it takes to collect them many times over as the years go by and things change. I'm still
amazed at how often one of my doctest
examples stops working after a ``harmless'' change.
For exhaustive testing, or testing boring cases that add no value to the docs, define a __test__
dict instead. That's what it's for.
|
