pytest-doctestplus

1.7.1 · active · verified Sun Apr 12

pytest-doctestplus is a pytest plugin that extends the standard Python doctest functionality with advanced features for testing example code in Python docstrings, reStructuredText (.rst), Markdown (.md), and TeX (.tex) files. It is currently at version 1.7.1 and maintains a consistent release cadence with new features, bug fixes, and compatibility updates for Python and pytest versions.

Warnings

breaking Python 3.9 and older versions (3.8, 3.7) are no longer supported. Ensure your environment uses Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or a later supported version.
breaking Compatibility with older pytest versions has been dropped. Specifically, pytest < 7 is no longer supported, and recent versions require pytest >= 8.
Fix: Upgrade your pytest installation to version 8.0 or newer (e.g., `pip install -U pytest`).
gotcha Using pytest's built-in `--doctest-modules` option will override pytest-doctestplus's functionality, even if `doctest_plus = enabled` is configured. Always use `--doctest-plus` to activate this plugin's features.
Fix: When you intend to use the advanced features of pytest-doctestplus, always use the `--doctest-plus` command-line option, and avoid `--doctest-modules`.
gotcha The `__doctest_requires__` module-level variable can cause unexpected test skipping if dependencies are not met or if the wildcard patterns are incorrectly defined. Ensure correct module availability and pattern matching.
Fix: Ensure that the required modules are importable. If encountering unexpected skips, verify the `__doctest_requires__` definition. Version 1.7.1 fixed a bug where constraints were not correctly handled.
gotcha Doctest directives with content that should not have any (e.g., `.. doctest-skip::` without further indented content) previously caused crashing Sphinx builds. While fixed in 1.6.0, using such directives incorrectly will now result in an error.
Fix: Ensure doctest directives are used correctly according to the documentation, especially regarding expected content or lack thereof.

Install

pip install pytest-doctestplus Install stable version

Quickstart

To quickly test doctests using pytest-doctestplus, place your doctests in docstrings or .rst files. Then, simply invoke pytest with the `--doctest-plus` flag. This example shows a simple function with a doctest and how to run it, including a skipped test using a doctest directive.

import pytest

# my_module.py
def greet(name):
    """
    Greets the given name.

    >>> greet('World')
    'Hello, World!'

    >>> greet('pytest-doctestplus') # doctest: +SKIP
    'Hello, pytest-doctestplus!'
    """
    return f'Hello, {name}!'

# To run the doctests from the command line, save the above as my_module.py
# and run pytest:
# pytest --doctest-plus my_module.py

view raw JSON →