Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/nschloe/pytest-codeblocks
:page_facing_up: Test code blocks in your READMEs
https://github.com/nschloe/pytest-codeblocks
markdown pytest python testing
Last synced: 3 days ago
JSON representation
:page_facing_up: Test code blocks in your READMEs
- Host: GitHub
- URL: https://github.com/nschloe/pytest-codeblocks
- Owner: nschloe
- License: mit
- Created: 2017-05-29T11:21:10.000Z (over 7 years ago)
- Default Branch: main
- Last Pushed: 2024-11-13T23:11:57.000Z (3 months ago)
- Last Synced: 2025-02-10T12:07:49.452Z (10 days ago)
- Topics: markdown, pytest, python, testing
- Language: Python
- Homepage:
- Size: 361 KB
- Stars: 97
- Watchers: 4
- Forks: 16
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-pytest - pytest-codeblocks - Tests code blocks in your READMEs. (Plugins)
README
Test code blocks in your READMEs.
[](https://pypi.org/project/pytest_codeblocks/)
[](https://anaconda.org/conda-forge/pytest-codeblocks/)
[](https://pypi.org/project/pytest_codeblocks/)
[](https://github.com/nschloe/pytest-codeblocks)
[](https://www.pepy.tech/projects/pytest-codeblocks)
[](https://github.com/nschloe/pytest-codeblocks/actions?query=workflow%3Atests)
[](https://app.codecov.io/gh/nschloe/pytest-codeblocks)
[](https://github.com/psf/black)
This is pytest-codeblocks, a [pytest](https://pytest.org/) plugin for testing code
blocks from README files. It supports Python and shell code.
Install with
```sh
pip install pytest-codeblocks
```
and run pytest with
```sh
pytest --codeblocks
```
```sh
================================= 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`:
````markdown
Lorem ipsum
```python
foo + bar # not working
```
dolor sit amet.
````
```markdown
```
You can skip code blocks on import errors with
```markdown
```
Skip the entire file by putting
```markdown
```
in the first line.
For expected errors, use `pytest.mark.xfail`:
````markdown
The following gives an error:
```python
1 / 0
```
````
#### Merging code blocks
Broken-up code blocks can be merged into one with the `pytest-codeblocks:cont` prefix
````markdown
Lorem ipsum
```python
a = 1
```
dolor sit amet
```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:
````markdown
Lorem ipsum
dolor sit amet
```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:
````markdown
This
```sh
print(1 + 3)
```
gives
```
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](#skipping-code-blocks)).