Metadata-Version: 2.4
Name: pytest-markdown-console
Version: 0.0.1.dev1
Summary: A pytest extension to test console code blocks in markdown files.
Author: confarg
Author-email: confarg <280620574+confarg@users.noreply.github.com>
License-Expression: MPL-2.0
Requires-Dist: pytest>=8
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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:

```bash
pip install pytest-markdown-console
```

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

```bash
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:

```bash
pytest -p no:markdown-console
```

To run only the plugin's tests:

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