Skip to content
Tutorials Center
My learning

Topics

Python Reference ยท Standard Library: Concurrency, Network and Tools

The doctest module

Reference for Python's doctest module: write >>> examples in docstrings, run them with testmod, ELLIPSIS and NORMALIZE_WHITESPACE flags, exceptions and pitfalls.

doctest finds interactive-session examples inside docstrings, runs them and compares the printed result with what the docstring says. A line that starts with >>> is code to run; the lines under it, up to a blank line or the next >>>, are the exact output expected.

It does two jobs at once: your documentation shows real usage, and that usage is checked so the docs cannot silently go stale. It suits small, clear examples. For edge cases, fixtures and many assertions, use unittest or pytest instead.

Python
def double(n):
    """Return n times two.

    >>> double(4)
    8
    """
    return n * 2

if __name__ == "__main__":
    import doctest
    doctest.testmod()       # prints nothing when every example passes

Try it

Python Passing and failing examples

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Exceptions, ELLIPSIS and whitespace

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
doctest.testmod(m=None, verbose=False, optionflags=0, raise_on_error=False)
doctest.testfile(filename, module_relative=True, verbose=False, optionflags=0)
doctest.run_docstring_examples(f, globs, verbose=False, name='NoName', optionflags=0)
Name Description
m Module to test; defaults to __main__.
verbose Print every example, not just failures.
optionflags Flags combined with `
raise_on_error Raise an exception at the first failure instead of reporting.
filename A text file (for example a README) containing >>> examples.

Return value: TestResults(failed, attempted), a named tuple. From a command line, python -m doctest -v file.py runs the examples in a file.

Common option flags:

Flag Effect
ELLIPSIS ... in the expected output matches any text.
NORMALIZE_WHITESPACE Runs of spaces, tabs and newlines compare as equal.
IGNORE_EXCEPTION_DETAIL Compares only the exception type, not its message.
SKIP Skips the example.
DONT_ACCEPT_TRUE_FOR_1 Distinguishes True from 1.

Flags can also be set per example with a comment such as # doctest: +ELLIPSIS.

Usage notes

  • Output is compared as text, exactly. A trailing space, a different repr or dictionary printed in a different order is a failure.
  • Blank lines end the expected output. To expect an empty line, write <BLANKLINE>.
  • Exceptions: write the Traceback (most recent call last): header, then ..., then the final ExceptionType: message line. Only that last line and the header are compared; the stack lines are ignored.
  • Unstable output (memory addresses, set ordering, dates, random numbers) makes bad doctests. Print a sorted list or an == comparison that returns True.
  • Statements that print nothing (assignments, imports) need no expected output.
  • Multi-line statements continue with ... at the start of each following line.
  • Backslashes in docstrings need a raw docstring (r"""..."""), or doubled, because the string is interpreted before doctest sees it.
  • Each docstring starts with a fresh copy of the module's globals, so examples in different functions do not share variables, but examples inside one docstring do.
  • Great for documentation, weak as a test suite: failures stop being obvious when many examples fill a docstring, and fixtures are awkward.
  • pytest can run doctests with --doctest-modules.