pytest-markdown-docs

0.9.2 · active · verified Wed Apr 15

pytest-markdown-docs is a pytest plugin that collects and executes Python code blocks found within Markdown files and Python docstrings as tests. It allows developers to ensure that documentation examples remain correct and up-to-date by integrating them into the standard pytest test suite. The library is currently at version 0.9.2 and follows an active, though not strictly fixed, release cadence.

Warnings

gotcha The plugin's test collection is only activated when the `--markdown-docs` command-line flag is explicitly passed to pytest. Simply installing the plugin is not enough.
Fix: Always run `pytest --markdown-docs` to enable markdown/docstring test collection.
gotcha Traceback line numbers for code within docstring-inlined snippets or continuation blocks might be inaccurate or confusing compared to standard Python files, as the plugin's internal handling of source locations is 'hacky'.
Fix: Be aware of this limitation when debugging failures in such blocks. Focus on the code content rather than exact line numbers in these specific cases.
gotcha Assertions within Markdown code fences are not rewritten by pytest to provide rich, detailed comparison diffs like they are for standard Python test functions.
Fix: Ensure your assert statements are clear. For complex data structures, consider explicitly printing values before the assertion to aid debugging.
breaking Older versions of `pytest-markdown-docs` (before 0.9.x) might have had compatibility issues with `pytest > 7.0.0` due to internal API changes in pytest.
Fix: Upgrade `pytest-markdown-docs` to version 0.9.0 or newer to ensure compatibility with `pytest` versions 7.0.0 and above. The current version (0.9.2) explicitly requires `pytest>=7.0.0`.
gotcha To prevent a specific Python code fence from being collected as a test, add `notest` to its info string (e.g., ````python notest````). Otherwise, any `python`, `python3`, or `py` code fence will be treated as a test.
Fix: Use the `notest` info string for examples or snippets that should not be executed as part of your test suite.

Install

pip install pytest-markdown-docs Install stable version

Quickstart

To use pytest-markdown-docs, install it and then simply invoke pytest with the `--markdown-docs` flag, pointing it to your Markdown files or Python modules containing docstrings. The plugin will discover and run code fences tagged as `python`, `python3`, or `py`.

import pytest

# Save this content as README.md
readme_content = """
# My Project

This is a sample project with a Python code example.

```python
def add(a, b):
    return a + b

assert add(1, 2) == 3
assert add(-1, 1) == 0
```

Another block that should be skipped:
```python notest
print('This code should not run as a test')
assert False # This would fail if not skipped
```
"""

with open('README.md', 'w') as f:
    f.write(readme_content)

# To run this, save the above content as a Python file (e.g., quickstart.py),
# then execute from your terminal:
# python -c "import quickstart" # Creates README.md
# pytest --markdown-docs README.md
#
# Expected output will show 2 passed tests from the first code block.

view raw JSON →