5.2.5 Unittest API
As your collection of doctest'ed modules grows, you'll want a way to run all their doctests systematically. Prior to Python 2.4, doctest had a barely documented Tester class that supplied a rudimentary way to combine doctests from multiple modules. Tester was feeble, and in practice most serious Python testing frameworks build on the unittest module, which supplies many flexible ways to combine tests from multiple sources. So, in Python 2.4, doctest's Tester class is deprecated, and doctest provides two functions that can be used to create unittest test suites from modules and text files containing doctests. These test suites can then be run using unittest test runners:
import unittest
import doctest
import my_module_with_doctests, and_another
suite = unittest.TestSuite()
for mod in my_module_with_doctests, and_another:
suite.addTest(doctest.DocTestSuite(mod))
runner = unittest.TextTestRunner()
runner.run(suite)
There are two main functions for creating unittest.TestSuite instances from text files and modules with doctests:
-
Convert doctest tests from one or more text files to a
unittest.TestSuite.
The returned unittest.TestSuite is to be run by the unittest framework and runs the interactive examples in each file. If an example in any file fails, then the synthesized unit test fails, and a failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.
Pass one or more paths (as strings) to text files to be examined.
Options may be provided as keyword arguments:
Optional argument module_relative specifies how the filenames in paths should be interpreted:
- If module_relative is
True(the default), then each filename specifies an OS-independent module-relative path. By default, this path is relative to the calling module's directory; but if the package argument is specified, then it is relative to that package. To ensure OS-independence, each filename should use/characters to separate path segments, and may not be an absolute path (i.e., it may not begin with/). - If module_relative is
False, then each filename specifies an OS-specific path. The path may be absolute or relative; relative paths are resolved with respect to the current working directory.
Optional argument package is a Python package or the name of a Python package whose directory should be used as the base directory for module-relative filenames. If no package is specified, then the calling module's directory is used as the base directory for module-relative filenames. It is an error to specify package if module_relative is
False.Optional argument setUp specifies a set-up function for the test suite. This is called before running the tests in each file. The setUp function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed.
Optional argument tearDown specifies a tear-down function for the test suite. This is called after running the tests in each file. The tearDown function will be passed a DocTest object. The setUp function can access the test globals as the globs attribute of the test passed.
Optional argument globs is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, globs is a new empty dictionary.
Optional argument optionflags specifies the default doctest options for the tests, created by or-ing together individual option flags. See section 5.2.3. See function set_unittest_reportflags() below for a better way to set reporting options.
Optional argument parser specifies a DocTestParser (or subclass) that should be used to extract tests from the files. It defaults to a normal parser (i.e.,
DocTestParser()).New in version 2.4.
- If module_relative is
-
Convert doctest tests for a module to a
unittest.TestSuite.
The returned unittest.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 failureException exception is raised showing the name of the file containing the test and a (sometimes approximate) line number.
Optional argument module 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.
Optional argument globs is a dictionary containing the initial global variables for the tests. A new copy of this dictionary is created for each test. By default, globs is a new empty dictionary.
Optional argument extraglobs specifies an extra set of global variables, which is merged into globs. By default, no extra globals are used.
Optional argument test_finder is the DocTestFinder object (or a drop-in replacement) that is used to extract doctests from the module.
Optional arguments setUp, tearDown, and optionflags are the same as for function DocFileSuite() above.
New in version 2.3.
Changed in version 2.4: The parameters globs, extraglobs, test_finder, setUp, tearDown, and optionflags were added; this function now uses the same search technique as testmod().
Under the covers, DocTestSuite() creates a unittest.TestSuite out of doctest.DocTestCase instances, and DocTestCase is a subclass of unittest.TestCase. DocTestCase isn't documented here (it's an internal detail), but studying its code can answer questions about the exact details of unittest integration.
Similarly, DocFileSuite() creates a unittest.TestSuite out of doctest.DocFileCase instances, and DocFileCase is a subclass of DocTestCase.
So both ways of creating a unittest.TestSuite run instances of DocTestCase. This is important for a subtle reason: when you run doctest functions yourself, you can control the doctest options in use directly, by passing option flags to doctest functions. However, if you're writing a unittest framework, unittest ultimately controls when and how tests get run. The framework author typically wants to control doctest reporting options (perhaps, e.g., specified by command line options), but there's no way to pass options through unittest to doctest test runners.
For this reason, doctest also supports a notion of doctest reporting flags specific to unittest support, via this function:
-
Set the doctest reporting flags to use.
Argument flags or's together option flags. See section 5.2.3. Only "reporting flags" can be used.
This is a module-global setting, and affects all future doctests run by module unittest: the runTest() method of DocTestCase looks at the option flags specified for the test case when the DocTestCase instance was constructed. If no reporting flags were specified (which is the typical and expected case), doctest's unittest reporting flags are or'ed into the option flags, and the option flags so augmented are passed to the DocTestRunner instance created to run the doctest. If any reporting flags were specified when the DocTestCase instance was constructed, doctest's unittest reporting flags are ignored.
The value of the unittest reporting flags in effect before the function was called is returned by the function.
New in version 2.4.
 |
 |
 |
Python Library Reference |  |
 |
 |
Release 2.4, documentation updated on 29 November 2004.