Implementation:Microsoft Playwright Trace Mode Config

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

Overview

Concrete configuration API for controlling when and how Playwright collects execution traces during test runs.

Description

Playwright provides a trace configuration option in the test configuration file and via CLI flags. This option accepts either a simple TraceMode string specifying the collection strategy, or a structured object that additionally controls which data types (snapshots, screenshots, sources, attachments) are included in the trace.

The configuration is resolved at test startup time by the TestTracing class, which evaluates the mode against the current test's retry count and status to determine whether tracing should be active. The _shouldCaptureTrace() method implements the core decision logic, returning true if the mode and test context warrant trace collection.

The supported trace modes are:

• off: No traces are collected.
• on: Traces are always collected for every test run.
• retain-on-failure: Traces are collected for every run but discarded if the test passes. This provides post-mortem data without accumulating trace files for passing tests.
• on-first-retry: Traces are collected only on the first retry (retry count == 1), minimizing overhead for the initial run.
• on-all-retries: Traces are collected on all retries (retry count > 0).
• retain-on-first-failure: Traces are collected on the first run (retry count == 0) but discarded if the test passes.

When using the object form, developers can independently toggle:

• snapshots: DOM snapshot capture (default: true).
• screenshots: Screencast frame capture (default: true).
• sources: Test source file inclusion in trace ZIP (default: true).
• attachments: Test attachment inclusion in trace ZIP (default: true).

Usage

Use this configuration to set up tracing in playwright.config.ts or override it from the command line:

• Set trace: 'on-first-retry' in CI configurations to capture traces only when tests need retrying.
• Set trace: 'on' during local development for always-available trace data.
• Use the object form when you need to reduce trace file size by disabling specific data types.
• Override with --trace on CLI flag for ad-hoc debugging of specific test runs.

Code Reference

Source Location

• Repository: playwright
• Primary file: packages/playwright/src/worker/testTracing.ts (Lines 40-99)
• Type definitions: packages/playwright/types/test.d.ts (Lines 6924-6956)

Signature

// In playwright.config.ts use() options:
trace: TraceMode | {
  mode: TraceMode;
  snapshots?: boolean;
  screenshots?: boolean;
  sources?: boolean;
  attachments?: boolean;
};

// TraceMode type:
type TraceMode = 'off' | 'on' | 'retain-on-failure' | 'on-first-retry'
  | 'on-all-retries' | 'retain-on-first-failure';

// Internal TraceOptions resolved from the config:
type TraceOptions = {
  screenshots: boolean;
  snapshots: boolean;
  sources: boolean;
  attachments: boolean;
  _live: boolean;
  mode: TraceMode;
};

Import

// In playwright.config.ts:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

// CLI override:
// npx playwright test --trace on

I/O Contract

Inputs

Name	Type	Required	Description
trace	TraceObject	No	The trace configuration value from playwright.config.ts use options. Defaults to 'off' if not specified.
mode	TraceMode	No	When using the object form, the collection strategy. Defaults to 'off'.
snapshots	boolean	No	Whether to capture DOM snapshots before and after each action. Defaults to true.
screenshots	boolean	No	Whether to capture screencast frames during execution. Defaults to true.
sources	boolean	No	Whether to include test source files in the trace ZIP. Defaults to true.
attachments	boolean	No	Whether to include test attachments in the trace ZIP. Defaults to true.
--trace	string	No	CLI flag override. Accepts any TraceMode value. Defined at program.ts:L432.

Outputs

Name	Type	Description
TraceOptions	object	The resolved internal options object used by TestTracing to determine capture behavior.
shouldCapture	boolean	The result of _shouldCaptureTrace(), determining whether tracing is active for the current test run.
trace.zip	file	When tracing is active and the test completes, a ZIP file containing all trace data is attached to the test result at testInfo.outputPath('trace.zip').

Usage Examples

Basic Example

// playwright.config.ts - Simple mode
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
  retries: 2,
});

Advanced Example

// playwright.config.ts - Object form with selective capture
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: {
      mode: 'retain-on-failure',
      snapshots: true,
      screenshots: true,
      sources: false,      // Exclude sources to reduce trace size
      attachments: false,  // Exclude attachments
    },
  },
});

CLI Override Example

# Enable tracing for all tests in a single run
npx playwright test --trace on

# Retain traces only for failing tests
npx playwright test --trace retain-on-failure

Decision Logic Reference

// From testTracing.ts:L70-87 - _shouldCaptureTrace()
private _shouldCaptureTrace() {
  if (this._options?.mode === 'on')
    return true;
  if (this._options?.mode === 'retain-on-failure')
    return true;
  if (this._options?.mode === 'on-first-retry' && this._testInfo.retry === 1)
    return true;
  if (this._options?.mode === 'on-all-retries' && this._testInfo.retry > 0)
    return true;
  if (this._options?.mode === 'retain-on-first-failure' && this._testInfo.retry === 0)
    return true;
  return false;
}

Related Pages

Implements Principle

• Principle:Microsoft_Playwright_Configure_Trace_Collection