{"id":5032,"library":"pytest-doctestplus","title":"pytest-doctestplus","description":"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.","status":"active","version":"1.7.1","language":"en","source_language":"en","source_url":"https://github.com/scientific-python/pytest-doctestplus","tags":["pytest","plugin","doctest","testing","documentation","rst","markdown","sphinx"],"install":[{"cmd":"pip install pytest-doctestplus","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core testing framework; this is a plugin for pytest.","package":"pytest","optional":false},{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false},{"reason":"Recommended for handling doctests that require remote data access.","package":"pytest-remotedata","optional":true},{"reason":"Required for the --doctest-ufunc option to include doctests in NumPy ufuncs.","package":"numpy","optional":true}],"imports":[],"quickstart":{"code":"import pytest\n\n# my_module.py\ndef greet(name):\n    \"\"\"\n    Greets the given name.\n\n    >>> greet('World')\n    'Hello, World!'\n\n    >>> greet('pytest-doctestplus') # doctest: +SKIP\n    'Hello, pytest-doctestplus!'\n    \"\"\"\n    return f'Hello, {name}!'\n\n# To run the doctests from the command line, save the above as my_module.py\n# and run pytest:\n# pytest --doctest-plus my_module.py","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or a later supported version.","message":"Python 3.9 and older versions (3.8, 3.7) are no longer supported. Ensure your environment uses Python 3.10 or newer.","severity":"breaking","affected_versions":">=1.7.0 (Python 3.9), >=1.4.0 (Python 3.8), >=1.1.0 (Python 3.7)"},{"fix":"Upgrade your pytest installation to version 8.0 or newer (e.g., `pip install -U pytest`).","message":"Compatibility with older pytest versions has been dropped. Specifically, pytest < 7 is no longer supported, and recent versions require pytest >= 8.","severity":"breaking","affected_versions":">=1.7.0 (pytest < 7), >=1.2.0 (pytest < 8)"},{"fix":"When you intend to use the advanced features of pytest-doctestplus, always use the `--doctest-plus` command-line option, and avoid `--doctest-modules`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.7.1"},{"fix":"Ensure doctest directives are used correctly according to the documentation, especially regarding expected content or lack thereof.","message":"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.","severity":"gotcha","affected_versions":"<1.6.0 (crash), >=1.6.0 (error)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}