executable-stories

Executable stories without Cucumber across JavaScript/TypeScript and non-JS test frameworks, with generated documentation and report outputs.

One source of truth. Code that executes. Docs that do not lie.

• Scenario API built on your test runner's native primitives
• given(), when(), then(), and(), but() helpers that register real tests
• Reporters/formatters that generate Markdown, HTML, JUnit XML, and Cucumber outputs from test metadata
• Output readable by developers and stakeholders

If a test is skipped, failed, or todo, the docs reflect that.

Example apps: apps/jest-example, apps/vitest-example, apps/playwright-example, apps/cypress-example, apps/vite-plus-example, apps/junit5-example (Java 21, Maven; verification: pnpm run verify:junit5), apps/pytest-example (Python 3.12+, pytest; verification: pnpm run verify:pytest), apps/go-example (Go 1.22+; verification: pnpm run verify:go), apps/rust-example (Rust 1.75+; verification: pnpm run verify:rust), apps/xunit-example (.NET 8, xUnit; verification: pnpm run verify:xunit).

The matrix below covers the JS/TS adapters. The same story structure and doc model are mirrored across the Go, Ruby, Rust, pytest, JUnit 5 (Kotlin), and xUnit (C#) adapters — see the cross-language parity policy.

For per-framework behaviour and guarantees (entry point, mental model, modifiers, framework-native attach), see: Jest — Developer experience, Vitest — Developer experience, Playwright — Developer experience, Cypress.

Details and reporter options: see each package's README.

OTel trace link is also supported in the non-JS adapters: Go (WithTraceUrlTemplate), Python (trace_url_template), Kotlin/JUnit5 (traceUrlTemplate parameter or env var), Rust (with_trace_url_template, requires otel feature), and C#/xUnit (Story.WithTraceUrlTemplate() or env var). All adapters auto-detect an active span and inject trace ID docs bidirectionally. Set OTEL_TRACE_URL_TEMPLATE (with {traceId} placeholder) to generate clickable trace links in reports.

Step timing (startTimer/endTimer) is supported in all non-JS adapters: Go (s.StartTimer()/s.EndTimer(token)), Python (story.start_timer()/story.end_timer(token)), Kotlin/JUnit5 (Story.startTimer()/Story.endTimer(token)), Rust (story.start_timer()/story.end_timer(token)), and C#/xUnit (Story.StartTimer()/Story.EndTimer(token)). The JS adapters record step timing automatically via story.fn() / story.expect() wrappers and step callbacks.

Jest (story.init() plus step markers):

import { expect, it } from '@jest/globals';
import { story } from 'executable-stories-jest';

it('User logs in', () => {
  story.init();
  story.given('user is on login page');
  story.when('user submits valid credentials');
  story.then('user sees the dashboard', () => {
    expect(true).toBe(true); // or real assertion
  });
});

Playwright uses the same story.given / story.when / story.then style, but pass testInfo to story.init(testInfo).

Cypress (call story.init() at the start of each it, then use step markers; see Cypress README).

Vitest (story.init(task); no top-level then):

import { expect, it } from 'vitest';
import { story } from 'executable-stories-vitest';

it('User logs in', ({ task }) => {
  story.init(task);
  story.given('user is on login page');
  story.when('user submits valid credentials');
  story.then('user sees the dashboard', () => {
    expect(true).toBe(true);
  });
});

Playwright step callbacks can use fixtures: given("...", async ({ page }) => { await page.goto("/login"); });

Generated Markdown:

### User logs in

- **Given** user is on login page
- **When** user submits valid credentials
- **Then** user sees the dashboard

1. Install the package for your test runner
2. Add the reporter to your config
3. Run your tests
4. Open the generated Markdown

The reporter writes reports/raw-run.json; turn it into any report format with the CLI:

npx --package executable-stories-formatters executable-stories format reports/raw-run.json --format html,markdown

See each package's README for detailed setup instructions.

Agent workflows: Publish StoryReport JSON and a scenario index from CI — see the agent artifact contract and MCP server guide. Package roles: package map. Cross-language parity policy: parity matrix.

Generate a multi-page Astro site from your stories — one page per story file plus a scenario Explorer. It auto-picks-up: add a *.story.test.ts and re-run, its page appears; delete it and the page is pruned. Zero per-test wiring.

The executable-stories CLI ships in the executable-stories-formatters package (install it, or invoke via npx --package executable-stories-formatters executable-stories …).

npx --package executable-stories-formatters executable-stories init-astro site   # scaffold the Astro/Starlight site
# vitest.config: createStoryReporter({ rawRunPath: 'reports/raw-run.json' })
pnpm test                                      # writes reports/raw-run.json (auto-includes all stories)
npx --package executable-stories-formatters executable-stories build-docs reports/raw-run.json --site-dir site
cd site && npm install && npm run build        # static dist/

build-docs is the headline command — format --format astro is a lower-level primitive that emits a single aggregated page, not a site.

From the repo root: pnpm quality runs build, lint, type-check, and test for all packages.

For contributor and AI agent guidance (conventions, framework APIs, ESLint plugins, verification), see AGENTS.md. CLAUDE.md is a symlink to the same file. Example apps in apps/ use the workspace packages. JUnit 5, pytest, Go, Rust, Ruby, and xUnit example apps are not part of pnpm quality. When Java 21 and Maven are available (e.g. in the devcontainer), run pnpm run verify:junit5 to run junit5-example. When Python 3.12+ is available, run pnpm run verify:pytest to run pytest-example. When Go 1.22+ is available, run pnpm run verify:go to run go-example. When Rust is available, run pnpm run verify:rust to run rust-example. When Ruby and Bundler are available, run pnpm run verify:ruby for executable-stories-ruby. When .NET 8 is available, run pnpm run verify:xunit to run xunit-example.

The executable-stories-formatters package (CLI for generating reports from test results JSON) supports filtering by source file (--include / --exclude), CI auto-detection (GitHub Actions, GitLab, CircleCI, Azure DevOps, Buildkite, Jenkins, Travis) so reports include branch, commit, and build links, notifications (Slack, Teams, or generic webhook with optional HMAC signing; --notify always|on-failure|never), and run history (--history-file) for flakiness, stability, and performance trends in the HTML report. See formatters README. The HTML report highlights step parameters (quoted strings and numbers) for readability. The package can be built as a single standalone binary with Bun:

cd packages/executable-stories-formatters && bun run compile

This produces an executable-stories binary in that package directory. CI builds the binary for the runner platform and uploads it as an artifact (executable-stories-linux-x64). The Release workflow builds multi-platform binaries (linux-x64, linux-arm64, darwin-x64, darwin-arm64, windows-x64) and uploads them as the formatters-binaries artifact.

MIT