pydoc > doctest

man perldoc info pydoc3 ri search

Help on module doctest:

📘 NAME

doctest – Module doctest — a framework for running examples in docstrings.

🚀 Quick Reference

Use Case	Command / Code	Description
Run doctests in a module	python M.py -v	Execute module and verify docstring examples, verbose output
Run doctests programmatically	doctest.testmod()	Test all docstrings in the current module
Convert docstrings to script	doctest.script_from_examples(s)	Turn doctest text into a Python script
Test a single file	doctest.testfile(filename)	Run doctests from an external file
Integrate with unittest	doctest.DocTestSuite()	Create a unittest suite from doctests
Debug a specific doctest	doctest.debug(module, name)	Drop into debugger for a failing test
Customize comparison	ELLIPSIS, NORMALIZE_WHITESPACE etc.	Option flags to relax output matching

📖 MODULE REFERENCE

https://docs.python.org/3.10/library/doctest.html

The following documentation is automatically generated from the Python source files. It may be incomplete, incorrect or include features that are considered implementation detail and may vary between Python implementations. When in doubt, consult the module reference at the location listed above.

📄 DESCRIPTION

In simplest use, end each module M to be tested with:

def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()

Then running the module as a script will cause the examples in the docstrings to get executed and verified:

python M.py

This won't display anything unless an example fails, in which case the failing example(s) and the cause(s) are printed to stdout (why not stderr? because stderr is a lame hack <0.2 wink>), and the final line of output is "Test failed.".

Run it with the -v switch instead:

python M.py -v

and a detailed report of all examples tried is printed to stdout, along with assorted summaries at the end.

You can force verbose mode by passing verbose=True to testmod, or prohibit it by passing verbose=False. In either of those cases, sys.argv is not examined by testmod.

There are a variety of other ways to run doctests, including integration with the unittest framework, and support for running non-Python text files containing doctests. There are also many ways to override parts of doctest's default behaviors. See the Library Reference Manual for details.

📦 CLASSES

🗂️ DebugRunner (inherits DocTestRunner)

Run doc tests but raise an exception as soon as there is a failure. If an unexpected exception occurs, an UnexpectedException is raised. It contains the test, the example, and the original exception.

• report_failure(self, out, test, example, got) — Report that the given example failed.
• report_unexpected_exception(self, out, test, example, exc_info) — Report that the given example raised an unexpected exception.
• run(self, test, compileflags=None, out=None, clear_globs=True) — Run the examples in test, and display the results using the writer function out. The examples are run in the namespace test.globs. If clear_globs is true (default), this namespace will be cleared after the test runs. compileflags sets flags for the Python compiler. Output checked via check_output.

Methods inherited from DocTestRunner:

• __init__(self, checker=None, verbose=None, optionflags=0) — Create a new test runner. Optional checker is an OutputChecker. verbose prints lots if True, only failures if False. optionflags controls output comparison.
• merge(self, other) — Backward compatibility cruft to maintain doctest.master.
• report_start(self, out, test, example) — Report that the test runner is about to process the given example (only if verbose=True).
• report_success(self, out, test, example, got) — Report successful example (only if verbose=True).
• summarize(self, verbose=None) — Print a summary of all test cases run, return (f, t) tuple.

📦 DocTest (object)

A collection of doctest examples to be run in a single namespace. Attributes: examples, globs, name, filename, lineno, docstring.

• __eq__(self, other) — Return self==value.
• __hash__(self) — Return hash(self).
• __init__(self, examples, globs, name, filename, lineno, docstring) — Create new DocTest with given examples. Globals initialized with a copy of globs.
• __lt__(self, other) — Return self<value.
• __repr__(self) — Return repr(self).

⚠️ DocTestFailure (Exception)

A DocTest example has failed in debugging mode. Attributes: test (DocTest object), example (Example object that failed), got (actual output).

• __init__(self, test, example, got) — Initialize self.
• __str__(self) — Return str(self).

🔍 DocTestFinder (object)

Extracts DocTests from a given object’s docstring and its contained objects. Works with modules, functions, classes, methods, staticmethods, classmethods, properties.

• __init__(self, verbose=False, parser=<DocTestParser>, recurse=True, exclude_empty=True) — Create new finder. parser factory for DocTest objects. recurse controls whether to search contained objects. exclude_empty controls whether empty docstrings are included.
• find(self, obj, name=None, module=None, globs=None, extraglobs=None) — Return list of DocTests defined by obj and its contained objects. module provides module context; if None attempts auto-detection. globs and extraglobs merge for test globals.

🔧 DocTestParser (object)

