Registry / testing / pytest-markdown-docs

pytest-markdown-docs

library0.9.2pypypiunverified

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.

testing

pip install pytest-markdown-docs

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-MARKDOWN-DO

pytest-markdown-docs

testingpythonv0.9.2

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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.

Debug

Known issues

gotchaThe 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.

affects: All versions

gotchaTraceback 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.

affects: All versions

gotchaAssertions 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.

affects: All versions

breakingOlder 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`.

affects: <0.9.0

gotchaTo 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.

affects: All versions

Errors

Common errors & fixes

collected 0 items

pytest-markdown-docs did not find any Markdown files with Python code blocks or any Python docstrings configured to be tested within pytest's collection path.

fix

Ensure Markdown files are in pytest's discovery path, contain fenced code blocks with `python` or `py` language specifiers, and verify `pytest-markdown-docs` is installed and active. You might need to specify `markdown_docs_paths` in `pytest.ini` or mark docstrings with `@pytest.mark.markdown_docs`.

SyntaxError: invalid syntax

A Python code block within a Markdown file or Python docstring processed by pytest-markdown-docs contains invalid Python syntax, causing the interpreter to fail.

fix

Review the Python code within the specific Markdown code block or docstring referenced in the traceback and correct the syntax errors.

ERROR: unrecognized arguments: --md-dryrun

A command-line option specific to pytest-markdown-docs was mistyped, causing pytest to report it as an unknown argument.

fix

Correct the command-line option to its proper form, for example, change `--md-dryrun` to `--md-dry-run`, or ensure other options like `--md-collect-only` or `--md-strict` are spelled correctly.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0xff in position 0: invalid start byte

pytest-markdown-docs attempted to read a Markdown file (or another text file) that is not encoded in UTF-8 or contains characters incompatible with UTF-8 decoding.

fix

Ensure that all Markdown files and related text files are saved with UTF-8 encoding. You may need to convert the file's encoding using a text editor or a command-line tool.

Upgrade

Version history

0.9.2latest on PyPI · released Mar 23, 2026

Audit

Dependencies

pytestrequiredCore testing framework, required for plugin functionality. Requires pytest>=7.0.0.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/modal-labs/pytest-markdown-docs ↗

packagehttps://pypi.org/project/pytest-markdown-docs/ ↗