5.2.5 Advanced Usage

Several module level functions are available for controlling how doctests are run.

debug( module, name)

Debug a single docstring containing doctests.

Provide the module (or dotted name of the module) containing the docstring to be debugged and the name (within the module) of the object with the docstring to be debugged.

The doctest examples are extracted (see function testsource()), and written to a temporary file. The Python debugger, pdb, is then invoked on that file. New in version 2.3.

testmod( )

This function provides the most basic interface to the doctests. It creates a local instance of class Tester, runs appropriate methods of that class, and merges the results into the global Tester instance, master.

To get finer control than testmod() offers, create an instance of Tester with custom policies, or run methods of master directly. See Tester.__doc__ for details.

testsource( module, name)

Extract the doctest examples from a docstring.

Provide the module (or dotted name of the module) containing the tests to be extracted and the name (within the module) of the object with the docstring containing the tests to be extracted.

The doctest examples are returned as a string containing Python code. The expected output blocks in the examples are converted to Python comments. New in version 2.3.

DocTestSuite( [module])

Convert doctest tests for a module to a unittest.TestSuite.

The returned TestSuite is to be run by the unittest framework and runs each doctest in the module. If any of the doctests fail, then the synthesized unit test fails, and a DocTestTestFailure exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.

The optional module argument provides the module to be tested. It can be a module object or a (possibly dotted) module name. If not specified, the module calling this function is used.

Example using one of the many ways that the unittest module can use a TestSuite:

    import unittest
    import doctest
    import my_module_with_doctests

    suite = doctest.DocTestSuite(my_module_with_doctests)
    runner = unittest.TextTestRunner()
    runner.run(suite)

New in version 2.3. Warning: This function does not currently search M.__test__ and its search technique does not exactly match testmod() in every detail. Future versions will bring the two into convergence.

See About this document... for information on suggesting changes.