Testing Docstring Examples with doctest

Intermediate

A useful example in a docstring can do two jobs: explain how a function is meant to behave and let Python check that the example still works. The built-in doctest module recognizes interactive-console examples, executes them, and compares the displayed result with the expected text. This lesson focuses on that documentation-first testing style; unittest.TestCase, fixture setup, and mocks already have their own lessons.

Turn examples into executable contracts

Write a small example as if you were using the interactive Python prompt. Start input lines with >>>, then place the exact expected output on the following line. Keep the example close to the function's docstring so a reader can discover it with help() and run it as a test. Examples should describe stable behavior that users care about, rather than incidental implementation details.

The first example places three input/output pairs in shipping_total()'s docstring. doctest.testmod() scans the current module for docstrings and runs those examples. A successful non-verbose run is quiet; verbose=True is helpful while learning because it shows each check and its result. The returned result has a failed count, so the surrounding script can also make success explicit.

Run docstring examples with testmod

For an ordinary module, the common entry point is doctest.testmod(). Put it behind if __name__ == "__main__": when the test should run only when the file is executed directly. You can also ask the standard-library command-line runner to test a file: python -m doctest -v shipping.py. Use -v for details. Importing a file for testing executes its top-level code, so keep module imports free of unwanted side effects.

Doctest examples run in a copy of a module's global namespace for each docstring, which helps prevent one docstring's temporary names from leaking into another. Keep each example understandable on its own and avoid depending on hidden order between examples.

Match returned values, printed output, and exceptions

An expression at the interactive prompt displays its representation: a returned string normally appears with quotes. A function that calls print() instead produces its printed text without those quotes. The expected output must match the relevant display; confusing return and print is a common reason an otherwise correct example fails.

Doctest can check expected exceptions too. Include the Traceback (most recent call last): heading, optionally use ... for the traceback stack, and finish with the exception type and message. The traceback stack itself is ignored, but the exception type and detail are compared by default. Avoid depending on full file paths, line numbers, memory addresses, or other output that varies across machines or versions.

def status():
    """Return the current status.

    >>> status()
    ?
    """
    return "ready"

import doctest
result = doctest.testmod()
assert result.failed == 0

Test examples in a documentation text file

Interactive examples do not have to live in a Python source file. doctest.testfile() can check console examples in a plain-text tutorial or README. This is useful when documentation contains short, copyable snippets. Be explicit about file encoding, and pass module_relative=False when supplying a direct filesystem path rather than a path relative to a module.

For a project, a command such as python -m doctest -v guide.txt runs the examples in a text file. Doctest's expected output format is intentionally simple: it is not a general parser for every shell transcript, traceback, or formatting convention. If an example needs setup that is too complex to understand, use a dedicated test with explicit setup rather than hiding that complexity in the documentation.

import doctest
from pathlib import Path
from tempfile import TemporaryDirectory
with TemporaryDirectory() as directory:
    path = Path(directory) / "guide.txt"
    path.write_text(">>> 2 + 2\n4\n", encoding="utf-8")
    result = doctest.?(str(path), module_relative=False)
    assert result.failed == 0

Integrate doctest with unittest when useful

A project can keep examples in docstrings and still include them in a broader unittest run. doctest.DocTestSuite() builds a test suite from a module's docstring examples. This is an integration point, not a replacement for unittest.TestCase: use ordinary unit tests for complex setup, multiple assertions, detailed diagnostics, or behavior that is awkward to express as a short console transcript.

import doctest
import io
import sys
import unittest

def sample():
    """A tiny example.

    >>> sample()
    'done'
    """
    return "done"

suite = doctest.?(sys.modules[__name__])
result = unittest.TextTestRunner(stream=io.StringIO()).run(suite)
assert result.wasSuccessful()

Know when doctest is not enough

Doctest is strongest when a concise example is itself useful documentation: a function's normal inputs, return values, and a small number of stable edge cases. It can become brittle when output contains unstable representations, depends on external state, or requires a long setup. Don't loosen output matching just to make a fragile example pass; simplify the example or use a more suitable unit test. Keep pure behavior real, and isolate external collaborators only when that boundary is what the test needs to control.

def describe_count(count):
    """Return a short description.

    >>> print(describe_count(3))
    ?
    """
    return f"{count} items"

import doctest
result = doctest.testmod()
assert result.failed == 0

def parse_age(value):
    """Reject negative ages.

    >>> parse_age(-1)
    Traceback (most recent call last):
        ...
    ?
    """
    if value < 0:
        raise ValueError("age must be non-negative")
    return value

import doctest
result = doctest.testmod()
assert result.failed == 0

import doctest

def ping():
    """Return a fixed response.

    >>> ping()
    'pong'
    """
    return "pong"

result = doctest.testmod(verbose=?)
assert result.attempted == 1
assert result.failed == 0