[py-dev] Backtracking on doctest

[Michele Simionato]

On 5/13/05, Ian Bicking <ianb at colorstudy.com> wrote:

> I think I had this idea that I could put ten lines of doctest at the top
> of my module that would be this concise documentation and description of
> the module, plus a test.  I'm not sure that's feasible, though it is
> still possible to use that for basic exercising of the code -- basically
> a one-liner that tells what a valid URL would be.  And, maybe, with a
> subclass of the standard Paste fixture you could add things like:
> 
>    app.upload_csv([('Name', 'Email'), ('Bob', 'bob at company.com')])
> 
> And that could be high enough level to get some benefit from being in a
> docstring.  But those kinds of methods (like "upload_csv") would have to
> be implemented in a class specifically meant for testing a single
> screen; which is also a useful idea, but I haven't really gotten that
> far in generalizing this stuff.

I mostly use this convention: for any mymodule.py file I have a 
mymodule.txt file containing the documentation and the basic
doctests for that module. There may be additional doctests which
do not add value to the documentation, and/or unittests: all this is
put them in a subdirectory called "test".
I tend to put very few or zero tests in the docstring.
I have my own recipe to run the text files

http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/410052

and another to run the test suite on the entire package (not yet published).


          Michele Simionato