What is the use of the "doctest" module in Python?

Question

Jayant Kumar · Accepted Answer

Table of Contents
Introduction
The doctest module in Python is a unique testing tool that allows you to embed test cases within docstrings in your code. This module validates that the examples provided in docstrings produce the expected output when the code is executed. By integrating testing directly into documentation, doctest helps ensure that code examples remain accurate and functional over time.
In this article, we'll explore the features of the doctest module, how to use it effectively, and practical examples to illustrate its application.
What Is the doctest Module?
The doctest module is a built-in Python library that allows you to write test cases as part of the docstrings in your functions and modules. These docstrings can include examples that doctest will run to verify that the code behaves as documented.
Key Features of the doctest Module

Embedded Testing: Write tests within docstrings to ensure code examples are up-to-date and accurate.
Automatic Test Extraction: Extract and run tests from docstrings automatically.
Documentation Accuracy: Keep code examples in documentation consistent with actual code behavior.
Simple Usage: Minimal setup required; integrate tests directly within the codebase.

Writing Tests with doctest
To use doctest, you write examples in the docstrings of your functions, classes, or modules. These examples are written in the interactive Python shell format.
Example: Basic Usage
import doctest

def add(a, b):
    """
    Add two numbers together.

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

# Run doctests
if __name__ == "__main__":
    doctest.testmod()

How It Works

Docstring: The add() function includes a docstring with examples of its usage.
Interactive Format: Examples are written in the format of the Python interactive shell (e.g., >>> add(2, 3)).
Validation: doctest.testmod() is used to run the tests embedded in the docstring and check that the output matches the expected results.

How doctest Works
When doctest.testmod() is called, it:

Extracts Examples: Finds examples in docstrings within the module.
Executes Examples: Runs the examples as if they were typed into the Python interactive shell.
Compares Output: Compares the actual output of the examples with the expected output in the docstrings.
Reports Results: Displays any discrepancies between expected and actual results.

Practical Examples of Using doctest
1. Testing a Function
Consider a function that computes the factorial of a number:
def factorial(n):
    """
    Compute the factorial of a number.

>>> factorial(5)
    120
    >>> factorial(0)
    1
    """
    if n == 0:
        return 1
    else:
        return n * factorial(n - 1)

# Run doctests
if __name__ == "__main__":
    doctest.testmod()

2. Testing a Class
You can also use doctest to test classes and methods:
class Calculator:
    """
    A simple calculator class.

>>> calc = Calculator()
    >>> calc.add(5, 3)
    8
    >>> calc.subtract(10, 7)
    3
    """
    
    def add(self, a, b):
        return a + b

def subtract(self, a, b):
        return a - b

# Run doctests
if __name__ == "__main__":
    doctest.testmod()

3. Testing a Module
doctest can be used at the module level to test multiple functions or classes:
def multiply(a, b):
    """
    Multiply two numbers.

>>> multiply(2, 3)
    6
    >>> multiply(-1, 1)
    -1
    """
    return a * b

def divide(a, b):
    """
    Divide two numbers.

>>> divide(6, 3)
    2.0
    >>> divide(5, 2)
    2.5
    >>> divide(5, 0)
    Traceback (most recent call last):
        ...
    ZeroDivisionError: division by zero
    """
    return a / b

# Run doctests
if __name__ == "__main__":
    doctest.testmod()

Integrating doctest with Other Testing Tools
doctest is often used alongside other testing frameworks like unittest or pytest. While doctest provides a way to ensure examples in documentation are correct, unittest and pytest offer more extensive testing features, such as fixtures, mocks, and parameterized tests.
Example: Combining doctest with unittest
import unittest
import doctest

def add(a, b):
    """
    Add two numbers together.

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

class TestAddFunction(unittest.TestCase):
    
    def test_add(self):
        self.assertEqual(add(2, 3), 5)

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

How It Works

**doctest.testmod()**: Runs tests embedded in docstrings.
**unittest.main()**: Runs unit tests defined in the TestAddFunction class.

Conclusion
The doctest module is a valuable tool for ensuring that code examples within docstrings are accurate and up-to-date. By embedding tests directly within documentation, it helps maintain the correctness of code examples and simplifies the process of verifying functionality. While doctest is excellent for lightweight testing and documentation accuracy, it can be effectively combined with other testing frameworks for comprehensive test coverage.

What is the use of the "doctest" module in Python?

Table of Contents

Introduction

What Is the `doctest` Module?

Key Features of the `doctest` Module

Writing Tests with `doctest`

Example: Basic Usage

How It Works

How `doctest` Works

Practical Examples of Using `doctest`

1. Testing a Function

2. Testing a Class

3. Testing a Module

Integrating `doctest` with Other Testing Tools

Example: Combining `doctest` with `unittest`

How It Works

Conclusion

Similar Questions