Skip to content

pytest-given

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

What people and agents read is what the code does.

Getting started See a report

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.

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

More and more tests aren't written by hand. A person describes a scenario, an AI agent writes the test along with the code, and people review the narrated report instead of the test code. The diagram shows this loop, and Working with AI agents explains how to set it up.

A loop between people, agents, and artifacts Developers and domain experts instruct AI agents, which write annotated tests and code. The tests verify the code and generate a report that domain experts validate and developers review, feeding back to the agents. Artifacts instruct write give context review verify generate validate give feedback AI Agents Developers Domain Experts Annotated Tests Code Report
Open at full size

Glossary and Domain Storytelling

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

Example reports

The Examples page links the test code behind each report.

Development and license

See AGENTS.md for setup, quality gates, and conventions. pytest-given is MIT licensed. The bundled Alpine.js runtime is also MIT; its notice is in THIRD-PARTY-LICENSES.