Principle:Microsoft Playwright Configure Trace Collection
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Testing |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Configuring when and how execution traces are collected during test runs for post-mortem debugging.
Description
Trace collection configuration is the foundational step in any trace-based debugging workflow. Before traces can be recorded, analyzed, or viewed, the testing framework must be told when to capture traces (always, on failure, on retry, never) and what to include in those traces (DOM snapshots, screenshots, source code, attachments).
This principle addresses the design decision of making trace collection configurable rather than always-on. Traces impose a performance overhead: they capture DOM snapshots, intercept network traffic, and record screenshots. By allowing developers to specify a trace mode, the framework ensures that production-like test runs remain fast while debugging-oriented runs capture rich diagnostic data.
The key insight is that trace collection needs are context-dependent:
- During local development: Traces may be always on for immediate feedback.
- In CI pipelines: Traces should only be captured on failure or retry to minimize resource usage while still providing diagnostic data when tests fail.
- For flaky test investigation: Traces should be captured on retries to compare passing and failing runs.
The configuration also governs the granularity of captured data. Not all trace scenarios require every data type. For example, a network-focused investigation may only need HAR data without DOM snapshots, while a visual regression investigation benefits from screenshots without source code.
Usage
Apply this principle whenever setting up a test suite that may need post-mortem debugging capabilities. The trace configuration should be:
- Set in the project configuration file (e.g., playwright.config.ts) for consistent behavior across all team members.
- Overridable via CLI flags for ad-hoc debugging sessions.
- Tuned per environment: aggressive collection in development, conservative collection in CI.
Theoretical Basis
At an abstract level, trace collection configuration follows the observer pattern with conditional activation. The system registers a trace observer on the test execution pipeline, but the observer only activates its recording machinery when its activation predicate evaluates to true.
The activation predicate is a function of:
- Mode: A symbolic constant describing the collection strategy (e.g., always, on-failure, on-retry).
- Run context: Runtime properties such as retry count, test status, and environment variables.
Pseudocode for the decision logic:
function shouldCaptureTrace(mode, retryCount, testStatus):
if mode == 'on':
return true
if mode == 'retain-on-failure':
return true // capture always, discard if passing
if mode == 'on-first-retry' and retryCount == 1:
return true
if mode == 'on-all-retries' and retryCount > 0:
return true
if mode == 'retain-on-first-failure' and retryCount == 0:
return true // capture on first run, discard if passing
return false
The retain modes represent a refinement: they capture data speculatively during execution but discard it if the test passes. This avoids the cold-start penalty of enabling tracing only after a failure has occurred (by which point the execution data is lost), while still keeping storage costs low for passing tests.
The configuration object itself follows a union type pattern: it can be a simple string (the mode) or a structured object providing fine-grained control over individual trace components. This layered API design lets casual users specify 'on' while power users control each component independently.