Skip to main content

Getting Started

Docs for Vitest SDK v0.3.3

In this guide you'll install LiveDoc, write your first executable specification, and see human-readable test output in your terminal — all in about five minutes.

What You'll Build​

By the end of this page you will have:

  • A working Vitest + LiveDoc project
  • A spec file using Gherkin syntax (Given / When / Then)
  • Beautiful, structured test output that doubles as living documentation

Prerequisites​

  • Node.js 18+ installed
  • A package manager: npm, yarn, or pnpm
  • A terminal and a code editor (VS Code recommended)

Step 1: Create a Project​

If you already have a project with Vitest, skip ahead to Step 2.

mkdir my-livedoc-project && cd my-livedoc-project
npm init -y

Step 2: Install LiveDoc​

Give GitHub Copilot, OpenAI Codex, Claude Code, Cursor, Roo Code, Windsurf, or another repository-aware agent this prompt:

Read https://livedoc.swedevtools.com/ai/setup.md and configure this repository
for LiveDoc. Inspect the project first, then ask me one configuration question
at a time. Summarize the proposed setup and wait for my approval before editing
files or installing packages.

The agent will confirm the project name, Viewer publishing, code coverage, thresholds, tag-based partial testing, and whether to add a representative LiveDoc spec. It also asks which AI tools you use and installs version-matched skills for each one inside the repository. It adds test:livedoc and, when coverage is enabled, test:livedoc:coverage package scripts. After it finishes, continue to Step 5 to inspect the result.

Already using Vitest?

LiveDoc works alongside your existing Vitest configuration. You don't need to change anything — just add the package and start writing .Spec.ts files.

Step 3: Configure Vitest​

Create (or update) a vitest.config.ts in your project root:

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

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

Key settings explained:

SettingWhy
globals: trueMakes expect available without importing — cleaner spec files
include: ['**/*.Spec.ts']LiveDoc specs use the .Spec.ts suffix by convention
reporters: [LiveDocSpecReporter]Produces structured, Gherkin-style output instead of default dots

Step 4: Write Your First Spec​

Create a file called tests/Calculator.Spec.ts:

// 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]; // 50 (auto-coerced to number)
    });

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

    when('I press add', () => {
      // addition already happened in the steps above
    });

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

Things to Notice​

PatternWhy
Then as thenESM treats lowercase then as a thenable. The uppercase import + alias avoids this quirk.
ctx.step.valuesQuoted values like '50' are automatically extracted and type-coerced — see Data Extraction.
.Spec.ts suffixLiveDoc convention. Your Vitest include pattern matches this.
Lowercase keywordsgiven, when, then — reads naturally in code while the output stays structured.
The Then import is required

You must import Then with uppercase T and alias it. Writing import { then } directly will cause ESM module-resolution issues.

Step 5: Run It 🎉​

npm run test:livedoc

If you used the manual installation path and did not add that package script, run npx vitest run instead. With AI-configured coverage, use:

npm run test:livedoc:coverage

You'll see output like this:

Vitest First Run

Every step title appears in the output — that's living documentation. When the business rules change, the specs and their output change with them.

Optional: VS Code Extension​

For the best authoring experience, install the LiveDoc VS Code Extension:

→ LiveDoc for VS Code

It provides:

  • 📐 Table formatting — automatically align data tables with a keystroke
  • ✂️ Snippets — quickly scaffold features, scenarios, and steps
  • 🎨 Syntax highlighting — Gherkin keywords stand out in your spec files

Recap​

  • Install vitest and @swedevtools/livedoc-vitest
  • Configure Vitest with include: ['**/*.Spec.ts'] and the LiveDocSpecReporter
  • Write specs using feature → scenario → given / when / then
  • Import Then as then to avoid the ESM thenable issue
  • Run with npm run test:livedoc and use test:livedoc:coverage when coverage is configured
  • Keep AI skills version-matched with npx livedoc-vitest-setup

Next Steps​