Implementation:Microsoft Playwright TraceViewer Server

Knowledge Sources	Playwright Playwright Trace Viewer Playwright CLI
Domains	Debugging, Testing
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete tool for launching the Playwright Trace Viewer as an HTTP server and optionally opening it in a browser application, provided by the Playwright library.

Description

The Trace Viewer Server module provides the infrastructure for serving trace data and the trace viewer single-page application (SPA) to a browser. It consists of several exported functions that handle different aspects of the viewer lifecycle:

startTraceViewerServer() (Lines 81-120) creates and configures an HttpServer instance with two route handlers:

• /trace/file?path=... serves trace files directly from the local filesystem. It also handles special cases: .json paths trigger synthetic trace descriptors for zip-less operation, and paths ending with traces.dir return all trace files in a directory.
• /trace/* serves the viewer SPA's static files (HTML, JavaScript, CSS) from the built vite/traceViewer/ directory.

If a transport is provided (e.g., StdinServer for UI mode), a WebSocket is created for live communication between the viewer and the test runner.

installRootRedirect() (Lines 122-152) configures the root URL to redirect to the viewer SPA with appropriate query parameters including the trace URL, WebSocket GUID, path separator, and any filter options (grep, project, reporter).

runTraceViewerApp() (Lines 154-162) is the main entry point for opening the viewer as a dedicated Chromium application window. It validates the trace path, starts the server, installs the redirect, and launches a persistent Chromium context with a 1280x800 window.

runTraceInBrowser() (Lines 164-169) opens the trace viewer in the user's default system browser instead of a dedicated Chromium window.

openTraceViewerApp() (Lines 171-204) handles the Chromium app launch using Playwright's own launchApp() utility. It creates an internal Playwright instance, launches a persistent browser context, syncs local storage settings, and navigates to the viewer URL.

validateTraceUrlOrPath() (Lines 58-79) validates and normalizes trace file paths. It handles HTTP URLs (passed through), .json paths (converted to file URLs), directories (appended with traces.dir marker), and missing files (throws an error).

Usage

Use this tool when:

• Viewing traces from the CLI: Run npx playwright show-trace trace.zip which internally calls runTraceViewerApp().
• Viewing traces in the browser: Use --browser flag to open in the default browser via runTraceInBrowser().
• Embedding the viewer: Use startTraceViewerServer() programmatically to host the viewer in custom tooling.
• Live tracing in UI mode: The test runner uses startTraceViewerServer() with a WebSocket transport for real-time trace updates.

Code Reference

Source Location

• Repository: playwright
• File: packages/playwright-core/src/server/trace/viewer/traceViewer.ts (Lines 81-204)

Signature

// Server options
type TraceViewerServerOptions = {
  host?: string;
  port?: number;
  isServer?: boolean;
  transport?: Transport;
};

// App options
type TraceViewerAppOptions = {
  headless?: boolean;
  persistentContextOptions?: Parameters<BrowserType['launchPersistentContext']>[2];
};

// Redirect options
type TraceViewerRedirectOptions = {
  args?: string[];
  grep?: string;
  grepInvert?: string;
  project?: string[];
  reporter?: string[];
  webApp?: string;
  isServer?: boolean;
};

// Main exported functions
async function startTraceViewerServer(
  options?: TraceViewerServerOptions
): Promise<HttpServer>;

async function installRootRedirect(
  server: HttpServer,
  traceUrl: string | undefined,
  options: TraceViewerRedirectOptions
): Promise<void>;

async function runTraceViewerApp(
  traceUrl: string | undefined,
  browserName: string,
  options: TraceViewerServerOptions & { headless?: boolean },
  exitOnClose?: boolean
): Promise<Page>;

async function runTraceInBrowser(
  traceUrl: string | undefined,
  options: TraceViewerServerOptions
): Promise<void>;

async function openTraceViewerApp(
  url: string,
  browserName: string,
  options?: TraceViewerAppOptions
): Promise<Page>;

Import

// Internal import (used by Playwright CLI):
import {
  startTraceViewerServer,
  runTraceViewerApp,
  runTraceInBrowser,
} from 'playwright-core/src/server/trace/viewer/traceViewer';

// CLI usage:
// npx playwright show-trace trace.zip
// npx playwright show-trace trace.zip --browser
// npx playwright show-trace https://example.com/trace.zip

I/O Contract

Inputs

Name	Type	Required	Description
traceUrl	undefined	No	Path to a trace ZIP file, directory, JSON descriptor, or HTTP URL. Validated by validateTraceUrlOrPath().
host	string	No	Host address for the HTTP server. Defaults to localhost.
port	number	No	Port number for the HTTP server. Defaults to auto-selected available port.
isServer	boolean	No	Whether to run in server mode with stdin transport for receiving trace URLs.
transport	Transport	No	WebSocket transport implementation for live communication (e.g., StdinServer).
browserName	string	No	Browser to use for the viewer app (chromium, firefox, webkit). Defaults to chromium in tests.
headless	boolean	No	Whether to launch the viewer browser in headless mode. Default: false.
exitOnClose	boolean	No	Whether to exit the process when the viewer window is closed.

Outputs

Name	Type	Description
HttpServer	HttpServer	The running HTTP server instance. Provides urlPrefix() for the server URL.
Page	Page	When using runTraceViewerApp() or openTraceViewerApp(), the Chromium Page object of the viewer app.
Console output	string	When using runTraceInBrowser(), the server URL is printed to the console.

Usage Examples

Basic Example

# View a trace file in a dedicated Chromium window
npx playwright show-trace test-results/my-test/trace.zip

# View a trace file in the default browser
npx playwright show-trace test-results/my-test/trace.zip --browser

# View a remote trace file
npx playwright show-trace https://example.com/traces/my-trace.zip

# View all traces in a directory
npx playwright show-trace test-results/my-test/

Programmatic Server Example

import { startTraceViewerServer, installRootRedirect } from
  'playwright-core/lib/server/trace/viewer/traceViewer';

// Start the trace viewer server
const server = await startTraceViewerServer({ port: 9323 });

// Install redirect to a specific trace
await installRootRedirect(server, 'file?path=/path/to/trace.zip', {});

console.log('Trace viewer available at:', server.urlPrefix('human-readable'));
// Output: Trace viewer available at: http://localhost:9323

Trace Validation Example

// The validateTraceUrlOrPath function handles multiple input formats:

// HTTP URL - passed through:
// 'https://example.com/trace.zip' -> 'https://example.com/trace.zip'

// Local file - converted to file URL:
// '/path/to/trace.zip' -> 'file?path=%2Fpath%2Fto%2Ftrace.zip'

// Directory - appended with traces.dir marker:
// '/path/to/traces/' -> 'file?path=%2Fpath%2Fto%2Ftraces%2Ftraces.dir'

// JSON descriptor - converted to file URL:
// '/path/to/trace.json' -> 'file?path=%2Fpath%2Fto%2Ftrace.json'

// Non-existent file - throws error:
// '/missing/trace.zip' -> Error: Trace file /missing/trace.zip does not exist!

Related Pages

Implements Principle

• Principle:Microsoft_Playwright_Open_Trace_Viewer