First Story (Vitest)

Write a story

Create a test file (e.g. src/login.story.test.ts):

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

describe('Login', () => {
  it('user logs in successfully', ({ task }) => {
    story.init(task);

    story.given('the user is on the login page');
    story.when('the user submits valid credentials');
    story.then('the user should see the dashboard');
    expect(true).toBe(true); // replace with real assertions
  });
});

Use story.init(task) at the start of the test (with task from the callback), then story.given, story.when, story.then to mark steps. There is no callback-based story("Title", define) — you use native describe/it and the story object.

Run tests

pnpm vitest run

Generated output

The reporter writes to your configured formats and paths. For Markdown output (for example docs/user-stories.md), the story above looks like:

### User logs in successfully

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

If a step is skipped, failed, or todo, the docs reflect that (e.g. ⚠️ or ❌).

See it in the report

Run your reporter with --format html and your stories render into an interactive report:

Report Outputwhat this code generatesOpen live report ↗

Every framework adapter produces this same report. Click to open the live one.

Next

Vitest story & doc API — step markers, inline docs, doc methods, and options.

Converting existing Vitest tests — adopt executable-stories without rewriting existing tests.

Recipes (Vitest) — more examples with tables, JSON, and tags.