README.md

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.

Skipping code blocks

Prefix your code block with a pytest-codeblocks:skip comment to skip

Lorem ipsum

<!--pytest-codeblocks:skip-->

```python
foo + bar  # not working
```

dolor sit amet.

Conditionally skipping code blocks works with skipif, e.g.,

<!--pytest-codeblocks:skipif(sys.version_info <= (3, 7))-->

Skip the entire file by putting

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

in the first line.

Merging code blocks

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

Expected output

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

This

```sh
print(1 + 3)
```

gives

<!--pytest-codeblocks:expected-output-->

```
4
```

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

Expected errors

Some code blocks are expected to give errors. You can verify this with

The following gives an error:

<!--pytest-codeblocks:expect-error-->

```python
1 / 0
```

The keyword expect-exception is also possible.

Doctest-style code blocks

Code blocks starting with ">>>" will be treated as interactive Python shell code, and tested by doctest.

```python
>>> print("Hello")
Hello
>>> 2+3
5
```

You can concatenate multiple doctest-style code blocks with <!--pytest-codeblocks:cont-->, but cannot mix doctest-style ones with normal python code blocks, or vice versa.

There are two ways to indicate expected exceptions in doctest-style code blocks. One is to include the expected exception into you code block, and let doctest handle it.

```python
>>> raise Exception("This should fail")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
Exception: This should fail
```

The other way is to use the <!--pytest-codeblocks:expect-exception-->, and let pytest handle it.

<!--pytest-codeblocks:expect-exception-->
```python
>>> raise Exception("This should fail")
```