23.2.7 Debugging

Doctest provides several mechanisms for debugging doctest examples:

Several functions convert doctests to executable Python programs, which can be run under the Python debugger, pdb.
The DebugRunner class is a subclass of DocTestRunner that raises an exception for the first failing example, containing information about that example. This information can be used to perform post-mortem debugging on the example.
The unittest cases generated by DocTestSuite() support the debug() method defined by unittest.TestCase.

You can add a call to pdb.set_trace() in a doctest example, and you'll drop into the Python debugger when that line is executed. Then you can inspect current values of variables, and so on. For example, suppose a.py contains just this module docstring:

"""
>>> def f(x):
...     g(x*2)
>>> def g(x):
...     print x+3
...     import pdb; pdb.set_trace()
>>> f(3)
9
"""

Then an interactive Python session may look like this:

>>> import a, doctest
>>> doctest.testmod(a)
--Return--
> <doctest a[1]>(3)g()->None
-> import pdb; pdb.set_trace()
(Pdb) list
  1     def g(x):
  2         print x+3
  3  ->     import pdb; pdb.set_trace()
[EOF]
(Pdb) print x
6
(Pdb) step
--Return--
> <doctest a[0]>(2)f()->None
-> g(x*2)
(Pdb) list
  1     def f(x):
  2  ->     g(x*2)
[EOF]
(Pdb) print x
3
(Pdb) step
--Return--
> <doctest a[2]>(1)?()->None
-> f(3)
(Pdb) cont
(0, 3)
>>>

Changed in version 2.4: The ability to use pdb.set_trace() usefully inside doctests was added.

Functions that convert doctests to Python code, and possibly run the synthesized code under the debugger:

script_from_examples( s)

Convert text with examples to a script.

Argument s is a string containing doctest examples. The string is converted to a Python script, where doctest examples in s are converted to regular code, and everything else is converted to Python comments. The generated script is returned as a string. For example,

    import doctest
    print doctest.script_from_examples(r"""
        Set x and y to 1 and 2.
        >>> x, y = 1, 2

        Print their sum:
        >>> print x+y
        3
    """)

displays:

    # Set x and y to 1 and 2.
    x, y = 1, 2
    #
    # Print their sum:
    print x+y
    # Expected:
    ## 3

This function is used internally by other functions (see below), but can also be useful when you want to transform an interactive Python session into a Python script.

New in version 2.4.

testsource( module, name)

Convert the doctest for an object to a script.

Argument module is a module object, or dotted name of a module, containing the object whose doctests are of interest. Argument name is the name (within the module) of the object with the doctests of interest. The result is a string, containing the object's docstring converted to a Python script, as described for script_from_examples() above. For example, if module a.py contains a top-level function f(), then

import a, doctest
print doctest.testsource(a, "a.f")

prints a script version of function f()'s docstring, with doctests converted to code, and the rest placed in comments.

New in version 2.3.

debug( module, name[, pm])

Debug the doctests for an object.

The module and name arguments are the same as for function testsource() above. The synthesized Python script for the named object's docstring is written to a temporary file, and then that file is run under the control of the Python debugger, pdb.

A shallow copy of module.__dict__ is used for both local and global execution context.

Optional argument pm controls whether post-mortem debugging is used. If pm has a true value, the script file is run directly, and the debugger gets involved only if the script terminates via raising an unhandled exception. If it does, then post-mortem debugging is invoked, via pdb.post_mortem(), passing the traceback object from the unhandled exception. If pm is not specified, or is false, the script is run under the debugger from the start, via passing an appropriate execfile() call to pdb.run().

New in version 2.3.

Changed in version 2.4: The pm argument was added.

debug_src( src[, pm][, globs])

Debug the doctests in a string.

This is like function debug() above, except that a string containing doctest examples is specified directly, via the src argument.

Optional argument pm has the same meaning as in function debug() above.

Optional argument globs gives a dictionary to use as both local and global execution context. If not specified, or None, an empty dictionary is used. If specified, a shallow copy of the dictionary is used.

New in version 2.4.

The DebugRunner class, and the special exceptions it may raise, are of most interest to testing framework authors, and will only be sketched here. See the source code, and especially DebugRunner's docstring (which is a doctest!) for more details:

class DebugRunner( [checker][, verbose][, optionflags])

A subclass of DocTestRunner that raises an exception as soon as a failure is encountered. If an unexpected exception occurs, an UnexpectedException exception is raised, containing the test, the example, and the original exception. If the output doesn't match, then a DocTestFailure exception is raised, containing the test, the example, and the actual output.

For information about the constructor parameters and methods, see the documentation for DocTestRunner in section 23.2.6.

There are two exceptions that may be raised by DebugRunner instances:

exception DocTestFailure( test, example, got): An exception thrown by DocTestRunner to signal that a doctest example's actual output did not match its expected output. The constructor arguments are used to initialize the member variables of the same names.

DocTestFailure defines the following member variables:

test: The DocTest object that was being run when the example failed.

example: The Example that failed.

got: The example's actual output.

exception UnexpectedException( test, example, exc_info): An exception thrown by DocTestRunner to signal that a doctest example raised an unexpected exception. The constructor arguments are used to initialize the member variables of the same names.

UnexpectedException defines the following member variables:

test: The DocTest object that was being run when the example failed.

example: The Example that failed.

exc_info: A tuple containing information about the unexpected exception, as returned by sys.exc_info().

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