There are several Python modules that integrate with pytest to run code snippets within Markdown files like README.md. These are particularly useful for ensuring documentation's code examples are always up-to-date and correct.
Here are the most prominent options:
markdown-pytest:
This pytest plugin allows you to run tests directly from Markdown files.
You mark code blocks with special HTML comments (e.g., ``) right before the code block.
It supports splitting a test across multiple code blocks with the same name and even subtests.
You can also hide initialization code from readers within comments.
pytest-markdown-docs:
Another pytest plugin that detects Python code fences (triple backticks) in Markdown files and runs them as tests.
It also supports doctests within Python docstrings.
You can configure global variables and use pytest fixtures within your Markdown snippets.
It allows for "continuation" of code blocks, so you can build up state across multiple snippets.
pytest-phmdoctest:
This plugin is based on the phmdoctest command-line tool.
It generates a pytest test file from a Markdown file, reading Python source code and expected terminal output from fenced code blocks.
It supports various directives (HTML comments) in your Markdown to control test behavior (e.g., skipping blocks, setting up/tearing down).
mktestdocs:
This library focuses on taking Python snippets from Markdown files and treating them as unit tests for pytest.
You can configure it to run all snippets in a file as a single test or each snippet independently.
There are several Python modules that integrate with pytest to run code snippets within Markdown files like README.md. These are particularly useful for ensuring documentation's code examples are always up-to-date and correct.
Here are the most prominent options:
markdown-pytest:
pytest-markdown-docs:
pytest-phmdoctest:
mktestdocs: