@swedevtools/livedoc-vitest

Turn your tests into living documentation

Write tests in Gherkin. Get documentation that never goes stale.

📖 Full Documentation →

What is LiveDoc?

LiveDoc brings Behavior-Driven Development to Vitest with full Gherkin syntax — Feature / Scenario / Given / When / Then, Specification / Rule, Scenario Outlines, Tags & Filtering, and beautiful reports.

Quick Start

Install

npm install --save-dev vitest@^4.0.16 @swedevtools/livedoc-vitest

Fastest Setup: Point Your AI at the Bootstrap URL

Tell your assistant:

Read https://livedoc.swedevtools.com/ai/setup.md and configure this Vitest project for LiveDoc. Inspect it first, ask me one configuration question at a time, and wait for approval before making changes.

No LiveDoc package or skill needs to be installed first. AI project setup →

AI setup installs version-matched skills inside the repository for every selected tool. Run npx livedoc-vitest-setup --tool copilot,codex,claude later to refresh them or add another tool. It also adds test:livedoc and, when coverage is enabled, test:livedoc:coverage package scripts.

Create a spec

// tests/Calculator.Spec.ts
import { feature, scenario, given, when, Then as then, and } from '@swedevtools/livedoc-vitest';

feature("Calculator", () => {
  scenario("Adding two numbers", () => {
    let result = 0;

    given("I have entered '50' into the calculator", (ctx) => {
      result = ctx.step.values[0];
    });

    and("I have entered '70' into the calculator", (ctx) => {
      result += ctx.step.values[0];
    });

    when("I press add", () => {
      // Addition already happened above
    });

    then("the result should be '120'", (ctx) => {
      expect(result).toBe(ctx.step.values[0]);
    });
  });
});

Why Then as then? ES modules treat then as a thenable indicator. We export Then (uppercase) and you alias it.

Configure Vitest

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';

export default defineConfig({
  test: {
    globals: true,
    include: ['**/*.Spec.ts'],
    reporters: [new LiveDocSpecReporter()],
  },
});

Run

npx vitest run

Publish a focused partial run

After publishing one full baseline, mark an isolated development run as partial so the Viewer keeps the complete latest-known picture:

LIVEDOC_RUN_TYPE=partial npx vitest run features/Login.Spec.ts

You can also set publish.runType or LiveDocViewerReporter({ runType: 'partial' }) in configuration. Partial runs require a running LiveDoc server and a completed full baseline for the same project and environment. Direct JSON/static partial export is not supported; release and production exports should use a full run.

Add coverage evidence

LiveDoc can attach Vitest coverage as optional run evidence. It does not change the test run status; threshold misses appear as warnings in the viewer.

Install the V8 provider on the same version as Vitest:

npm install --save-dev @vitest/coverage-v8

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import { LiveDocSpecReporter } from '@swedevtools/livedoc-vitest/reporter';

export default defineConfig({
  test: {
    reporters: [
      new LiveDocSpecReporter({
        coverage: { enabled: true, thresholds: { lines: 80 } },
      }),
    ],
    coverage: {
      enabled: true,
      provider: 'v8',
      reporter: ['text', 'html', 'json-summary'],
    },
  },
});

npx vitest run --coverage

LiveDoc consumes Vitest's in-memory coverage map before the run is published. It also auto-detects coverage/coverage-summary.json and coverage/lcov.info as fallbacks. For custom artifact paths, set coverage.artifactPath in the reporter or use LIVEDOC_COVERAGE_PATH.

See the Code Coverage guide for provider choices, thresholds, troubleshooting, and the Viewer module hierarchy.

Documentation

📖 Full documentation at livedoc.swedevtools.com →

Covers getting started, BDD & Specification patterns, data extraction, scenario outlines, tags & filtering, reporters, viewer integration, CI/CD, troubleshooting, and more.

License

MIT