Using the doctest Module in Python: Documentation and Testing Combined

The doctest module in Python provides a way to write tests within docstrings of functions, classes, and modules. These tests serve a dual purpose: they act as documentation examples, demonstrating how to use the code, while also serving as executable tests that can be automatically verified.

In this blog post, we will explore the doctest module in Python, learn how to write tests using docstrings, and see how to run and interpret the test results.

Writing Doctests

Doctests are written within the docstrings of functions, classes, or modules using a special format. They consist of interactive Python code snippets that demonstrate the usage of the code and the expected output.

Let’s look at an example:

def add_numbers(a, b):
    """
    Add two numbers and return the result.

    >>> add_numbers(2, 3)
    5

    >>> add_numbers(-1, 1)
    0
    """
    return a + b

In this example, we have a add_numbers() function that takes two numbers as arguments and returns their sum. The doctest examples are included within the docstring.

Each example consists of the Python code to execute and the expected output. In this case, we have two examples that demonstrate the addition of two numbers.

Running Doctests

Python provides a built-in way to run the doctests using the doctest module. The doctest module automatically discovers doctests in the docstrings and executes them.

You can run the doctests by executing the module or using the doctest.testmod() function.

Let’s take a look at an example:

import doctest

def add_numbers(a, b):
    """
    Add two numbers and return the result.

    >>> add_numbers(2, 3)
    5

    >>> add_numbers(-1, 1)
    0
    """
    return a + b

if __name__ == "__main__":
    doctest.testmod()

In this code, we import the doctest module and include the doctest.testmod() function at the end of the module. When you execute this module, the doctests will be discovered and run.

Interpreting Doctest Results

After running the doctests, the doctest module provides a summary of the test results. It informs you about the number of tests run, the number of failures, and any unexpected output encountered.

A successful doctest run will not produce any output. If a failure occurs, the doctest module displays detailed information about the test that failed.

Let’s consider an example where a doctest fails:

import doctest

def add_numbers(a, b):
    """
    Add two numbers and return the result.

    >>> add_numbers(2, 3)
    5

    >>> add_numbers(-1, 1)
    1  # Incorrect output, should be 0
    """
    return a + b

if __name__ == "__main__":
    doctest.testmod()

In this code, the second doctest has an incorrect output. When you run this code, the doctest module will indicate the failure with a detailed error message:

**********************************************************************
File "example.py", line 11, in __main__.add_numbers
Failed example:
    add_numbers(-1, 1)
Expected:
    0
Got:
    1
**********************************************************************
1 items had failures:
   2 in __main__.add_numbers
***Test Failed*** 1 failures.

The failure message clearly states the failed example, the expected output (0), and the actual output (1). This helps identify the issue and correct the code.

Benefits of Using Doctests

Using the doctest module in Python offers several benefits:

1. Documentation and Testing in One: Doctests serve as documentation examples, illustrating how to use the code effectively. At the same time, they act as executable tests, ensuring the code behaves as expected.
2. Easy to Write and Maintain: Doctests are written within docstrings, making them easy to write, update, and maintain. They stay synchronized with the code, eliminating the need to maintain separate test files.
3. Code Coverage: Doctests provide a way to ensure code coverage. By including examples for different scenarios and edge cases, you can verify that your code handles all expected inputs and outputs.
4. Integration with Test Runners: Doctests can be integrated with popular Python test runners, such as unittest and pytest, allowing you to run all your tests together and obtain comprehensive test results.

Guidelines for Writing Effective Doctests

To write effective doctests, consider the following guidelines:

1. Keep Examples Concise: Keep the examples within the docstrings concise and focused. Each example should demonstrate a specific functionality or behavior.
2. Cover Different Scenarios: Include examples that cover different scenarios, edge cases, and error conditions. This ensures comprehensive testing of the code.
3. Include Expected Outputs: Clearly specify the expected output in the doctest examples. This makes it easy to identify failures and verify the correctness of the code.
4. Avoid Side Effects: Doctests should not have any side effects, such as modifying global variables or writing to files. They should be self-contained and independent.

Conclusion

In this blog post, we explored the doctest module in Python and learned how to write tests within docstrings. We saw how to run the doctests and interpret the test results.

By leveraging the doctest module, you can create self-contained and executable tests that act as documentation examples. This helps improve code readability, maintainability, and reliability.

Remember to write concise and comprehensive examples, covering different scenarios and edge cases. Regularly run the doctests to ensure the code remains correct as you make updates.

We hope you found this blog post informative and that it encourages you to adopt the doctest module in your Python projects.

If you have any questions or need further assistance, please let us know. Happy testing with the doctest module in Python!