Parses strings containing doctest examples.

• get_doctest(self, string, globs, name, filename, lineno) — Extract all examples from string into a DocTest object.
• get_examples(self, string, name='<string>') — Return list of Example objects from string. Line numbers 0-based.
• parse(self, string, name='<string>') — Divide string into examples and text, return list of alternating Examples and strings. Line numbers 0-based.

🏃 DocTestRunner (object)

Runs DocTest test cases and accumulates statistics. run returns (f, t). summarize prints summary and returns aggregated (f, t).

• __init__(self, checker=None, verbose=None, optionflags=0) — Create new runner. checker is OutputChecker, verbose controls verbosity, optionflags controls comparison.
• merge(self, other) — Backward compatibility cruft.
• report_failure(self, out, test, example, got) — Report failed example.
• report_start(self, out, test, example) — Report start of example processing (if verbose).
• report_success(self, out, test, example, got) — Report successful example (if verbose).
• report_unexpected_exception(self, out, test, example, exc_info) — Report unexpected exception.
• run(self, test, compileflags=None, out=None, clear_globs=True) — Run examples in test. compileflags for Python compiler, out writer function (default sys.stdout.write), clear_globs clears namespace after run.
• summarize(self, verbose=None) — Print summary, return (failed, tried).

📝 Example (object)

A single doctest example with source, want (expected output), exc_msg, lineno, indent, options.

• __eq__(self, other) — Return self==value.
• __hash__(self) — Return hash(self).
• __init__(self, source, want, exc_msg=None, lineno=0, indent=0, options=None) — Initialize self.

✅ OutputChecker (object)

Checks whether actual output matches expected output. Methods: check_output returns True if match, output_difference returns string describing differences.

• check_output(self, want, got, optionflags) — Return True iff got matches want according to option flags.
• output_difference(self, example, got, optionflags) — Return description of differences between expected and actual output.

⚠️ UnexpectedException (Exception)

A DocTest example encountered an unexpected exception. Attributes: test, example, exc_info.

• __init__(self, test, example, exc_info) — Initialize self.
• __str__(self) — Return str(self).

🔧 FUNCTIONS

• DocFileSuite(*paths, **kw) — A unittest suite for one or more doctest files. Supports module_relative, package, setUp, tearDown, globs, optionflags, parser, encoding.
• DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, **options) — Convert doctest tests for a module to a unittest test suite. Supports setUp, tearDown, globs, optionflags.
• debug(module, name, pm=False) — Debug a single doctest docstring. Provide module and object name.
• debug_src(src, pm=False, globs=None) — Debug a single doctest docstring from source string src.
• register_optionflag(name) — Register a new option flag.
• run_docstring_examples(f, globs, verbose=False, name='NoName', compileflags=None, optionflags=0) — Test examples in the given object's docstring using globs as globals.
• script_from_examples(s) — Extract script from text with examples. Example input converted to code, output to comments.
• set_unittest_reportflags(flags) — Sets the unittest option flags. Only reporting flags allowed.
• testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=<DocTestParser>, encoding=None) — Test examples in the given file. Return (#failures, #tests). Supports many optional arguments for path interpretation, globals, verbosity, option flags, etc.
• testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False) — Test examples in docstrings reachable from module m (or current module). Also tests from m.__test__ dict. Returns (#failures, #tests). Supports name, globs, extraglobs, verbose, report, optionflags, raise_on_error, exclude_empty.
• testsource(module, name) — Extract the test sources from a doctest docstring as a script.

📈 DATA

• COMPARISON_FLAGS = 63
• DONT_ACCEPT_BLANKLINE = 2
• DONT_ACCEPT_TRUE_FOR_1 = 1
• ELLIPSIS = 8
• FAIL_FAST = 1024
• IGNORE_EXCEPTION_DETAIL = 32
• NORMALIZE_WHITESPACE = 4
• REPORTING_FLAGS = 1984
• REPORT_CDIFF = 128
• REPORT_NDIFF = 256
• REPORT_ONLY_FIRST_FAILURE = 512
• REPORT_UDIFF = 64
• SKIP = 16
• __all__ = ['register_optionflag', 'DONT_ACCEPT_TRUE_FOR_1', ...]
• __docformat__ = 'reStructuredText en'
• __test__ = {'_TestClass': <class 'doctest._TestClass'>, 'blank lines': ...}

📁 FILE

/usr/lib/python3.10/doctest.py

📘 NAME 🚀 Quick Reference 📖 MODULE REFERENCE 📄 DESCRIPTION 📦 CLASSES 🔧 FUNCTIONS 📈 DATA 📁 FILE