Test code blocks in your READMEs.

This is pytest-codeblocks, a pytest plugin for testing code blocks from README files. It supports Python and shell code.

Install with

pip install pytest-codeblocks

and run pytest with

pytest --codeblocks

================================= test session starts ================================= platform linux -- Python 3.9.4, pytest-6.2.4, py-1.10.0, pluggy-0.13.1 rootdir: /path/to/directory plugins: codeblocks-0.11.0 collected 56 items example.md ....................... [ 50%] README.md ....................... [100%] ================================= 56 passed in 0.08s ==================================

pytest-codeblocks will only pick up code blocks with python and sh/bash/zsh syntax highlighting.

It is possible to use pytest.mark for marking code blocks. For example, to skip a code block use pytest.mark.skip or pytest.mark.skipif:

Lorem ipsum <!--pytest.mark.skip--> ```python foo + bar # not working ``` dolor sit amet.

<!--pytest.mark.skipif(sys.version_info <= (3, 7), reason="Need at least Python 3.8")-->

You can skip code blocks on import errors with

<!--pytest-codeblocks:importorskip(sympy)-->

Skip the entire file by putting

<!--pytest-codeblocks:skipfile-->

in the first line.

For expected errors, use pytest.mark.xfail:

The following gives an error: <!--pytest.mark.xfail--> ```python 1 / 0 ```

Broken-up code blocks can be merged into one with the pytest-codeblocks:cont prefix

Lorem ipsum ```python a = 1 ``` dolor sit amet <!--pytest-codeblocks:cont--> ```python # this would otherwise fail since `a` is not defined a + 1 ```

If you'd like to prepend code that you don't want to show, you can just comment it out; pytest-codeblocks will pick it up anyway:

Lorem ipsum <!-- ```python a = 1 ``` --> dolor sit amet <!--pytest-codeblocks:cont--> ```python # this would otherwise fail since `a` is not defined a + 1 ```

You can also define the expected output of a code block:

This ```sh print(1 + 3) ``` gives <!--pytest-codeblocks:expected-output--> ``` 4 ```

Use expected-output-ignore-whitespace if you'd like whitespace differences to be ignored.

(Conditionally) Skipping the output verfication works by prepending the first block with skip/skipif (see above).