Skip to main content

Reporters

Docs for Vitest SDK v0.3.3

LiveDoc provides reporters that transform raw Vitest results into beautiful, structured output — from colored CLI output to JSON exports and real-time web visualization.

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

export default defineConfig({
  test: {
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
      }),
    ],
  },
});

Reference​

LiveDocSpecReporter​

The primary reporter. Formats test results in Gherkin-style CLI output with features, scenarios, and steps — and automatically discovers a running LiveDoc server for real-time visualization.

LiveDocSpecReporter Output

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

new LiveDocSpecReporter(options?: LiveDocSpecReporterOptions)
One reporter does it all

As of v0.1.6, LiveDocSpecReporter handles both console output and server auto-discovery. You no longer need a separate LiveDocServerReporter — just add LiveDocSpecReporter and it will automatically find and publish to a running LiveDoc server.

Options​

OptionTypeDefaultDescription
detailLevelstring"spec+summary+headers"Controls what is displayed. Combine flags with +.
outputstringundefinedFile path to write output (in addition to console).
removeHeaderTextstringundefinedPrefix to strip from file paths in headers (useful for monorepos).
colorsbooleantrueEnable/disable ANSI colors in output.
postReportersPostReporter[][]Additional reporters to run after test completion.
json-outputstringundefinedFile path for JSON output (used with JsonReporter).
publishobjectundefinedExplicit server publish configuration (see below).
exportobjectundefinedWrite a TestRunV1 JSON file to disk (see Export Options).
coverageobjectundefinedAttach coverage evidence and optional thresholds. Requires a Vitest coverage provider.

Auto-Discovery​

When LiveDocSpecReporter initializes, it automatically attempts to find a running LiveDoc server using the following priority:

  1. Environment variables — LIVEDOC_SERVER_URL or LIVEDOC_PUBLISH_SERVER
  2. Explicit publish config — livedoc.options.publish in your vitest config
  3. discoverServer() fallback — dynamically imports @swedevtools/livedoc-server to probe for a running server
  4. Default local viewer — probes http://localhost:3100/api/health

If no server is found, the reporter silently continues with console-only output — your tests always run normally. Use LIVEDOC_PROJECT and LIVEDOC_ENVIRONMENT to control where the run appears in the viewer.

Publish Options​

To explicitly configure server publishing instead of relying on auto-discovery:

new LiveDocSpecReporter({
  detailLevel: "spec+summary+headers",
  publish: {
    enabled: true,
    server: "http://localhost:3100",
    project: "my-project",
    environment: "local",
  },
})
OptionTypeDefaultDescription
publish.enabledbooleanfalseEnable server publishing
publish.serverstringundefinedServer URL
publish.projectstring"livedoc"Project name for grouping results
publish.environmentstring"local"Environment label
publish.runType"full" | "partial""full"Publish a complete baseline or focused partial update

Coverage Options​

Install @vitest/coverage-v8 at the same version as Vitest, enable Vitest coverage, and set coverage.enabled on the reporter:

new LiveDocSpecReporter({
  coverage: {
    enabled: true,
    thresholds: {
      lines: 80,
      branches: 75,
    },
  },
})
OptionTypeDefaultDescription
coverage.enabledbooleanfalseExpect and publish coverage evidence
coverage.path / coverage.artifactPathstringAuto-detectCustom JSON summary or LCOV artifact
coverage.thresholdsPartial<Record<"lines" | "branches" | "functions" | "statements", number>>NoneNon-fatal Viewer warnings

See Code Coverage for the complete runner configuration and dependency matrix.

Export Options​

Write a TestRunV1 JSON file directly to disk after each test run — no server needed. This is the recommended approach for CI pipelines and for feeding the static HTML export.

new LiveDocSpecReporter({
  detailLevel: "spec+summary+headers",
  export: {
    output: "./test-results/livedoc-report.json",
  },
})
OptionTypeDefaultDescription
export.outputstring"./test-results/livedoc-report.json"File path for the JSON output. Directories are created automatically.
export.projectstringPublish config or "livedoc"Project name embedded in the JSON. Falls back to publish.project.
export.environmentstringAuto-detectedEnvironment label. Falls back to publish.environment, then auto-detects ("ci" when CI env var is set, "local" otherwise).
Export runs alongside publishing

The export option writes a file in addition to console output and server publishing — it doesn't replace either. You can use export, publish, and postReporters together.

On completion the reporter prints a confirmation with the file size:

✅ LiveDoc results exported to ./test-results/livedoc-report.json (1.2 MB)

The exported JSON file can be used with livedoc-viewer export to generate a self-contained HTML report, or consumed by any tool that reads the TestRunV1 schema.

Detail Level Flags​

Combine flags with + to control output verbosity.

Summary detail level:

Summary Detail Level

List detail level (with individual rule/scenario results):

List Detail Level

