pytest-markdown-console 0.0.1.dev1

A pytest extension to test console code blocks in markdown files.

A pytest extension to test console code blocks in Markdown files

A minimal pytest extension to test console blocks in your Markdown documentation. Works on Linux, macOS, and Windows.

Installation

In your project, run:

pip install pytest-markdown-console

If you are using uv, install it as a development dependency:

uv add --dev pytest-markdown-console

The plugin self-registers and will run in each subsequent pytest invocation.

How does it work?

Each console code block in Markdown files collected by the plugin generates a test case.

The test runs each command in the block and compares its actual output to the expected output written in the block.

For example:

```console
$ uv run myapp.py
Hello, world!
```

This creates a passing test case if your app actually prints "Hello, world!".

Signal expected failures

Sometimes you want to illustrate expected failures. To convey this to both the reader and the plugin, place a # Error: comment at the end of the failing command, or on the line preceding it:

```console
$ uv run myapp.py --bad_option  # Error: this will fail
$ # Error: this will also most definitely fail
$ uv run myapp.py --still_bad
```

Filter by platform

To restrict a test to specific platforms, use the platform: directive:

```console platform:linux,macos
$ echo "This will generate a test case on Linux and macOS"
```

To exclude a platform, prefix its name with !:

```console platform:!windows
$ echo "This will not generate a test case on Windows"
```

Change the working directory

By default, all commands run in the same directory as the Markdown file. To use a different directory, use the cwd: directive:

```console cwd:../
$ uv run myapp.py
...
```

Relative paths are resolved relative to the Markdown file's location.

Controlling which tests run

By default, all tests run including those generated by this plugin. To exclude them:

pytest -p no:markdown-console

To run only the plugin's tests:

pytest -m markdown_console

Why this extension?

This plugin makes your documentation testable — specifically console blocks — within the same pytest suite you use for the rest of your code.

It is similar to pytest-markdown-docs, which works on Python code blocks, and follows similar conventions.

Other tools can test console blocks in Markdown files, but we couldn't find one that is simple, supports Windows, integrates with pytest, and requires no boilerplate.

Does it make sense to test console blocks?

Testing console blocks is admittedly niche. They often contain installation instructions or shell-specific commands that don't translate across platforms.

However, if you are building a CLI app, you likely already showcase commands and their output in your docs. Testing those snippets ensures they stay up-to-date.

Launching a Python app on Windows, Linux, or macOS is the same one-liner when using uv. That is the sweet spot motivating this small plugin.