pytest_docfiles

pytest plugin to test code sections in your documentation.

Installation

pip install pytest_docfiles

Usage

Define code sections in your markdown files.

<!-- doc.md -->
# Hello World
```python
print("hello world!")
```

run pytest on your markdown files with the --docfiles flag.

pytest --docfiles doc.md

Features

Section Names

Define names for your code sections so they can be better identified in your pytest output

<!-- doc.md -->
```python {"name": "my-section"}
print("hello world")
```

$ pytest --docfiles doc.md
...
doc.md::my-section PASSED
...

Fixtures

Define your fixtures in conftest.py as usual

# conftest.py

import pytest

@pytest.fixture
def custom_fixture() -> str:
    return "fixture value"

@pytest.fixture(autouse=True)
def autouse() -> None:
    """autouse fixtures are used in each code section"""

use the fixtures in your code sections

<!-- doc.md -->
```python {"fixtures": ["custom_fixture"]}
assert custom_fixture == "fixture value"
```

Scopes

Code section depending on other code section can be executed in scopes.

```python {"scope": "my-scope"}
value = True
```
```python {"scope": "my-scope"}
assert value is True
```

Skip Sections

```python {"skip": true}
raise Exception("this section should not run")
```

Exception Handling

```python {"raises": "RuntimeError"}
raise RuntimeError("this section should pass")
```