markdown-pytest¶
markdown-pytest is a pytest plugin that collects and runs Python code blocks directly from Markdown files, so your documentation examples are always tested and never go stale.
$ pytest -v README.md
README.md::test_quick_start PASSED
README.md::test_example PASSED
README.md::test_with_tmp_path PASSED
Why test your documentation?¶
Documentation examples rot. A library evolves, an API changes, someone updates the code but forgets the README — and now your users copy-paste broken examples. markdown-pytest solves this by running every Python code block in your Markdown files as a real pytest test.
Because the test markers are plain HTML comments, rendered documentation looks completely normal. Readers see clean code blocks; pytest sees a full test suite.
Features at a glance¶
Zero-config collection — install and run
pytest docs/orpytest README.md. No extra configuration needed.Code splitting — spread a single test across multiple code blocks, with prose in between, the way you would naturally write a tutorial.
Fixtures — use
tmp_path,monkeypatch,capsys, or any custom fixture fromconftest.pydirectly in your Markdown code blocks.Subtests — run independent sub-cases sharing a common setup, powered by pytest’s built-in subtests support (pytest 9+).
Hidden blocks — hide setup or assertion code inside HTML comments so readers see only the interesting part.
Subprocess isolation — run a block in a fresh Python process for tests that mutate global state or call
sys.exit().Async support — prefix a test name with
asyncto enable top-levelawaitand async fixtures.REPL / doctest mode — write blocks in interactive Python shell format (
>>> ...) and check their output.Marks — apply
xfail,skip, or any custom mark directly from the comment.
Quickstart¶
pip install markdown-pytest
Add a comment above a Python code block in any .md file:
<!-- name: test_addition -->
```python
assert 1 + 1 == 2
```
Run:
pytest README.md
That’s it. Jump to the Tutorial 1 — Your first Markdown test for a complete walkthrough.