@swedevtools/livedoc-viewer

Real-time BDD test results in your browser.

📖 Documentation · GitHub

What It Does

LiveDoc Viewer is a web-based dashboard that visualizes BDD test results as they run. Start the viewer, run your tests, and watch features, scenarios, and steps stream into the browser in real time.

• Live updates — results appear via WebSocket as each scenario completes
• Failure details — click any failed step to see the error and stack trace
• Quality dashboard — tests, failures, rule violations, coverage, and duration at a glance
• Code coverage — weighted module totals with line and branch drill-down
• Run history — Full and Partial views with optional automatic latest-run following
• Deep links — share the exact project, run, projection, folder, or test
• Multi-framework — works with @swedevtools/livedoc-vitest (TypeScript) and SweDevTools.LiveDoc.xUnit (.NET)
• Static export — generate a self-contained HTML report you can share or archive

Installation

# Global — use the CLI from any project
npm install -g @swedevtools/livedoc-viewer

# Or as a dev dependency in your project
npm install -D @swedevtools/livedoc-viewer

Requires Node.js 18 or later.

Quick Start

1. Start the viewer

livedoc-viewer

This launches a local server at http://localhost:3100 and opens your browser.

2. Connect your test framework

Add the LiveDoc reporter to your Vitest config:

// 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' }),
    ],
  },
});

The reporter auto-discovers a running viewer — no extra configuration needed.

3. Run your tests

npx vitest run

Switch to the browser and watch results appear in real time.

Focused Partial Runs

Developers and AI agents can validate one file, scenario, or rule without replacing the complete latest-known documentation. Publish one full baseline, then configure the reporter with runType: 'partial' or LIVEDOC_RUN_TYPE=partial for focused runs.

The Run menu keeps one chronological history with Full and Partial n badges. Selecting a partial defaults to Combined (the full baseline plus completed partial updates); switch to This partial to inspect only what that invocation executed. Static exports remain full-run workflows.

Coverage in the Viewer

When a reporter attaches file-level coverage, the dashboard adds a Code Coverage section with module health, file counts, and weighted line totals. Runs without coverage show no coverage controls.

The coverage explorer leads with the project/module hierarchy, shows line and branch percentages, removes redundant path prefixes, and keeps modules collapsed until you drill in. Coverage is invocation evidence, not a test result, so low coverage or threshold warnings do not change pass/fail status.

See the Code Coverage guide for complete Vitest, xUnit, and Visual Studio setup.

CLI Usage

Server Mode (default)

livedoc-viewer [options]

| Option | Short | Default | Description | | --------------- | ----- | ----------- | -------------------------------- | | --port <port> | -p | 3100 | Port to run the server on | | --host <host> | -H | localhost | Host interface to bind to | | --no-open | — | (opens) | Don't open browser automatically | | --version | -V | — | Show version and exit | | --help | -h | — | Show help and exit |

# Custom port, no browser
livedoc-viewer -p 8080 --no-open

# Accessible on the network (CI/CD)
livedoc-viewer --host 0.0.0.0 --no-open

Static Export

Generate a self-contained HTML report from a TestRunV1 JSON file. The output embeds all JS, CSS, and test data inline — open it in any browser with zero dependencies.

livedoc-viewer export -i <path> [-o <path>] [-t <title>]

| Option | Short | Required | Default | Description | | ------------------ | ----- | -------- | ------------------------- | --------------------------- | | --input <path> | -i | Yes | — | Path to TestRunV1 JSON file | | --output <path> | -o | No | ./livedoc-report.html | Output HTML file path | | --title <title> | -t | No | Project name or "LiveDoc" | Custom report title |

# Basic export
livedoc-viewer export -i ./test-results/lastrun.json

# Custom output path and title
livedoc-viewer export -i results.json -o ./reports/sprint-42.html -t "Sprint 42 Results"

Documentation

📖 Full documentation at livedoc.swedevtools.com →

• Getting Started — install, connect, and run
• Understanding the UI — what each panel shows
• Code Coverage — configure Vitest, xUnit, and Visual Studio coverage
• CLI Options Reference — all flags and subcommands
• REST API — programmatic access
• WebSocket API — real-time protocol

License

MIT © Garry McGlennon