Skip to main content

Test code blocks in your READMEs

Project description

pytest-codeblocks

Test code blocks in your READMEs.

PyPi Version Anaconda Cloud PyPI pyversions GitHub stars Downloads

gh-actions codecov Code style: black

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.

Marking code blocks

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

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

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).

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pytest_codeblocks-0.16.2.tar.gz (11.2 kB view details)

Uploaded Source

Built Distribution

pytest_codeblocks-0.16.2-py3-none-any.whl (7.7 kB view details)

Uploaded Python 3

File details

Details for the file pytest_codeblocks-0.16.2.tar.gz.

File metadata

  • Download URL: pytest_codeblocks-0.16.2.tar.gz
  • Upload date:
  • Size: 11.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.31.0

File hashes

Hashes for pytest_codeblocks-0.16.2.tar.gz
Algorithm Hash digest
SHA256 fd4c1c913a49df4c8f107728418e7ffb454be0f2676ea6e972eb77ae03c6c373
MD5 6c31239e61618105150d57ab548d89b5
BLAKE2b-256 baf5847eb4a320600d917b38832eaa287a872abc96681cb0cb91282f536bc077

See more details on using hashes here.

File details

Details for the file pytest_codeblocks-0.16.2-py3-none-any.whl.

File metadata

File hashes

Hashes for pytest_codeblocks-0.16.2-py3-none-any.whl
Algorithm Hash digest
SHA256 488726753a34583b5263a1518ae57d87543b8384e5e46c652e2779d9bd0e40bf
MD5 1b4b375a73f3bee148eba45772733a5c
BLAKE2b-256 052d715bece123dcd0424305633a67acca192f6adb71e4a7c0b332e3ed32187d

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page