diff --git a/README.md b/README.md index b2ac4d5..dceb233 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 @@ -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 + +```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 @@ -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 @@ -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 `` instead. + +### Control test case runs globally By default, test cases generated by this plugin are run whenever pytest is invoked. To exclude them entirely: @@ -235,34 +249,12 @@ pytest -m markdown_console ``` -### Customising the directive tag - -By default, directive comments use the `pytest-markdown-console` tag: - -````markdown - -```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 `` 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. diff --git a/pyproject.toml b/pyproject.toml index a7bda3c..422998a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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 = [ diff --git a/uv.lock b/uv.lock index c35f9f8..567c5b4 100644 --- a/uv.lock +++ b/uv.lock @@ -233,7 +233,7 @@ wheels = [ [[package]] name = "pytest-markdown-console" -version = "0.0.1.dev2" +version = "0.0.1" source = { editable = "." } dependencies = [ { name = "pytest" },