Trace Viewer

Relevant source files

• docs/src/api/class-screencast.md
• docs/src/api/class-video.md
• packages/html-reporter/package.json
• packages/playwright-core/src/client/channelOwner.ts
• packages/playwright-core/src/client/clientInstrumentation.ts
• packages/playwright-core/src/client/connection.ts
• packages/playwright-core/src/client/screencast.ts
• packages/playwright-core/src/client/video.ts
• packages/playwright-core/src/server/dispatchers/dispatcher.ts
• packages/playwright-core/src/server/index.ts
• packages/playwright-core/src/server/screencast.ts
• packages/playwright-core/src/server/trace/recorder/snapshotter.ts
• packages/playwright-core/src/server/trace/recorder/snapshotterInjected.ts
• packages/playwright-core/src/server/trace/recorder/tracing.ts
• packages/recorder/package.json
• packages/trace-viewer/package.json
• packages/trace-viewer/src/sw/main.ts
• packages/trace-viewer/src/ui/actionList.css
• packages/trace-viewer/src/ui/actionList.tsx
• packages/trace-viewer/src/ui/callTab.css
• packages/trace-viewer/src/ui/callTab.tsx
• packages/trace-viewer/src/ui/copyToClipboard.css
• packages/trace-viewer/src/ui/copyToClipboard.tsx
• packages/trace-viewer/src/ui/filmStrip.css
• packages/trace-viewer/src/ui/filmStrip.tsx
• packages/trace-viewer/src/ui/snapshotTab.css
• packages/trace-viewer/src/ui/snapshotTab.tsx
• packages/trace-viewer/src/ui/sourceTab.css
• packages/trace-viewer/src/ui/sourceTab.tsx
• packages/trace-viewer/src/ui/timeline.css
• packages/trace-viewer/src/ui/timeline.tsx
• packages/trace-viewer/src/ui/uiModeTraceView.tsx
• packages/trace-viewer/src/ui/workbench.tsx
• packages/trace-viewer/src/ui/workbenchLoader.css
• packages/trace-viewer/src/ui/workbenchLoader.tsx
• packages/trace-viewer/src/vite-env.d.ts
• packages/trace/src/trace.ts
• packages/web/src/ansi2html.ts
• packages/web/src/components/errorMessage.tsx
• packages/web/src/components/listView.css
• packages/web/src/components/listView.tsx
• packages/web/src/components/treeView.tsx
• tests/config/traceViewerFixtures.ts
• tests/config/utils.ts
• tests/library/browsercontext-credentials.spec.ts
• tests/library/download.spec.ts
• tests/library/emulation-focus.spec.ts
• tests/library/heap.spec.ts
• tests/library/permissions.spec.ts
• tests/library/screencast.spec.ts
• tests/library/screenshot.spec.ts
• tests/library/trace-viewer.spec.ts
• tests/library/tracing.spec.ts
• tests/library/video.spec.ts

The Trace Viewer is a standalone browser-based application for inspecting .zip trace archives produced by Playwright's tracing API. It provides a post-mortem debugging experience by rendering recorded actions, DOM snapshots, screenshots, network traffic, console output, and source code in an interactive interface.

---

High-Level Architecture

The Trace Viewer consists of a Node.js backend that serves trace data and a React frontend that visualizes it.

Diagram: Trace Viewer System Overview

Sources: packages/playwright-core/cli.js1-20 packages/trace-viewer/src/ui/workbenchLoader.tsx26-37 packages/trace-viewer/src/ui/workbench.tsx67-72

---

Trace Server Infrastructure

The Trace Viewer is launched via the show-trace command. The server infrastructure is responsible for:

1. Serving Assets: Delivering the built React application and static resources.
2. Data Retrieval: Responding to requests for specific trace artifacts (images, network HARs, source files) using content-addressable storage (SHA-1).
3. Local Network Access: Handling permission prompts for local file access when fetching assets from the service worker packages/trace-viewer/src/ui/workbenchLoader.tsx159-163

The WorkbenchLoader component manages the initial loading state. It supports:

• File Drag-and-Drop: Processing .zip files dropped into the browser packages/trace-viewer/src/ui/workbenchLoader.tsx88-91
• Service Worker Integration: Using a service worker to intercept requests and stream trace data, providing progress updates to the UI packages/trace-viewer/src/ui/workbenchLoader.tsx151-154
• Remote Connection: Connecting to a TestServer via WebSocket when running in "server mode" packages/trace-viewer/src/ui/workbenchLoader.tsx111-121

Sources: packages/trace-viewer/src/ui/workbenchLoader.tsx102-174 tests/config/traceViewerFixtures.ts153-186

---

UI Component Hierarchy

The Workbench is the root UI component that composes the layout panels using SplitView and TabbedPane.