FlagDescription
specShow individual steps with pass/fail status
summaryShow totals summary at the end
headersShow feature and scenario names
listCompact list format
autoAutomatic detail level based on test count
silentNo console output (useful when only using post-reporters)

Common combinations:

// Full output (default) — show everything
detailLevel: "spec+summary+headers"

// Summary only — just totals
detailLevel: "summary"

// Headers and summary — no individual steps
detailLevel: "headers+summary"

// Silent — only post-reporters produce output
detailLevel: "silent"

Console Output Example​

Feature: Shopping Cart  @ecommerce

  Scenario: Adding an item
    ✓ given an empty cart
    ✓ when the user adds a product
    ✓ then the cart contains 1 item

──────────────────────────────────────────────────────
LiveDoc Test Summary
  ✓ 3 steps passed
  1 feature, 1 scenario, 3 steps

JsonReporter​

Post-reporter that writes test results to a JSON file. Used as a postReporter inside LiveDocSpecReporter.

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

new JsonReporter()

Configuration​

The JSON output file path is set via the json-output option on LiveDocSpecReporter:

new LiveDocSpecReporter({
  detailLevel: "spec+summary+headers",
  postReporters: [new JsonReporter()],
  "json-output": "./livedoc-results.json",
})

JSON Output Contents​

The JSON file includes:

  • All features with their scenarios and steps
  • All specifications with their rules
  • Pass/fail status and execution timing
  • Error messages and stack traces
  • Tags and metadata

LiveDocViewerReporter​

Post-reporter that sends test results to a LiveDoc Viewer web UI via HTTP POST.

import { LiveDocViewerReporter } from "@swedevtools/livedoc-vitest/reporter";

new LiveDocViewerReporter(options?: LiveDocViewerOptions)

Options​

OptionTypeDefaultDescription
serverstring"http://localhost:3100"Viewer server URL
projectstring"livedoc"Project name for grouping results
environmentstring"local"Environment label (e.g., "local", "ci")
timeoutnumber5000HTTP request timeout in milliseconds
silentbooleantrueIf true, fails silently when server is unavailable

Example​

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

new LiveDocSpecReporter({
  detailLevel: "spec+summary+headers",
  postReporters: [
    new LiveDocViewerReporter({
      server: "http://localhost:3100",
      project: "my-project",
      environment: "local",
    }),
  ],
})

LiveDocServerReporter (deprecated)​

Deprecated since v0.1.6

LiveDocServerReporter is now a re-export of LiveDocSpecReporter. Auto-discovery is built into LiveDocSpecReporter — you no longer need a separate reporter. Existing configs that use LiveDocServerReporter will continue to work, but you can simplify by removing it.

Previously a standalone reporter for auto-discovering a running LiveDoc server. This functionality is now built directly into LiveDocSpecReporter.

Old config (still works, but unnecessary):

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

reporters: [
  new LiveDocSpecReporter({ detailLevel: "spec+summary+headers" }),
  new LiveDocServerReporter(), // ← No longer needed
],

New simplified config:

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

reporters: [
  new LiveDocSpecReporter({ detailLevel: "spec+summary+headers" }),
  // Auto-discovery happens automatically — no second reporter needed
],

Usage​

Basic: CLI output only​

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

export default defineConfig({
  test: {
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
      }),
    ],
  },
});

CLI with TestRunV1 export for CI​

Export a TestRunV1 JSON file for CI artifact upload or static HTML export:

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

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

CLI with SDK-model JSON export (JsonReporter)​

The JsonReporter writes the raw LiveDoc SDK model to a JSON file. This is useful for custom tooling but is not the same format as TestRunV1.

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

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

Full stack: CLI + JSON + Viewer​

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

export default defineConfig({
  test: {
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
        postReporters: [
          new JsonReporter(),
          new LiveDocViewerReporter({
            server: "http://localhost:3100",
            project: "my-project",
            environment: "local",
          }),
        ],
        "json-output": "./livedoc-results.json",
      }),
      // LiveDocSpecReporter auto-discovers a running LiveDoc server —
      // no separate LiveDocServerReporter needed
    ],
  },
});

Output to file for CI logs​

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

export default defineConfig({
  test: {
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: "spec+summary+headers",
        output: "./test-output.txt",
      }),
    ],
  },
});

VS Code–safe configuration​

The VS Code Vitest extension can conflict with custom reporters. Detect the environment and fall back:

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

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

export default defineConfig({
  test: {
    reporters: isVSCodeVitest
      ? undefined
      : [
          new LiveDocSpecReporter({
            detailLevel: "spec+summary+headers",
          }),
        ],
  },
});

Monorepo path cleanup​

Strip path prefixes from file headers for cleaner output in monorepos:

new LiveDocSpecReporter({
  detailLevel: "spec+summary+headers",
  removeHeaderText: "packages/",
})
// Before: packages/auth/tests/Login.Spec.ts
// After:  auth/tests/Login.Spec.ts

See Also​