Reporters

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.

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

Option	Type	Default	Description
detailLevel	string	"spec+summary+headers"	Controls what is displayed. Combine flags with +.
output	string	undefined	File path to write output (in addition to console).
removeHeaderText	string	undefined	Prefix to strip from file paths in headers (useful for monorepos).
colors	boolean	true	Enable/disable ANSI colors in output.
postReporters	PostReporter[]	[]	Additional reporters to run after test completion.
json-output	string	undefined	File path for JSON output (used with JsonReporter).
publish	object	undefined	Explicit server publish configuration (see below).
export	object	undefined	Write a TestRunV1 JSON file to disk (see Export Options).

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

If no server is found, the reporter silently continues with console-only output — your tests always run normally.

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:3000",
    project: "my-project",
    environment: "local",
  },
})

Option	Type	Default	Description
publish.enabled	boolean	false	Enable server publishing
publish.server	string	undefined	Server URL
publish.project	string	"default"	Project name for grouping results
publish.environment	string	"local"	Environment label

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",
  },
})

Option	Type	Default	Description
export.output	string	"./test-results/livedoc-report.json"	File path for the JSON output. Directories are created automatically.
export.project	string	Publish config or "default"	Project name embedded in the JSON. Falls back to publish.project.
export.environment	string	Auto-detected	Environment 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:

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

Flag	Description
spec	Show individual steps with pass/fail status
summary	Show totals summary at the end
headers	Show feature and scenario names
list	Compact list format
auto	Automatic detail level based on test count
silent	No 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

Option	Type	Default	Description
server	string	"http://localhost:3100"	Viewer server URL
project	string	"default"	Project name for grouping results
environment	string	"local"	Environment label (e.g., "local", "ci")
timeout	number	5000	HTTP request timeout in milliseconds
silent	boolean	true	If 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

• Configuration — full vitest.config.ts reference
• Guide: CI/CD Integration — using reporters in continuous integration
• Guide: Static HTML Export — generate shareable HTML reports from exported JSON
• Guide: Viewer Integration — setting up the LiveDoc Viewer
• Guide: Custom Reporters — building your own reporter