Diagram: Workbench Component Tree

Sources: packages/trace-viewer/src/ui/workbench.tsx67-210 packages/trace-viewer/src/ui/snapshotTab.tsx45-104

---

ActionList

The ActionList packages/trace-viewer/src/ui/actionList.tsx51-129 renders the hierarchical tree of actions recorded during the trace.

• Tree Construction: Uses buildActionTree to convert a flat list of ActionTraceEventInContext into a nested ActionTreeItem structure packages/trace-viewer/src/ui/actionList.tsx66
• Rendering: Each action row displays the method name, formatted parameters, duration, and status icons (error/warning) packages/trace-viewer/src/ui/actionList.tsx131-167
• Locator Preview: If an action has a selector, it renders a generated locator description (e.g., page.getByRole('button')) packages/trace-viewer/src/ui/actionList.tsx145
• Filtering: Supports filtering actions by text or by categories via the isVisible callback packages/trace-viewer/src/ui/actionList.tsx86-95

Sources: packages/trace-viewer/src/ui/actionList.tsx51-167 packages/trace-viewer/src/ui/workbench.tsx104-114

---

SnapshotTabsView

The SnapshotTabsView packages/trace-viewer/src/ui/snapshotTab.tsx45-104 is responsible for rendering DOM snapshots. It manages the "Action", "Before", and "After" tabs to show state transitions.

Snapshot Rendering Engine

The viewer uses a double-iframe strategy in SnapshotView to prevent flickering when switching between actions packages/trace-viewer/src/ui/snapshotTab.tsx115-161

1. URL Resolution: extendSnapshot constructs URLs for the snapshot HTML and metadata (snapshotInfo) packages/trace-viewer/src/ui/snapshotTab.tsx63-66
2. Snapshot Info: Fetches viewport dimensions and the original page URL via fetchSnapshotInfo to correctly size the iframe packages/trace-viewer/src/ui/snapshotTab.tsx126
3. Injected Script: For the "Action" tab, it can inject a script into the snapshot iframe to provide interactive "Pick Locator" functionality packages/trace-viewer/src/ui/snapshotTab.tsx86-91

Interactive Inspection

When isInspecting is enabled, the SnapshotView enables element picking. It uses the InjectedScript and Recorder classes to generate selectors for elements hovered in the snapshot packages/trace-viewer/src/ui/snapshotTab.tsx25-26

Sources: packages/trace-viewer/src/ui/snapshotTab.tsx45-161 packages/playwright-core/src/server/trace/recorder/tracing.ts128

---

Timeline and FilmStrip

• Timeline: A horizontal bar showing the duration of the test. It renders colored segments for actions, network requests, and console messages packages/trace-viewer/src/ui/timeline.tsx30
• FilmStrip: Renders a sequence of screenshots captured during the trace. It calculates which frames to show based on the available width and provides a hover preview packages/trace-viewer/src/ui/filmStrip.tsx38-50

Sources: packages/trace-viewer/src/ui/timeline.tsx30 packages/trace-viewer/src/ui/filmStrip.tsx38-50

---

Specialized Tabs

SourceTab

The SourceTab packages/trace-viewer/src/ui/sourceTab.tsx73-124 displays the test code. It highlights the line corresponding to the selected action and provides a stack trace navigator via StackTraceView packages/trace-viewer/src/ui/sourceTab.tsx122 It uses CodeMirrorWrapper for syntax highlighting and can open the file in VS Code via vscode:// protocol links packages/trace-viewer/src/ui/sourceTab.tsx100

ErrorsTab

The ErrorsTab packages/trace-viewer/src/ui/errorsTab.tsx aggregates all errors encountered during the trace. It provides error grouping and consolidated views of associated actions packages/trace-viewer/src/ui/workbench.tsx22

NetworkTab

The NetworkTab packages/trace-viewer/src/ui/networkTab.tsx provides a grid view of all network resources. It supports sorting by columns like "Name", "Method", "Status", and "Duration". Selecting a resource opens the detailed resource view.

Table: NetworkTab Columns

Column	Description
name	File name and URL
method	HTTP method (GET, POST, etc.)
status	HTTP status code
duration	Time taken for the request
size	Transferred resource size

Sources: packages/trace-viewer/src/ui/networkTab.tsx25 packages/trace-viewer/src/ui/sourceTab.tsx73-124 packages/trace-viewer/src/ui/workbench.tsx79-91

---

Data Flow: Recording to Viewing

Diagram: Trace Data Flow

Sources: packages/playwright-core/src/server/trace/recorder/tracing.ts164-182 packages/trace-viewer/src/ui/workbenchLoader.tsx128-144 packages/trace-viewer/src/ui/workbench.tsx67-72