Guides
Start with Install and your first story. Everything below assumes you have a run producing reports.
Concepts
Section titled “Concepts”Read these once and the rest of the docs stop being surprising.
Why not Cucumber?What we dropped from Gherkin and why: no feature files, no step matching, no world object.
Four layers, without a world objectWhere to put setup, actions, and assertions when there is no shared mutable world.
The specification layerDeclaring a feature above your tests so the docs have a spine.
Developer experienceHow the API sits inside each host framework, and where they deliberately differ.
Understanding the reportStatus precedence, storyboards, state snapshots, and what an unasserted claim means.
Writing stories
Section titled “Writing stories”Formatting and metadataEvery doc kind, plus tickets, tags, and the metadata that travels with a scenario.
Tagging for your audienceA small tag vocabulary that splits one suite into product, design, support, and QA views.
Adopting an existing suite
Section titled “Adopting an existing suite”You do not rewrite anything. You annotate the tests you already have.
Setup decision treeWhich package and which output mode, given what you already run.
Converting Vitest testsAdd story markers to an existing Vitest suite.
Converting Jest testsAdd story markers to an existing Jest suite.
Converting Playwright testsAdd story markers to an existing Playwright suite.
Converting a CucumberJS suiteRetire the feature files and step definitions, keep the scenarios.
Output and reports
Section titled “Output and reports”Output modesColocated, aggregated, and per-source state, plus what a filtered run may retire.
Collating reportsCombine many runs, or many repos, into one accumulated suite.
Sharing reportsHand a report to someone who will not clone the repo.
CI and source linksWire commit SHAs and permalinks so every scenario links to the code that proves it.
Publishing living documentation
Section titled “Publishing living documentation”Astro docs siteScaffold a Starlight site whose scenario pages regenerate from every run.
Add to an existing Astro siteMount story pages inside a docs site you already have.
Multi-repo docs hubOne site over several repos' runs, with drift between them made visible.
Embed reports in React appsDrop the renderer into a Next.js, Remix, or Vite app.
Product sites with CMS and demosTurn a Playwright run into a customer-facing demo page.
Embedding skill and agent HTMLPut an agent's generated HTML inside a scenario, sandboxed.
CI gates and review
Section titled “CI gates and review”GitHub ActionSurface a run as a PR comment, with a verdict and ranked findings.
Release confidenceThe before-PR and release gates: compare and gate-release.
Evidence Review and Code DiffGrade the proof behind a change, and annotate the patch with the scenarios that cover it.
Integrations
Section titled “Integrations”Publishing to Confluence and JiraEmit Atlassian Document Format and publish it without a lossy paste.
TestRail and Xray syncBridge the suite to the test management tool your org already pays for.
For coding agents
Section titled “For coding agents”Agent artifact contractThe StoryReport JSON, the scenario index, and the behavior manifest an agent reads instead of source.
MCP serverRead-only tools over the run, plus run_scenario for a focused rerun.
Agent loops and backpressurecheck, triage, and goal: the three signals an autonomous loop runs on.
When something breaks
Section titled “When something breaks”Common issuesNo report generated, init errors, and the framework-specific gotchas behind them.