5.2.6.5 DocTestRunner objects

###
5.2.6.5 DocTestRunner objects

class `DocTestRunner`( | [checker][, verbose][, optionflags])

  A processing class used to execute and verify the interactive examples in a `DocTest`.

  The comparison between expected outputs and actual outputs is done by an `OutputChecker`. This comparison may be customized with a number of option flags; see section 5.2.3 for more information. If the option flags are insufficient, then the comparison may also be customized by passing a subclass of `OutputChecker` to the constructor.

  The test runner's display output can be controlled in two ways. First, an output function can be passed to `TestRunner.run()`; this function will be called with strings that should be displayed. It defaults to `sys.stdout.write`. If capturing the output is not sufficient, then the display output can be also customized by subclassing DocTestRunner, and overriding the methods `report_start`, `report_success`, `report_unexpected_exception`, and `report_failure`.

  The optional keyword argument checker specifies the `OutputChecker` object (or drop-in replacement) that should be used to compare the expected outputs to the actual outputs of doctest examples.

  The optional keyword argument verbose controls the `DocTestRunner`'s verbosity. If verbose is `True`, then information is printed about each example, as it is run. If verbose is `False`, then only failures are printed. If verbose is unspecified, or `None`, then verbose output is used iff the command-line switch -v is used.

  The optional keyword argument optionflags can be used to control how the test runner compares expected output to actual output, and how it displays failures. For more information, see section 5.2.3.

  New in version 2.4.

`DocTestParser` defines the following methods:

`report_start`( | out, test, example)

  Report that the test runner is about to process the given example. This method is provided to allow subclasses of `DocTestRunner` to customize their output; it should not be called directly.

  example is the example about to be processed. test is the test containing example. out is the output function that was passed to `DocTestRunner.run()`.

`report_success`( | out, test, example, got)

  Report that the given example ran successfully. This method is provided to allow subclasses of `DocTestRunner` to customize their output; it should not be called directly.

  example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to `DocTestRunner.run()`.

`report_failure`( | out, test, example, got)

  Report that the given example failed. This method is provided to allow subclasses of `DocTestRunner` to customize their output; it should not be called directly.

  example is the example about to be processed. got is the actual output from the example. test is the test containing example. out is the output function that was passed to `DocTestRunner.run()`.

`report_unexpected_exception`( | out, test, example, exc_info)

  Report that the given example raised an unexpected exception. This method is provided to allow subclasses of `DocTestRunner` to customize their output; it should not be called directly.

  example is the example about to be processed. exc_info is a tuple containing information about the unexpected exception (as returned by `sys.exc_info()`). test is the test containing example. out is the output function that was passed to `DocTestRunner.run()`.

`run`( | test[, compileflags][, out][, clear_globs])

  Run the examples in test (a `DocTest` object), and display the results using the writer function out.

  The examples are run in the namespace `test.globs`. If clear_globs is true (the default), then this namespace will be cleared after the test runs, to help with garbage collection. If you would like to examine the namespace after the test completes, then use clear_globs=False.

  compileflags gives the set of flags that should be used by the Python compiler when running the examples. If not specified, then it will default to the set of future-import flags that apply to globs.

  The output of each example is checked using the `DocTestRunner`'s output checker, and the results are formatted by the `DocTestRunner.report_*` methods.

`summarize`( | [verbose])

  Print a summary of all the test cases that have been run by this DocTestRunner, and return a tuple "`(failure_count, test_count)`".

  The optional verbose argument controls how detailed the summary is. If the verbosity is not specified, then the `DocTestRunner`'s verbosity is used.