Metadata-Version: 2.1
Name: pytest-docfiles
Version: 0.2.0
Summary: pytest plugin to test codeblocks in your documentation.
Home-page: https://www.github.com/stefanhoelzl/pytest_docfiles/
Author: Stefan Hoelzl
Author-email: stefanh+pytest_docfiles@posteo.de
License: MIT
Keywords: pytest plugin markdown documentation codeblocks
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Testing
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest (>=3.7.0)
Requires-Dist: markdown-it-py (>=2.0.0)

# pytest_docfiles
[![Build Status](https://github.com/stefanhoelzl/pytest_docfiles/workflows/push/badge.svg)](https://github.com/stefanhoelzl/pytest_docfiles/actions)
[![PyPI](https://img.shields.io/pypi/v/pytest_docfiles.svg)](https://pypi.org/project/pytest_docfiles/)
[![Downloads](https://img.shields.io/pypi/dm/pytest_docfiles?color=blue&logo=pypi&logoColor=yellow)](https://pypistats.org/packages/pytest_docfiles)
[![License](https://img.shields.io/pypi/l/pytest_docfiles.svg)](LICENSE)

pytest plugin to test code sections in your documentation.

## Installation
```bash
pip install pytest_docfiles
```

## Usage
Define code sections in your markdown files.
````md
<!-- doc.md -->
# Hello World
```python
print("hello world!")
```
````
run pytest on your markdown files with the `--docfiles` flag.
```bash
pytest --docfiles doc.md
```

## Features
### Section Names
Define names for your code sections so they can be better identified in your pytest output
````md
<!-- doc.md -->
```python {"name": "my-section"}
print("hello world")
```
````
```bash
$ pytest --docfiles doc.md
...
doc.md::my-section PASSED
...
```

### Fixtures
Define your fixtures in `conftest.py` as usual
```python
# 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
````md
<!-- doc.md -->
```python {"fixtures": ["custom_fixture"]}
assert custom_fixture == "fixture value"
```
````

### Scopes
Code section depending on other code section can be executed in scopes.
````md
```python {"scope": "my-scope"}
value = True
```
```python {"scope": "my-scope"}
assert value is True
```
````

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

### Exception Handling
````md
```python {"raises": "RuntimeError"}
raise RuntimeError("this section should pass")
```
````

