Python > Testing in Python > Doctests > Running Doctests

Running Doctests in Python

This guide demonstrates how to run doctests embedded within Python code using the doctest module. Doctests are a simple and effective way to test your code by embedding example usages directly within docstrings. This makes your documentation executable and ensures that your code behaves as documented.

What are Doctests?

Doctests are a form of unit testing in Python that allows you to embed test cases directly within the docstrings of your functions, classes, or modules. The doctest module then parses these docstrings, executes the embedded code, and verifies that the actual output matches the expected output you've provided. They are a lightweight way to test and document your code simultaneously.

Example Doctest

This code defines a simple add function with a docstring that includes doctests. The lines starting with >>> represent the Python code to be executed. The line immediately following is the expected output. The if __name__ == '__main__': block ensures that the doctests are run when the script is executed directly. doctest.testmod() searches the current module for doctests and runs them.

def add(a, b):
    """Return the sum of a and b.

    >>> add(2, 3)
    5
    >>> add(-1, 1)
    0
    >>> add(0, 0)
    0
    """
    return a + b

if __name__ == '__main__':
    import doctest
    doctest.testmod()

Running Doctests from the Command Line

You can also run doctests from the command line using the python -m doctest command followed by the name of your Python file. This is useful for automating tests as part of a build process or continuous integration setup.

python -m doctest your_module.py

Verbose Mode

Using the -v flag (verbose mode) provides more detailed output, showing each test case that is run and whether it passed or failed. This can be very helpful for debugging failing doctests.

python -m doctest -v your_module.py

Concepts Behind the Snippet

The core concept is embedding executable documentation within the code itself. The doctest module provides the machinery to parse and execute these examples. It relies on string comparison to determine if the tests pass or fail. Therefore, output needs to be predictable.

Real-Life Use Case

Imagine you are building a library for mathematical operations. Doctests allow you to clearly demonstrate how each function should be used directly in the documentation, which also acts as verification tests. For example, if a function is designed to calculate the area of a circle and should return a precise result, you could use doctests to verify that it consistently provides accurate calculations for various inputs.

Best Practices

  • Keep doctests concise and focused on demonstrating the core functionality of the code being tested.
  • Write clear and precise expected output to avoid false negatives.
  • Use verbose mode (-v) during development to easily identify failing tests.
  • Consider using more advanced testing frameworks like pytest or unittest for more complex testing scenarios.

Interview Tip

When discussing testing strategies in an interview, mentioning doctests shows that you understand the importance of integrating documentation and testing. Explain how you would use doctests for simple functionalities and more comprehensive frameworks for complex logic.

When to Use Doctests

Doctests are best suited for:
  • Simple examples and tests within the documentation.
  • Quickly verifying the basic functionality of small functions or classes.
  • Ensuring that example usages in documentation remain accurate as the code evolves.

Memory Footprint

Doctests generally have a low memory footprint since they're executed in-place and are relatively lightweight. The primary memory usage comes from the execution of the code within the docstrings themselves.

Alternatives

Alternatives to doctests include:
  • unittest: Python's built-in unit testing framework, offering more advanced features like test suites, fixtures, and assertions.
  • pytest: A popular third-party testing framework that simplifies test discovery and execution.
  • nose: Another testing framework, though less actively maintained than pytest.

Pros of Doctests

  • Easy to write and integrate into existing code.
  • Serves as both documentation and test cases.
  • Requires no separate test files.

Cons of Doctests

  • Limited in scope and complexity compared to dedicated testing frameworks.
  • Can be difficult to maintain for large or complex projects.
  • Relies on string comparison, which can be brittle.

← Patching a Function's Return Value Simple Test Function with pytest →

FAQ

  • How do I handle exceptions in doctests?

    You can include expected exceptions in your doctests using the doctest.ELLIPSIS flag, or by using assertRaises within the doctest itself. Refer to the doctest module's documentation for details.
  • Can I ignore certain parts of the output in doctests?

    Yes, you can use the doctest.ELLIPSIS flag to match variable parts of the output. This is useful for things like memory addresses or timestamps that change between runs.