Several module level functions are available for controlling how doctests are run.
module, name) |
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.
[m][, name][, globs][, verbose][, isprivate][, report][, optionflags][, extraglobs][, raise_on_error]) |
All arguments are optional, and all except for m should be specified in keyword form.
Test examples in docstrings in functions and classes reachable
from module m (or the current module if m is not supplied
or is None
), starting with m.__doc__
.
Also test examples reachable from dict m.__test__
, if it
exists and is not None
. m.__test__
maps
names (strings) to functions, classes and strings; function and class
docstrings are searched for examples; strings are searched directly,
as if they were docstrings.
Only docstrings attached to objects belonging to module m are searched.
Return "(failure_count, test_count)".
Optional argument name gives the name of the module; by default,
or if None
, m.__name__
is used.
Optional argument globs gives a dict to be used as the globals
when executing examples; by default, or if None
,
m.__dict__
is used. A new shallow copy of this dict is
created for each docstring with examples, so that each docstring's
examples start with a clean slate.
Optional argument extraglobs gives a dict merged into the
globals used to execute examples. This works like
dict.update(): if globs and extraglobs have a
common key, the associated value in extraglobs appears in the
combined dict. By default, or if None
, no extra globals are
used. This is an advanced feature that allows parameterization of
doctests. For example, a doctest can be written for a base class, using
a generic name for the class, then reused to test any number of
subclasses by passing an extraglobs dict mapping the generic
name to the subclass to be tested.
Optional argument verbose prints lots of stuff if true, and prints
only failures if false; by default, or if None
, it's true
if and only if '-v'
is in sys.argv
.
Optional argument report prints a summary at the end when true, else prints nothing at the end. In verbose mode, the summary is detailed, else the summary is very brief (in fact, empty if all tests passed).
Optional argument optionflags or's together option flags. See see section 5.2.5.
Optional argument raise_on_error defaults to false. If true, an exception is raised upon the first failure or unexpected exception in an example. This allows failures to be post-mortem debugged. Default behavior is to continue running examples.
Optional argument isprivate specifies a function used to
determine whether a name is private. The default function treats
all names as public. isprivate can be set to
doctest.is_private
to skip over names that are
private according to Python's underscore naming convention.
DocTestFinder.find()
instead.Changed in version 2.3: The parameter optionflags was added.
Changed in version 2.4: The parameters extraglobs and raise_on_error were added.
module, name) |
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.
[module]) |
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.