Various Ways for Executing Doctests in Python

Executing Doctests in Python: A Comprehensive Guide

Doctest is a module in the Python Standard Library that enables you to write tests within the documentation of your code—typically inside docstrings. These tests look like interactive Python sessions (as if they were run in a Python shell), and the doctest module verifies that the output matches the expected result. While doctests are generally simpler than unit tests written with unittest or pytest, they are powerful for checking that code examples in documentation remain correct over time.

This guide explores the various ways to execute doctests in Python, from running them via the command line to embedding them in code and running them programmatically.

---

Methods for Executing Doctests

There are several ways to run doctests, depending on your workflow and goals. Below, we cover each method in detail.

1. Running Doctests Using the Command Line

This is the simplest way to run all doctests defined in a file:

python -m doctest -v your_script.py

Explanation:

-m doctest: Invokes Python’s doctest module. -v: Enables verbose mode, which prints out each test and result. This method will search for docstrings in your_script.py and execute the examples they contain. If any of the outputs don't match the expected results, it will raise an error.

Pros:

No need to modify your script. Easily integrates into CI pipelines. Cons:

Cannot specify individual functions. Limited flexibility for dynamic test environments.

2. Embedding doctest.testmod() in Your Script

You can embed doctest execution directly into the script itself, typically inside a main block:

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

You can also enable verbose mode:

doctest.testmod(verbose=True)

Explanation:

testmod() automatically finds all doctests in functions, classes, and module-level docstrings. This method is ideal for scripts that should test themselves when executed directly. Pros:

Self-contained testing. Immediate feedback during script development. Cons:

May not suit production environments. Requires execution of the script to run the tests.

3. Using doctest.testfile()

If you store your doctests in a separate .txt or .rst file (commonly used for documentation), you can test them with doctest.testfile():

if __name__ == "__main__":
    import doctest
    doctest.testfile("README.txt", verbose=True)

This is particularly useful for testing code examples in documentation files.

Pros:

Separates test logic from implementation. Good for literate programming and educational material. Cons:

Harder to keep examples synchronized with code changes.

4. Using doctest.run_docstring_examples()

For advanced use cases, or when you want to run doctests on specific objects (rather than all functions in a module), use run_docstring_examples():

import doctest

def square(n):
    """
    >>> square(2)
    4
    >>> square(-3)
    9
    """
    return n * n

doctest.run_docstring_examples(square, globals(), verbose=True) This method is useful in interactive environments like Jupyter Notebooks, or for manually running selected tests.

Pros:

Fine-grained control. Works well with individual functions and in dynamic contexts. Cons:

Less automatic than testmod() or command-line execution.

5. Running Doctests in Jupyter Notebooks

Although Jupyter Notebooks do not automatically support doctests, you can still use them. Simply write a function with a doctest in its docstring and then run:

import doctest
doctest.run_docstring_examples(your_function, globals(), verbose=True)```
Some third-party tools like ipython_doctest can also help, but they're not standard.

### 6. Using pytest to Run Doctests
If you're using pytest as your test runner, you can configure it to collect and run doctests:
```sh

Install pytest if not already installed:
pip install pytest
Run pytest with the --doctest-modules flag:
pytest --doctest-modules your_script.py

Pros:

Integrates doctests into broader test suites. Produces rich output and integrates with plugins. Cons:

Adds a dependency (though many developers use pytest anyway). May require additional configuration for complex setups.

7. Using unittest to Run Doctests

Python’s unittest module allows you to create test suites that include doctests. Here’s an example:

import unittest
import doctest
import your_module

def load_tests(loader, tests, ignore):
    tests.addTests(doctest.DocTestSuite(your_module))
    return tests
Then run the file with:

python -m unittest your_test_file.py

Summary of Execution Methods

Method	Description	Best Use Case
python -m doctest -v	Command-line test of all examples	Quick checks, automation
doctest.testmod()	Embedded in script	Self-testing scripts
doctest.testfile()	Run tests from external file	Testing documentation
doctest.run_docstring_examples()	Manually run specific object tests	Jupyter, dynamic testing
pytest --doctest-modules	Integrates with pytest	Large projects, plugin support
unittest integration	Combines doctest with other test types	Projects using unittest

Tips for Writing Reliable Doctests

Ensure outputs are deterministic. Avoid relying on things like dictionary key order or non-deterministic values unless absolutely necessary. Match formatting precisely. Doctest compares strings, so any mismatch in spacing or formatting causes a failure. Keep tests simple and illustrative. Doctests are not meant for exhaustive testing but for basic correctness and clarity. Use triple-quoted strings ("""...""") for function docstrings to allow multi-line examples.

Conclusion

Doctests offer a lightweight, powerful way to ensure that your documentation stays truthful and your code remains reliable. While not suitable for complex testing scenarios, they are an excellent complement to traditional testing tools. You can execute doctests in multiple ways depending on your environment, use case, and preferences—from simple command-line invocations to advanced integrations with pytest and unittest.

If you're writing code that will be read by others, especially if you're demonstrating usage through examples, consider embedding doctests. They serve not only as a guarantee of correctness but also as a valuable form of living documentation.