`doctest`

The Python doctest module provides tools for testing your code by running tests embedded in docstrings and verifying that they produce the expected results.

This module is particularly useful for ensuring that code examples in documentation stay accurate and up to date.

Here’s a quick example:

Python
      
        
      
    
>>> import doctest

>>> def add(a, b):
...     """Returns the sum of a and b.
...
...     >>> add(2, 3)
...     5
...     >>> add(-1, -5)
...     -6
...     """
...     return a + b
...

>>> doctest.testmod()
TestResults(failed=0, attempted=2)

Key Features

Embeds tests in docstrings
Validates examples against expected output
Supports interactive session documentation
Provides a way to ensure documentation accuracy

Frequently Used Classes and Functions

Object	Type	Description
`doctest.testmod()`	Function	Tests examples in a module’s docstrings
`doctest.testfile()`	Function	Tests the examples in the input file
`doctest.run_docstring_examples()`	Function	Tests examples in a specific docstring
`doctest.DocTestRunner`	Class	Runs a collection of docstring tests
`doctest.DocTestFinder`	Class	Finds tests in docstrings

Examples

Testing a single function’s docstring:

Python
      
        
      
    
>>> import doctest

>>> def subtract(a, b):
...     """Returns the difference between a and b.
...
...     >>> subtract(5, 2)
...     3
...     """
...     return a - b
...

>>> doctest.run_docstring_examples(subtract, globals())

Common Use Cases

Verifying that code examples in documentation are correct
Running lightweight tests during development
Ensuring that code changes don’t break documented functionality

Real-World Example

Suppose you have a module with several functions, each documented with examples. You want to ensure that all examples remain valid as the code evolves:

Python
      
        
      
    
>>> import doctest

>>> def multiply(a, b):
...     """Returns the product of a and b.
...
...     >>> multiply(2, 3)
...     6
...     """
...     return a * b
...

>>> def divide(a, b):
...     """Returns the quotient of a divided by b.
...
...     >>> divide(6, 2)
...     3.0
...     """
...     return a / b
...

>>> doctest.testmod()
TestResults(failed=0, attempted=2)

In this example, you use the doctest module to verify that all embedded tests runs correctly, helping ensure code reliability and documentation accuracy.

Tutorial

Python's doctest: Document and Test Your Code at Once

In this tutorial, you'll learn how to add usage examples to your code's documentation and docstrings and how to use these examples to test your code. To run your usage examples as automated tests, you'll use Python's doctest module from the standard library.

intermediate python testing

For additional information on related topics, take a look at the following resources: