 |
 |
 |
Python Library Reference |  |
 |
 |
|
|
|
Python Library Reference | |
|
|
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.
|
|
|
Python Library Reference | |
|
|