Metadata-Version: 2.5
Name: pytest-given
Version: 0.5.1
Summary: A pytest plugin that generates interactive HTML reports from Given/When/Then annotated tests.
Project-URL: Homepage, https://github.com/nwilbert/pytest-given
Project-URL: Repository, https://github.com/nwilbert/pytest-given
Project-URL: Issues, https://github.com/nwilbert/pytest-given/issues
Project-URL: Changelog, https://github.com/nwilbert/pytest-given/blob/main/CHANGELOG.md
Author-email: Niko Wilbert <mail@nikowilbert.de>
License-Expression: MIT
License-File: LICENSE.md
License-File: THIRD-PARTY-LICENSES
Keywords: bdd,domain-storytelling,given-when-then,living-documentation,pytest,report,testing,ubiquitous-language
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.14
Requires-Dist: jinja2>=3.1
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: markupsafe>=2.0
Requires-Dist: pytest>=9.0
Description-Content-Type: text/markdown

# pytest-given

A pytest plugin that turns Given/When/Then annotated tests into interactive HTML reports.

**Given** your pytest tests,<br>
**when** you narrate them with `given` / `when` / `then`,<br>
**then** documentation and behavior fuse into one report.

**What people and agents read is what the code does.**

Inspired by [JGiven](https://jgiven.org/) (Java).

**Documentation: <https://nwilbert.github.io/pytest-given/latest/>**

Live examples:
- **[Coffeeshop](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html)**: a tour of the core features.
- **[Hotel booking](https://nwilbert.github.io/pytest-given/latest/examples/hotel-booking.html)**: a glossary and domain stories, with story coverage.
- **[File glossary](https://nwilbert.github.io/pytest-given/latest/examples/file-glossary-booking.html)**: the same, with the glossary kept in a Markdown file.
- **[Self-report](https://nwilbert.github.io/pytest-given/latest/examples/self-report.html)**: pytest-given's own test suite.

## Quick start

```bash
pip install pytest-given
```

Requires **Python ≥ 3.14** (t-strings — [PEP 750](https://peps.python.org/pep-0750/) — are part of the step-text API) and **pytest ≥ 9.0**.

If AI agents work in your repo, also install the bundled [agent skills](https://nwilbert.github.io/pytest-given/latest/ai-agents/#agent-skills) — with pytest-given's own command, or with [library-skills](https://library-skills.io) alongside the skills of your other dependencies:

```bash
pytest-given skills install
# or
uvx library-skills install --claude
```

Then narrate a test:

```python
import pytest
from pytest_given import attach, given, scenario, then, when


@pytest.fixture
@given('a coffee machine with 10 coffees')
def machine():
    return {'coffees': 10, 'price': 2}


@scenario('Buying a coffee takes one from the machine', tags=['checkout'])
def test_buy_coffee(machine):
    with when('I buy a coffee'):
        machine['coffees'] -= 1
    with then('the machine has 9 coffees left'):
        assert machine['coffees'] == 9
        attach('Machine state', machine)
```

Run it:

```bash
pytest --given-html
```

This produces `given-report/report.html` — one file you can open directly in a browser.

The Coffeeshop example's report shows this same scenario:

✅ [Buying a coffee takes one from the machine](https://nwilbert.github.io/pytest-given/latest/examples/coffeeshop.html#scenario=examples/coffeeshop/test_coffeeshop.py::test_buy_coffee)

## Why pytest-given?

Classical BDD tools (Cucumber, behave, pytest-bdd) center on Gherkin, a natural-language DSL: stakeholders write the tests, and engineers maintain the glue code behind each step. The [BDD page](https://nwilbert.github.io/pytest-given/latest/bdd/) writes the quick start's scenario that way, for comparison.

pytest-given works the other way round: **engineers or their agents write normal tests, and pytest-given turns them into readable documentation.** Stakeholders and domain experts can follow the HTML report without ever opening the test suite. Engineers get a view of the system's behavior that is easier to scan than test code, browsable by tag, glossary term, or module. The approach is the one [JGiven](https://jgiven.org/) pioneered for Java, brought to pytest.

- Plain Python: no Gherkin, no `.feature` files, no parser.
- Tests stay first-class pytest tests, and the report is a by-product.
- Self-contained HTML: open it locally or attach it to a CI run, with no server and no external assets.

### Written by agents, reviewed by people

Most tests are no longer written by hand. A person describes the behavior they want, in a prompt or a spec, and an AI agent writes the tests along with the code. People review the narrated report first, and the test code behind it where it matters. The diagram shows this loop, and [Working with AI agents](https://nwilbert.github.io/pytest-given/latest/ai-agents/) explains how to set it up.

<p align="center">
  <img src="https://raw.githubusercontent.com/nwilbert/pytest-given/main/docs/pytest-given-diagram.svg" alt="A loop between people, agents, and artifacts: developers instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report, which domain experts validate. Developers review all the artifacts, feeding back to the agents." width="640">
</p>

### Glossary and Domain Storytelling

pytest-given goes beyond JGiven by tying tests to the domain itself. A [glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/) defines the terms your team uses, and the report highlights them wherever a test mentions them. [Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/) adds the big picture: stories of how the domain works, with the report showing which scenarios cover each sentence of a story.

### Documents that stay true

A design spec or a README can [cite](https://nwilbert.github.io/pytest-given/latest/guide/citations/) scenarios, tags and stories as links into the report, each led by its current status. `pytest-given citations update` keeps the citations in line with the latest run. `pytest-given citations check` in CI fails when a cited scenario stops passing or disappears, so the document can't quietly claim what the code no longer does.

## Features

- **[Step context managers](https://nwilbert.github.io/pytest-given/latest/guide/scenarios/)**: `with given(...)`, `when(...)`, `then(...)` blocks in plain pytest tests, nesting within a phase.
- **[Narrated fixtures](https://nwilbert.github.io/pytest-given/latest/guide/scenarios/)**: `@given` on a fixture, or `Annotated[..., given(...)]` on a parameter, records setup as a step.
- **[Parametrized scenarios](https://nwilbert.github.io/pytest-given/latest/guide/parametrized/)**: one narrated tree plus a parameter table per case, or one scenario per case on request.
- **[Glossary](https://nwilbert.github.io/pytest-given/latest/guide/glossary/)**: your domain's terms, declared in code or loaded from a `GLOSSARY.md`, rendered as highlighted term refs in the narration.
- **[Domain Storytelling](https://nwilbert.github.io/pytest-given/latest/guide/domain-storytelling/)**: Domain Stories as sequences of sentences, and per-sentence coverage in the report.
- **Reports**: a self-contained [HTML report](https://nwilbert.github.io/pytest-given/latest/html-report/) to browse and share, and a [Markdown report](https://nwilbert.github.io/pytest-given/latest/markdown-report/) for diffs, reviews and agents.
- **[Narration lint](https://nwilbert.github.io/pytest-given/latest/configuration/narration-lint/)**: structural checks that a step's text is honest about its body: empty steps, a `then` that checks nothing, a missing phase.
- **[Citations](https://nwilbert.github.io/pytest-given/latest/guide/citations/)**: links from Markdown documents to scenarios, tags and stories, led by their status and checked against the latest run.
- **[Agent skills](https://nwilbert.github.io/pytest-given/latest/ai-agents/)**: bundled Agent Skills for authoring, navigating and reviewing narrated tests, installable with one command.

The full reference — pytest options, source links, the standalone CLI — is on the [documentation site](https://nwilbert.github.io/pytest-given/latest/).

## License

[MIT](https://github.com/nwilbert/pytest-given/blob/main/LICENSE.md). The bundled Alpine.js runtime is also MIT, with its notice in [THIRD-PARTY-LICENSES](https://github.com/nwilbert/pytest-given/blob/main/THIRD-PARTY-LICENSES).
