5.2.5 Unittest API

##
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:

`DocFileSuite`( | *paths, **kw)

  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.

`DocTestSuite`( | [module][, globs][, extraglobs][, test_finder][, setUp][, tearDown][, checker])

  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_unittest_reportflags`( | flags)

  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.