pytest-codeblocks

What it is and what it does

pytest-codeblocks is a pytest plugin that treats code blocks in markdown files—particularly READMEs—as executable test cases. It discovers blocks marked with python, sh, bash, or zsh syntax highlighting and runs them through pytest, letting you verify that documentation examples actually work.

The plugin supports marking code blocks with pytest directives (skip, skipif, xfail) via HTML comments, merging fragmented examples across multiple blocks, and validating expected output. This catches a common documentation debt: examples that drift out of sync with the actual codebase. It depends only on pytest and requires Python 3.10 or later.

Use it for:

• Verify that code examples in a project's README actually execute without errors.
• Catch breaking changes when refactoring by running documented usage patterns as tests.
• Validate shell command sequences and their output in installation or setup documentation.
• Ensure multi-step code examples work when split across separate markdown blocks.
• Skip or mark code blocks as expected-to-fail for examples that demonstrate error handling.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that automatically discovers and runs Python and shell code blocks from README and markdown files as test cases.

Yes. Low install friction, no security vulnerabilities, permissive MIT license, and active maintenance make this a straightforward addition to any project with documentation that includes runnable code. It solves a real problem—keeping examples in sync with code—with minimal overhead.

Install

pytest-codeblocks on PyPI

pip install pytest-codeblocks

uv add pytest-codeblocks

poetry add pytest-codeblocks

Installing pytest-codeblocks

Before you install

Low friction install with a single runtime dependency on pytest. Actively maintained with a release within the last 60 days and marked as Production/Stable.

License in practice

MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart

pip install pytest-codeblocks

# In your README.md, add code blocks with python or sh syntax highlighting
# Then run:
pytest --codeblocks

Requires Python 3.10 or later.

Verify before relying

• Whether the plugin handles edge cases like nested code blocks or complex markdown structures.
• Performance characteristics when testing large numbers of code blocks across many files.

Package facts

Evidence: pytest_codeblocks-0.18.0-py3-none-any.whl

Tags

More Testing packages