pytest-doctestplus

What it is and what it does

pytest-doctestplus extends pytest's built-in doctest support to handle example code in Python docstrings and standalone documentation files (RST, Markdown, TeX). It solves the problem of testing documentation examples that may have floating-point precision variations, need to skip certain tests, or depend on remote data—situations where standard doctests fail or require workarounds.

The plugin integrates directly into pytest's collection and execution pipeline. You enable it via command-line flags (--doctest-plus, --doctest-rst, --doctest-ufunc) or configuration, then write doctests using standard Python doctest syntax plus optional directives like +FLOAT_CMP for approximate numeric comparison, +IGNORE_WARNINGS to suppress warnings, or +SHOW_WARNINGS to display them. It respects pytest's standard doctest options and can work alongside pytest-remotedata for tests that fetch external resources.

Use it for:

• Test code examples in Sphinx documentation to ensure they remain correct as the library evolves.
• Validate Markdown README files and tutorials contain working Python code snippets.
• Compare floating-point numerical results in doctests without brittle string matching on roundoff digits.
• Skip doctests in specific classes or functions during CI without removing the documentation examples.
• Test NumPy ufunc docstrings that contain example code requiring special handling.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that runs doctests in Python docstrings and documentation files (reStructuredText, Markdown, TeX) with advanced features like floating-point comparison and remote data handling.

Yes. This is a mature, actively maintained plugin (Production/Stable) with low install friction and no known vulnerabilities. Install it if you write documentation with code examples and want to ensure those examples stay correct. The floating-point comparison and remote-data features address real pain points in scientific and technical documentation testing.

Install

pytest-doctestplus on PyPI

pip install pytest-doctestplus

uv add pytest-doctestplus

poetry add pytest-doctestplus

Installing pytest-doctestplus

Before you install

Low friction install with only pytest and packaging as runtime dependencies. Actively maintained with recent commits and stable releases; last update 200 days ago with ongoing development.

License in practice

BSD license (permissive) means you can use this freely in commercial and open-source projects with minimal restrictions.

Quickstart

pip install pytest-doctestplus

# In your test file or docstring:
# >>> 1.0 / 3.0  # doctest: +FLOAT_CMP
# 0.333333333333333311

# Run with: pytest --doctest-plus --doctest-glob '*.md'

Requires Python 3.10 or later.

Verify before relying

• Whether the plugin handles all edge cases in Markdown fenced code blocks consistently across different markdown parsers.
• Performance impact when running doctests on very large documentation sets or projects with thousands of examples.

Package facts

Evidence: pytest_doctestplus-1.7.1-py3-none-any.whl

Keywords: doctest, rst, pytest, py.test

Tags

More Utilities packages