Skip to main content

Configuration

LiveDoc is configured through the standard vitest.config.ts file. This page documents every configuration option relevant to LiveDoc — file inclusion patterns, reporter setup, globals mode, and environment settings.

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

export default defineConfig({
  test: {
    include: ["**/*.Spec.ts"],
    globals: true,
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
      }),
    ],
  },
});

Reference​

File Inclusion​

test.include​

Glob patterns that determine which files Vitest treats as test files.

include: string[]

Default (Vitest): ["**/*.{test,spec}.{js,ts,jsx,tsx}"]

LiveDoc convention:

include: ["**/*.Spec.ts"]

LiveDoc spec files use the .Spec.ts extension (capital S) by convention. This distinguishes them from regular Vitest test files.

File Naming Convention

LiveDoc spec files must end in .Spec.ts (e.g., UserAuth.Spec.ts, ShoppingCart.Spec.ts). The capital S is intentional and required for the LiveDoc toolchain to recognize them.

test.exclude​

Glob patterns for files to exclude from test discovery.

exclude: string[]

Default: ["**/node_modules/**", "**/dist/**"]

// Exclude legacy tests during migration
exclude: ["**/node_modules/**", "**/dist/**", "**/legacy/**"]

Reporters​

test.reporters​

Array of reporter instances. LiveDoc reporters replace Vitest's default reporter.

reporters: Reporter[]

See Reporters for the full reference on each reporter.

import { LiveDocSpecReporter, JsonReporter } from "@swedevtools/livedoc-vitest/reporter";
import LiveDocServerReporter from "@swedevtools/livedoc-vitest/reporter";

export default defineConfig({
  test: {
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
        postReporters: [new JsonReporter()],
        "json-output": "./livedoc-results.json",
      }),
      new LiveDocServerReporter(),
    ],
  },
});

Globals Mode​

test.globals​

When true, LiveDoc keywords are available globally without imports.

globals: boolean

Default: false

export default defineConfig({
  test: {
    globals: true,
  },
});

With globals enabled, you can write specs without import statements:

// No import needed — all keywords are global
feature("Shopping Cart", () => {
  scenario("Add item", () => {
    given("an empty cart", () => { /* ... */ });
    when("a product is added", () => { /* ... */ });
    then("the cart has 1 item", () => { /* ... */ }); // lowercase `then` works!
  });
});
Globals mode resolves the Then import issue

When globals: true is set, lowercase then is registered as a global — no need for the import { Then as then } alias.

Without globals (explicit imports):

import { feature, scenario, given, when, Then as then } from "@swedevtools/livedoc-vitest";

feature("Shopping Cart", () => {
  // ...
});

TypeScript configuration for globals:

Add LiveDoc types to your tsconfig.json:

{
  "compilerOptions": {
    "types": ["vitest/globals", "@swedevtools/livedoc-vitest/globals"]
  }
}

Environment​

test.environment​

The execution environment for tests.

environment: "node" | "jsdom" | "happy-dom" | "edge-runtime"

Default: "node"

// For DOM-dependent tests (e.g., React components)
export default defineConfig({
  test: {
    environment: "jsdom",
  },
});

Most LiveDoc specs test business logic and run fine with "node". Use "jsdom" or "happy-dom" only if your specs exercise DOM APIs.

Setup Files​

test.setupFiles​

Files that run before each test file. Use for global setup like registering LiveDoc globals, configuring test utilities, or seeding databases.

setupFiles: string | string[]
export default defineConfig({
  test: {
    setupFiles: ["./tests/setup.ts"],
  },
});

Example setup file:

// tests/setup.ts
import { expect } from "vitest";

// Add custom matchers
expect.extend({
  toBeValidEmail(received: string) {
    const pass = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(received);
    return {
      pass,
      message: () => `expected ${received} to be a valid email`,
    };
  },
});

Thread Configuration​

test.pool and test.poolOptions​

Controls how tests are parallelized. LiveDoc works with all Vitest pool options.

pool: "threads" | "forks" | "vmThreads"

Default: "forks"

export default defineConfig({
  test: {
    pool: "forks",
    poolOptions: {
      forks: {
        singleFork: true, // Run all tests in a single process
      },
    },
  },
});
Single fork for ordered output

If you need deterministic reporter output (e.g., features printed in file order), use singleFork: true. This runs tests sequentially in one process.

Usage​

Minimal configuration​

The simplest working configuration:

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

export default defineConfig({
  test: {
    include: ["**/*.Spec.ts"],
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
      }),
    ],
  },
});

A complete configuration with all common options:

// vitest.config.ts
import { defineConfig } from "vitest/config";
import {
  LiveDocSpecReporter,
  JsonReporter,
  LiveDocViewerReporter,
} from "@swedevtools/livedoc-vitest/reporter";
import LiveDocServerReporter from "@swedevtools/livedoc-vitest/reporter";

const isVSCodeVitest = !!(
  process.env.VITEST_VSCODE ||
  process.env.VSCODE_PID ||
  process.env.VSCODE_IPC_HOOK
);

export default defineConfig({
  test: {
    include: ["**/*.Spec.ts"],
    exclude: ["**/node_modules/**", "**/dist/**"],
    globals: true,
    environment: "node",
    setupFiles: ["./tests/setup.ts"],
    reporters: isVSCodeVitest
      ? undefined
      : [
          new LiveDocSpecReporter({
            detailLevel: "spec+summary+headers",
            colors: true,
            postReporters: [
              new JsonReporter(),
              new LiveDocViewerReporter({
                server: "http://localhost:3100",
                project: "my-project",
              }),
            ],
            "json-output": "./livedoc-results.json",
          }),
          new LiveDocServerReporter(),
        ],
  },
});

Monorepo per-package configuration​

In a monorepo, each package has its own vitest.config.ts:

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

export default defineConfig({
  test: {
    include: ["**/*.Spec.ts"],
    globals: true,
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
        removeHeaderText: "packages/auth/",
      }),
    ],
  },
});

CI/CD configuration​

Optimized for continuous integration — JSON output, no colors, file logging:

// vitest.config.ci.ts
import { defineConfig } from "vitest/config";
import { LiveDocSpecReporter, JsonReporter } from "@swedevtools/livedoc-vitest/reporter";

export default defineConfig({
  test: {
    include: ["**/*.Spec.ts"],
    globals: true,
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
        colors: false,
        output: "./test-output.txt",
        postReporters: [new JsonReporter()],
        "json-output": "./livedoc-results.json",
      }),
    ],
  },
});

Run with:

vitest run --config vitest.config.ci.ts

See Also​