[Python-Dev] An OO API for doctest / unittest integration...

[Olemis Lang]

Hello... this is my first post to this list and...

I would like to introduce myself by proposing a module for inclusion
(hopefully in a "near future") among the standard libraries (modules)
offered by Python (of course the idea is to present it here, promote
the debate and if "we all like it", well... distribute it together
with Python). I will be as concise as possible all the way through
this message so as to avoid writing a long speech (and therefore a
lengthy message). Further details can be found in an article published
"a few months ago" [1].

The module (its name... dutest) has the same goals considered to
develop the unittest API provided by doctest since Python 2.4.
However it includes other important features which make the
difference. Some of them are the following:

  * A novel object-oriented API programmers can use in order to
    retrieve test cases out of interactive sessions in the form
    doctest examples. In other words, novel test loaders find and
    put test cases together, just like unittest test loaders do.
    Nowadays the unittest API included in doctest offers the functions
    DocFileSuite and DocTestSuite for this purpose, therefore lacking
    in object orientation.

  * The match made for different doctest examples during a doctest run
    is stored separately by instances of TestResult. Nowadays
    the unittest API included in doctest stores the whole doctest
    report at once into test results. This has some "drawbacks".
    Firstly, it is difficult to know what is wrong during the test
    (since to kinds of reports are intermingled). Besides several
    summaries can be found throughout test reports. When building test
    analysis tools, this also means that further parsing should be
    done so as to discover the descriptions of individual failures ...
    (further and more detailed analysis and explanations can be found
    in the aforementioned article [1])

  * A few more features...

The module is actually employed for testing the pyOOP package
(under development by the FLiOOPS project [2]). You can simply
download dutest [3] and try it out, or you can also check out the
trunk [4] doing something like

$ svn co https://flioops.svn.sourceforge.net/svnroot/flioops/py/trunk .

install the package doing something like

$ setup.py install
$ setup.py clean

Optionally (if you like to see a much more real test report) you
can also download the modules ipdbc [5], PyDBC [6], and
PyContracts [7], and install them.

Next, run pyOOP test suite from the Python interpreter doing something
like

{{{
#!python

try:
    from oop.test import check_oopdbc
except ImportWarning:
    from oop.test import check_oopdbc

oop.test.test_oopdbc.TESTLOG_FILE = '/path/to/log/file'

check_oopdbc()
}}}

and "see" the output report (e.g.  $ vi /path/to/log/file).

Finally, any bug or bizarre behavior you find, please submit it to the
bug tracking system of the FLiOOPS project [8]. We will fix it "as
soon as we can". If you have any suggestion or need an additional
feature, please submit a feature request to the FLiOOPs project [9]...
and/or share it with us here in python-dev... ;) as well as any
comments about the whole thing.

I hope you like it :)

----

[1] O. Lang, "Doctest and unittest… now they'll live happily forever"
    (2008) The Python Papers, vol. 3, no. 1, pp 38:51, ISSN 1834-3147.

[2] FLiOOPS project home page
       (https://flioops.sourceforge.net)

[3] Download page of module dutest
       (https://sourceforge.net/project/showfiles.php?group_id=220287&abmode=1)

[4] pyOOP SVN trunk
       (https://flioops.svn.sourceforge.net/svnroot/flioops/py/trunk)

[5] Yet another invariant/pre-/postcondition design-by-contract
       support module,
       Dmitry Dvoinikov
       (http://www.targeted.org/python/recipes/ipdbc.py)

[6] PyDBC -- Design by Contract for Python 2.2+,
       Daniel Arbuckle
       (http://www.nongnu.org/pydbc/)

[7] Contracts for Python (PEP 316),
       Terence Way
       (http://www.wayforward.net/pycontract/)

[8] Bug tracking system of the FLiOOPS project
       (https://sourceforge.net/tracker/admin/?atid=1049023&group_id=220287)

[9] Feature Request tracker system of the FLiOOPS project
       (https://sourceforge.net/tracker/admin/?atid=1049026&group_id=220287)

[10] Send patches to the FLiOOPS project
       (https://sourceforge.net/tracker/admin/?atid=1049025&group_id=220287)



-- 
Regards,

Olemis.