Recipes

Every recipe shows one scenario twice: the test you write, and the documentation it generates. Pick your framework in the tab strip on any recipe and the rest of the site follows that choice.

One output, nine adapters

The generated documentation is identical whichever adapter you use. Only the test code changes. Eight recipes are marked all languages below; the rest cover Vitest, Jest, Playwright, and Cypress.

Step structure

How Given, When, and Then read when you repeat them. A repeated keyword renders as And from the second occurrence onward.

User logs in successfullyThree Given steps in a row. All languages.

User updates profile detailsOne Given, several When steps, one Then.

Checkout calculates totalsOne When, three Then steps. All languages.

Password reset flowA longer flow with several steps of each keyword.

Logout clears sessionThree consecutive Then steps.

Two step checkoutTwo When groups in one scenario, each with its own Then.

Contrast and explicit keywords

story.and() and story.but() never auto-convert, so use them when the wording matters more than the keyword arithmetic.

Login blocked for suspended userBut keeps negative intent visible. All languages.

Payment declinedThen states what happened, But states what did not.

Guest checkout allowedA note explaining why a step is worded as a negative.

Search results show highlightsAn explicit And after a Then.

Report shows fields in orderAn explicit And in the middle of a Then block.

Document status changesName both states so the transition reads without the code.

Attaching data to a step

Tables, JSON, and code blocks travel with the step they belong to, so a reader sees the payload rather than a description of it.

Bulk user creationstory.table() on setup and on the expected result. All languages.

Calculate shipping optionsOne table drives the input, three Then steps check it.

Configure feature flagsA wide table with more columns than a step could carry.

Update preferencesA two-column table read as key and value.

API accepts a JSON payloadstory.json() renders formatted JSON. All languages.

Import XML invoicestory.code() with an XML document. All languages.

Render markdownMarkdown source shown as source, not parsed.

Import users and send welcome emailA table on one step, a code block on the next.

Scenario outlines

Loop over your cases and register one scenario per row. No Examples table, no placeholder syntax, just the language you already write.

Login errorsOne scenario per error case, from an array.

Many login attemptsOne outline covering several different outcomes.

Shipping eligibilityOne scenario per country, from a single table.

Tax calculation by regionA row per region and the rate you expect.

Create users from table inputAn outline where each row also attaches its table.

Post JSON payloadAn outline where every case carries its own payload.

Shared setup and business rules

Change email addressShared Given setup, grouped as a background.

Change passwordThe same background, a different When and Then.

Eligible customer gets discountThe positive path of a named rule.

Ineligible customer does not get discountThe negative path of the same rule.

Create orderBackground and tags together. All languages.

Login worksTags at init, so readers can filter the report. All languages.

Where this code lives

Each snippet is lifted from a suite that runs in CI, so none of it drifts:

Adapter	Source
Vitest	apps/vitest-example/src/replicate.story.test.ts
Jest	apps/jest-example
Playwright	apps/playwright-example
Cypress	apps/cypress-example
Go, Python, Rust, Kotlin, C#	packages/executable-stories-*

For the full API behind these recipes, see the story and doc API reference.