Principle:Microsoft Playwright Open Trace Viewer
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Testing |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Launching an interactive viewer to explore recorded traces, inspect actions, view DOM snapshots, and analyze network traffic.
Description
After traces have been collected (see Configure_Trace_Collection and Capture_Trace_Data), the developer needs a way to explore the recorded data interactively. The trace viewer principle addresses the need for a visual debugging environment that reconstructs the test execution from trace files and presents it in a navigable, interactive format.
The trace viewer operates as a local web application that serves trace data through an HTTP server and renders it in a browser-based single-page application (SPA). This architecture choice provides several advantages:
- Cross-platform compatibility: The viewer runs in any modern browser without platform-specific dependencies.
- Rich interactivity: DOM snapshots are rendered as live HTML, allowing inspection with browser DevTools.
- Offline capability: Trace files are self-contained ZIP archives that can be shared and viewed without access to the original test environment.
- Remote access: The HTTP server can be exposed on a network for team collaboration.
The viewer provides multiple inspection modes:
- Action timeline: A chronological list of all Playwright API calls with their parameters, duration, and outcome (pass/fail).
- DOM snapshots: Live-rendered HTML snapshots showing the page state before and after each action, with the target element highlighted.
- Network panel: A HAR-viewer-style panel showing all network requests with full request/response details.
- Console log: All console messages captured during execution.
- Source code: The test source code with the current action highlighted and error locations annotated.
- Attachments: Test attachments such as screenshots, videos, and custom data.
Usage
Apply this principle when:
- Debugging a failed test: Open the trace attached to a failed test to understand what happened step by step.
- Investigating flaky tests: Compare traces from passing and failing runs to identify non-deterministic behavior.
- Reviewing test behavior: Use the trace viewer as a visual record of test execution for code review or documentation.
- CI artifact inspection: Download trace ZIP files from CI and open them locally for investigation.
Theoretical Basis
The trace viewer follows the time-travel debugging paradigm, where the developer can navigate backward and forward through the execution timeline, inspecting the system state at any point.
The abstract architecture:
// Server component
function startTraceViewerServer(options):
server = createHttpServer()
// Route: Serve trace files from local filesystem
server.route('/trace/file', (request) =>
filePath = request.params.path
return readAndServe(filePath)
)
// Route: Serve the viewer SPA (HTML/JS/CSS)
server.route('/trace/*', (request) =>
return serveStaticFile(viewerDir, request.path)
)
// Optional: WebSocket for live trace updates
if options.transport:
server.createWebSocket(options.transport)
server.listen(options.port, options.host)
return server
// App component
function openTraceViewer(traceUrl, server):
// Option 1: Open in a dedicated Chromium app window
page = launchChromiumApp(server.url)
return page
// Option 2: Open in the user's default browser
openInDefaultBrowser(server.url)
Key design principles:
- URL-based trace loading: Traces are identified by URL (file path or HTTP URL), enabling both local files and remote trace servers. The URL is validated before loading to provide clear error messages for missing files.
- Directory-based trace discovery: When pointed at a directory rather than a specific file, the viewer discovers all trace files within it and presents them as a composite view. This supports the common pattern of viewing all traces from a test run.
- Dual launch modes: The viewer can open as a dedicated Chromium app window (for a native-app-like experience) or in the default browser (for integration with existing browser workflows).
- Live trace support: When used in UI mode, the viewer connects to the test runner via WebSocket and updates in real-time as tests execute, providing a live debugging experience.