doctest

Doctest is a testing framework in Python's standard library that extracts and executes small interactive Python examples embedded in code documentation. It reads docstrings, finds blocks that look like an interactive session (lines starting with >>> and subsequent output lines), runs the code, and checks that the actual output matches the expected output in the docstring. The goal is to ensure that examples in documentation stay correct and serve as lightweight tests for the public API.

Usage is centered on running tests against modules or files. The doctest module provides functions such as testmod() to run tests in a module and testfile() to test a standalone file. Tests can also be collected into suites and executed as part of a larger test run. From the command line, you can run tests with python -m doctest <module> -v to see detailed results. A typical example uses the interactive prompt >>> to indicate input, followed by the expected output. Doctest supports features such as ellipsis matching and whitespace normalization through optional flags that control how outputs are compared. It can be integrated into test suites and can report failures with details to help diagnose mismatches.

Limitations and practice: Doctest is best for straightforward, text-based outputs and examples that are stable. It can be brittle if documentation changes or if outputs depend on non-deterministic factors. For more comprehensive testing, doctest is often used alongside other testing frameworks such as unittest or pytest. It emphasizes documentation as a source of tests and can serve as living documentation when used with care.