Skip to main content

Getting Started

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​

npm install --save-dev vitest @swedevtools/livedoc-vitest
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 🎉​

npx vitest run

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

Optional: Install AI Skills​

If your team uses AI coding assistants, install the LiveDoc skill so your AI writes correct BDD tests with proper patterns and value extraction:

npx livedoc-vitest-setup

This installs skill files for your chosen AI tools (GitHub Copilot, Claude Code, Cursor, Windsurf, or Roo Code). Commit the generated files so every developer on the team benefits automatically.

→ See AI Skill Setup for details and non-interactive CI usage.

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 npx vitest run and enjoy structured, readable output
  • Install AI skills with npx livedoc-vitest-setup so your AI assistant writes correct tests

Next Steps​