Skip to main content

How to Set Up Multiple Projects

Docs for LiveDoc Viewer v0.4.0

This guide shows you how to configure multiple projects and environments to send test results to a single LiveDoc Viewer instance. By the end, you'll have a shared dashboard that organizes results by project and environment.

Prerequisites
  • The LiveDoc Viewer running (Getting Started)
  • At least two projects with LiveDoc reporters configured

Overview​

A single LiveDoc Viewer instance can receive results from multiple test projects and environments simultaneously. The viewer organizes results into a hierarchy:

Each combination of project + environment maintains its own run history, and the viewer's project selector lets you switch between them.

Step 1: Configure Project Identity​

Each project sets its project and environment fields in the reporter configuration:

// packages/api/vitest.config.ts
import { defineConfig } from 'vitest/config';
import {
  LiveDocSpecReporter,
  LiveDocViewerReporter,
} from '@swedevtools/livedoc-vitest/reporter';

export default defineConfig({
  test: {
    include: ['**/*.Spec.ts'],
    globals: true,
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: 'spec+summary+headers',
        postReporters: [
          new LiveDocViewerReporter({
            server: 'http://localhost:3100',
            project: 'my-api',            // ← Project name
            environment: 'local',          // ← Environment label
          }),
        ],
      }),
    ],
  },
});
// packages/web/vitest.config.ts
export default defineConfig({
  test: {
    include: ['**/*.Spec.ts'],
    globals: true,
    reporters: [
      new LiveDocSpecReporter({
        detailLevel: 'spec+summary+headers',
        postReporters: [
          new LiveDocViewerReporter({
            server: 'http://localhost:3100',
            project: 'my-web-app',         // ← Different project
            environment: 'local',
          }),
        ],
      }),
    ],
  },
});

Step 2: Run Tests​

Start the viewer once, then run tests from each project. Results are organized automatically:

# Terminal 1: Start the viewer
livedoc-viewer

# Terminal 2: Run API tests
cd packages/api && npx vitest run

# Terminal 3: Run web tests
cd packages/web && npx vitest run

Both projects' results appear in the viewer under their respective project names.

Step 3: Navigate in the Viewer​

In the viewer dashboard:

  1. Use the Project selector dropdown at the top to switch between my-api and my-web-app
  2. Use the Environment selector to filter by local, ci, or other environments
  3. Each project/environment combination has its own run history

Logical Grouping for Split Test Projects​

Sometimes multiple test projects belong to the same product. For example, checkout.unit.tests, checkout.integration.tests, and checkout.e2e.tests may all describe one checkout application. When those projects run together, the viewer can group them into a single logical project.

The viewer only creates a group when projects share a root prefix, use the same environment, and run as one logical execution. Runs can overlap, or one run can start within 60 seconds of another grouped run completing.

The first time a group is detected, the viewer asks whether to use the grouped view or keep individual projects. You can change this later from Viewer settings:

SettingWhat it does
Group related test projectsEnables or disables logical project grouping
Hide grouped source projectsHides physical test projects from the project selector once they are represented by a group
Always show latest runFollows the newest live execution instead of preserving the current historical selection

Even when source projects are hidden from the selector, they remain visible as folders inside the grouped run. This keeps the project list clean while still showing which test project produced each feature or specification.

The project selector shows only the newest logical group for each project/environment. Older grouped executions remain available in the Run menu.

Multi-project selector

Environment Naming Conventions​

Choose environment names that reflect your deployment contexts:

EnvironmentWhen to use
localDeveloper workstation during local development
ciContinuous integration pipeline
stagingPre-production environment
productionProduction smoke tests or monitors

Dynamic Environment Labels​

Use environment variables to set the label automatically:

new LiveDocViewerReporter({
  server: 'http://localhost:3100',
  project: 'my-api',
  environment: process.env.LIVEDOC_ENV
    || (process.env.CI ? 'ci' : 'local'),
}),

Monorepo Setup​

In a monorepo, each package typically has its own vitest.config.ts. Set a unique project name per package:

my-monorepo/
├── packages/
│   ├── auth/        → project: "auth-service"
│   ├── billing/     → project: "billing-service"
│   └── web/         → project: "web-app"
└── livedoc-viewer   → single shared viewer

All packages point to the same viewer URL. The viewer's project selector shows all three projects.

Querying Multi-Project Data via API​

Use the REST API to query the hierarchy programmatically:

# List all projects and their environments
curl -s http://localhost:3100/api/hierarchy | jq .

# List runs for a specific project (filter client-side)
curl -s http://localhost:3100/api/runs | jq '.[] | select(.project == "my-api")'

Key Takeaways​

  • project groups results by application or service
  • environment distinguishes deployment contexts (local, CI, staging)
  • A single viewer handles multiple projects and environments
  • Each project + environment combo has independent run history
  • The hierarchy API exposes the full project → environment → run tree

See Also​