Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 26 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
# 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.
# A pytest plugin to test console code blocks in Markdown files


## Installation
Expand Down Expand Up @@ -39,7 +37,7 @@ Hello, world!
```
````

Running pytest with this extension creates a test case that passes if the app actually prints "Hello, world!".
Running pytest with this plugin creates a test case that passes if the app actually prints "Hello, world!".

### Match partial output

Expand Down Expand Up @@ -69,8 +67,7 @@ $ uv run myapp.py --still_bad
```
````

To pass the test case, the command line must fail and the error message produced by the application, if any, must match.

To the test case to pass, the command line must fail and the error message produced by the application, if any, must match.

### Filter by platform

Expand Down Expand Up @@ -178,8 +175,18 @@ Done.

`yield` fixtures work normally — teardown runs after the block completes.

### Exclude a block from testing

To exclude a block from being collected as a test at all, use the `notest` directive:

````markdown
<!-- pytest-markdown-console: notest -->
```console
$ echo "This block will not be tested"
```
````

### Hidden blocks
### Run hidden blocks

Wrapping a fence in an HTML comment hides it from rendered output (e.g. on GitHub) while
the plugin still finds and runs it. This is useful for setup steps that would clutter the
Expand Down Expand Up @@ -207,10 +214,9 @@ hi
-->
````

### Customise the directive tag

### Exclude a block from testing

To exclude a block from being collected as a test at all, use the `notest` directive:
By default, directive comments use the `pytest-markdown-console` tag:

````markdown
<!-- pytest-markdown-console: notest -->
Expand All @@ -219,8 +225,16 @@ $ echo "This block will not be tested"
```
````

You can change this tag via `pyproject.toml`, for example to keep your Markdown source shorter:

### Controlling test case runs globally
```toml
[tool.pytest.ini_options]
markdown_console_directive = "console-test"
```

With the above setting you would write `<!-- console-test: notest -->` instead.

### Control test case runs globally

By default, test cases generated by this plugin are run whenever pytest is invoked. To exclude them entirely:

Expand All @@ -235,34 +249,12 @@ pytest -m markdown_console
```


### Customising the directive tag

By default, directive comments use the `pytest-markdown-console` tag:

````markdown
<!-- pytest-markdown-console: notest -->
```console
$ echo "This block will not be tested"
```
````

You can change this tag via `pyproject.toml`, for example to keep your Markdown source shorter:

```toml
[tool.pytest.ini_options]
markdown_console_directive = "console-test"
```

With the above setting you would write `<!-- console-test: notest -->` instead.


## Why this extension?
## Why this plugin?

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

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.
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[project]
name = "pytest-markdown-console"
version = "0.0.1.dev2"
version = "0.0.1"
description = "A pytest extension to test console code blocks in markdown files."
readme = "README.md"
authors = [
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading