Skip to main content

Viewer Integration

Docs for xUnit SDK v0.4.0

This guide shows you how to connect your LiveDoc xUnit tests to the LiveDoc Viewer — a real-time web UI that displays your test results as they execute. For local development, auto-discovery means no code changes and no configuration files — just start the Viewer and run your tests.

Prerequisites
  • A .NET project with SweDevTools.LiveDoc.xUnit installed — see Getting Started
  • Node.js 18+ (required for the viewer)

Overview​

The LiveDoc Viewer is a standalone web application that receives test results over HTTP. When you run your xUnit tests, the LiveDoc Reporter automatically discovers the Viewer on localhost:3100 and streams results in real time. No assembly attributes or configuration files needed.

How auto-discovery works: At startup, the reporter pings http://localhost:3100/api/health. If the Viewer responds, reporting is enabled automatically. If not, reporting is silently disabled and tests run normally.

Step 1: Install and Start the Viewer​

Install the viewer CLI globally via npm:

npm install -g @swedevtools/livedoc-viewer

Start it:

livedoc-viewer

The viewer opens at http://localhost:3100 by default.

Step 2: Run Your Tests​

In a separate terminal, run your tests as usual:

dotnet test --logger LiveDoc

That's it. Auto-discovery detects the Viewer and streams results as each test completes. Open http://localhost:3100 in your browser to see results appear in real time.

The viewer organizes results by the full declared namespace hierarchy, independently of the assembly name, not by physical folders alone. Every namespace segment is retained; class names and Feature/Specification titles remain document leaves rather than navigation folders. Align source folders and namespaces so developers and readers see the same capability structure, as described in Best Practices.

Zero config

No assembly attributes, no .runsettings files, no environment variables needed for local development. Auto-discovery handles everything.

Add Code Coverage​

The LiveDoc NuGet package includes its coverage collector and attachment processor. To collect line and branch data with Microsoft's collector, request Cobertura output:

dotnet test .\MySolution.sln --collect:"Code Coverage;Format=Cobertura"

For this repository:

dotnet test .\dotnet\xunit\livedoc-xunit.sln --collect:"Code Coverage;Format=Cobertura"

Visual Studio's Analyze Code Coverage for All Tests may emit a binary .coverage attachment. Install Microsoft's converter:

dotnet tool install --global dotnet-coverage

No coverlet.collector dependency is required for the recommended Microsoft Code Coverage command. See the shared Code Coverage guide for XPlat/Coverlet, custom runsettings, thresholds, diagnostics, and module scope.

Inspect Ordinary Facts and Theories​

You can adopt living documentation incrementally. With standard-test reporting enabled through the test framework integration, ordinary xUnit Facts and Theory cases appear beside Features and Specifications. Open their test container, then select a test row—even when it passed or was skipped—to inspect its result. Each published Theory case keeps its own parameterized title, stable ID, and execution status.

The Viewer accepts both Standard and Container document kinds in existing saved reports and static exports. You do not need to rewrite persisted JSON, add Feature/Specification attributes to ordinary tests, or change the producer's document kind. Namespace folders, project/run selection, filters, and deep links continue to use the original report identities.

Failed tests show their reported errors; skipped tests show the reason when the reporter supplied one. Evidence recorded in execution.attachments, including captured output files, uses the same attachment gallery as authored tests. The Viewer does not invent output or reasons missing from the report.

Step 3: Customize (Optional)​

For custom project names, non-default ports, or CI/CD pipelines — pass parameters directly on the --logger flag:

# Custom project name
dotnet test --logger "LiveDoc;Project=checkout-service"

# Viewer on a non-default port
dotnet test --logger "LiveDoc;ServerUrl=http://localhost:4200"

# Multiple settings
dotnet test --logger "LiveDoc;ServerUrl=http://localhost:4200;Project=checkout-service;Environment=staging"
ParameterDefaultDescription
ServerUrl(auto-discover on localhost:3100)Explicit Viewer URL. Skips auto-discovery.
ProjectAssembly nameProject name displayed in the Viewer.
Environment"local"Environment label (e.g., "local", "ci", "staging").
ExportPath(disabled)JSON export file path.

See the Configuration Reference for the full list of parameters and environment variables.

CI/CD Configuration​

In CI pipelines, auto-discovery won't find a Viewer on localhost. Pass the URL as a logger parameter or use environment variables:

# GitHub Actions — logger parameters (simplest)
- name: Run tests with Viewer reporting
  run: dotnet test --logger "LiveDoc;ServerUrl=https://livedoc-viewer.internal.co;Project=my-app;Environment=ci"
# GitHub Actions — environment variables (alternative)
- name: Run tests with Viewer reporting
  run: dotnet test --logger LiveDoc
  env:
    LIVEDOC_SERVER_URL: https://livedoc-viewer.internal.co
    LIVEDOC_PROJECT: my-app
    LIVEDOC_ENVIRONMENT: ci
No Viewer in CI?

If you don't run a Viewer in CI, use ExportPath to generate a JSON file for static HTML reports. See Export Configuration.

Complete Workflow​

Here's the full local workflow from start to finish:

# Terminal 1: Start the viewer
livedoc-viewer

# Terminal 2: Run your tests (auto-discovery connects automatically)
dotnet test --logger LiveDoc
  1. Start the viewer — open a terminal and run livedoc-viewer
  2. Run your tests — in a separate terminal, run dotnet test --logger LiveDoc
  3. View results — open http://localhost:3100 and watch results stream in

Troubleshooting​

ProblemCauseSolution
Results don't appear in viewerViewer not running when tests startStart livedoc-viewer before running dotnet test — auto-discovery pings at startup
Connection refusedViewer not running or wrong portStart livedoc-viewer first; if using a non-default port, set LIVEDOC_SERVER_URL
Tests pass but viewer shows nothingFirewall blocking localhostAllow port 3100 through your firewall
Results appear but unorganizedFlat namespace structureOrganize tests into nested namespaces — see Best Practices
Viewer shows stale resultsBrowser cache or previous session dataRefresh the browser or restart the viewer
Project shows assembly nameNo custom project name setSet LIVEDOC_PROJECT environment variable
Project shows "Unknown"Assembly name doesn't end in .Tests/.Test/.SpecsSet LIVEDOC_PROJECT environment variable
Coverage is absentThe run did not request coverageUse --collect:"Code Coverage;Format=Cobertura" or Visual Studio Analyze Code Coverage
dotnet-coverage-missingVisual Studio produced binary .coverage outputInstall dotnet-coverage globally or set LIVEDOC_DOTNET_COVERAGE_TOOL
CI: no results in viewerLIVEDOC_SERVER_URL not setAuto-discovery only checks localhost:3100 — set the env var explicitly in CI

Related​