Interface Tracing

API for collecting and saving Playwright traces. Playwright traces can be opened in Trace Viewer after Playwright script runs.

NOTE You probably want to enable tracing in your config file instead of using context.tracing.

The context.tracing API captures browser operations and network activity, but it doesn't record test assertions (like expect calls). We recommend enabling tracing through Playwright Test configuration, which includes those assertions and provides a more complete trace for debugging test failures.

Start recording a trace before performing actions. At the end, stop tracing and save it to a file.

const browser = await chromium.launch();
const context = await browser.newContext();
await context.tracing.start({ screenshots: true, snapshots: true });
const page = await context.newPage();
await page.goto('https://playwright.dev');
expect(page.url()).toBe('https://playwright.dev');
await context.tracing.stop({ path: 'trace.zip' });

interface Tracing {
    group(
        name: string,
        options?: { location?: { column?: number; file: string; line?: number } },
    ): Promise<Disposable>;
    groupEnd(): Promise<void>;
    start(
        options?: {
            live?: boolean;
            name?: string;
            screenshots?: boolean;
            snapshots?: boolean;
            sources?: boolean;
            title?: string;
        },
    ): Promise<void>;
    startChunk(options?: { name?: string; title?: string }): Promise<void>;
    startHar(
        path: string,
        options?: {
            content?: "embed" | "attach" | "omit";
            mode?: "full" | "minimal";
            resourcesDir?: string;
            urlFilter?: string | RegExp;
        },
    ): Promise<Disposable>;
    stop(options?: { path?: string }): Promise<void>;
    stopChunk(options?: { path?: string }): Promise<void>;
    stopHar(): Promise<void>;
}

Index

Methods

group groupEnd start startChunk startHar stop stopChunk stopHar

Methods

group

group(
name: string,
options?: { location?: { column?: number; file: string; line?: number } },
): Promise<Disposable>
NOTE Use test.step instead when available.

Creates a new group within the trace, assigning any subsequent API calls to this group, until tracing.groupEnd() is called. Groups can be nested and will be visible in the trace viewer.

Usage
```
// use test.step instead
await test.step('Log in', async () => {
  // ...
});
```
Parameters
- name: string
  Group name shown in the trace viewer.
- Optionaloptions: { location?: { column?: number; file: string; line?: number } }
  - Optionallocation?: { column?: number; file: string; line?: number }
    
    Specifies a custom location for the group to be shown in the trace viewer. Defaults to the location of the tracing.group(name[, options]) call.
Returns Promise<Disposable>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:22796

groupEnd

groupEnd(): Promise<void>
Closes the last group created by tracing.group(name[, options]).

Returns Promise<void>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:22814

start

start(
    options?: {
        live?: boolean;
        name?: string;
        screenshots?: boolean;
        snapshots?: boolean;
        sources?: boolean;
        title?: string;
    },
): Promise<void>
Start tracing.

NOTE You probably want to enable tracing in your config file instead of using Tracing.start.

The context.tracing API captures browser operations and network activity, but it doesn't record test assertions (like expect calls). We recommend enabling tracing through Playwright Test configuration, which includes those assertions and provides a more complete trace for debugging test failures.

Usage
```
await context.tracing.start({ screenshots: true, snapshots: true });
const page = await context.newPage();
await page.goto('https://playwright.dev');
expect(page.url()).toBe('https://playwright.dev');
await context.tracing.stop({ path: 'trace.zip' });
```
Parameters
- Optionaloptions: {
      live?: boolean;
      name?: string;
      screenshots?: boolean;
      snapshots?: boolean;
      sources?: boolean;
      title?: string;
  }
  - Optionallive?: boolean
    
    When enabled, the trace is written to an unarchived file that is updated in real time as actions occur, instead of caching changes and archiving them into a zip file at the end. This is useful for live trace viewing during test execution.
  - Optionalname?: string
    
    If specified, intermediate trace files are going to be saved into the files with the given name prefix inside the tracesDir directory specified in browserType.launch([options]). To specify the final trace zip file name, you need to pass path option to tracing.stop([options]) instead.
  - Optionalscreenshots?: boolean
    
    Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview.
  - Optionalsnapshots?: boolean
    
    If this option is true tracing will
    
    capture DOM snapshot on every action
    
    record network activity
  - Optionalsources?: boolean
    
    Whether to include source files for trace actions.
  - Optionaltitle?: string
    
    Trace name to be shown in the Trace Viewer.
Returns Promise<void>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:22840

startChunk

startChunk(options?: { name?: string; title?: string }): Promise<void>
Start a new trace chunk. If you'd like to record multiple traces on the same BrowserContext, use tracing.start([options]) once, and then create multiple trace chunks with tracing.startChunk([options]) and tracing.stopChunk([options]).

Usage
```
await context.tracing.start({ screenshots: true, snapshots: true });
const page = await context.newPage();
await page.goto('https://playwright.dev');

await context.tracing.startChunk();
await page.getByText('Get Started').click();
// Everything between startChunk and stopChunk will be recorded in the trace.
await context.tracing.stopChunk({ path: 'trace1.zip' });

await context.tracing.startChunk();
await page.goto('http://example.com');
// Save a second trace file with different actions.
await context.tracing.stopChunk({ path: 'trace2.zip' });
```
Parameters
- Optionaloptions: { name?: string; title?: string }
  - Optionalname?: string
    
    If specified, intermediate trace files are going to be saved into the files with the given name prefix inside the tracesDir directory specified in browserType.launch([options]). To specify the final trace zip file name, you need to pass path option to tracing.stopChunk([options]) instead.
  - Optionaltitle?: string
    
    Trace name to be shown in the Trace Viewer.
Returns Promise<void>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:22909

startHar

startHar(
    path: string,
    options?: {
        content?: "embed" | "attach" | "omit";
        mode?: "full" | "minimal";
        resourcesDir?: string;
        urlFilter?: string | RegExp;
    },
): Promise<Disposable>
Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when tracing.stopHar() is called, or when the returned Disposable is disposed.

Only one HAR recording can be active at a time per BrowserContext.

Usage
```
await context.tracing.startHar('trace.har');
const page = await context.newPage();
await page.goto('https://playwright.dev');
await context.tracing.stopHar();
```
Parameters
- path: string
  Path on the filesystem to write the HAR file to. If the file name ends with .zip, the HAR is saved as a zip archive with response bodies attached as separate files.
- Optionaloptions: {
      content?: "embed" | "attach" | "omit";
      mode?: "full" | "minimal";
      resourcesDir?: string;
      urlFilter?: string | RegExp;
  }
  - Optionalcontent?: "embed" | "attach" | "omit"
    
    Optional setting to control resource content management. If omit is specified, content is not persisted. If attach is specified, resources are persisted as separate files or entries in the ZIP archive. If embed is specified, content is stored inline the HAR file as per HAR specification. Defaults to attach for .zip output files and to embed for all other file extensions.
  - Optionalmode?: "full" | "minimal"
    
    When set to minimal, only record information necessary for routing from HAR. This omits sizes, timing, page, cookies, security and other types of HAR information that are not used when replaying from HAR. Defaults to full.
  - OptionalresourcesDir?: string
    
    Only used together with content: 'attach'. When set, response bodies are placed in this directory instead of next to the HAR file. Not compatible with a .zip HAR file.
  - OptionalurlFilter?: string | RegExp
    
    A glob or regex pattern to filter requests that are stored in the HAR. Defaults to none.
Returns Promise<Disposable>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:22947

stop

stop(options?: { path?: string }): Promise<void>
Stop tracing.
Parameters
- Optionaloptions: { path?: string }
  - Optionalpath?: string
    
    Export trace into the file with the given path.
Returns Promise<void>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:22978

stopChunk

stopChunk(options?: { path?: string }): Promise<void>
Stop the trace chunk. See tracing.startChunk([options]) for more details about multiple trace chunks.
Parameters
- Optionaloptions: { path?: string }
  - Optionalpath?: string
    
    Export trace collected since the last tracing.startChunk([options]) call into the file with the given path.
Returns Promise<void>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:22991

stopHar

stopHar(): Promise<void>
Stop HAR recording and save the HAR file to the path given to tracing.startHar(path[, options]).

Returns Promise<void>
- Defined in node_modules/.pnpm/playwright-core@1.62.1/node_modules/playwright-core/types/types.d.ts:23004

Interface Tracing

Index

Methods

Methods

group

Parameters

Optionallocation?: { column?: number; file: string; line?: number }

Returns Promise<Disposable>

groupEnd

Returns Promise<void>

start

Parameters

Optionallive?: boolean

Optionalname?: string

Optionalscreenshots?: boolean

Optionalsnapshots?: boolean

Optionalsources?: boolean

Optionaltitle?: string

Returns Promise<void>

startChunk

Parameters

Optionalname?: string

Optionaltitle?: string

Returns Promise<void>

startHar

Parameters

Optionalcontent?: "embed" | "attach" | "omit"

Optionalmode?: "full" | "minimal"

OptionalresourcesDir?: string

OptionalurlFilter?: string | RegExp

Returns Promise<Disposable>

stop

Parameters

Optionalpath?: string

Returns Promise<void>

stopChunk

Parameters

Optionalpath?: string

Returns Promise<void>

stopHar

Returns Promise<void>

Settings

On This Page

`Optional`location?: { column?: number; file: string; line?: number }

`Optional`live?: boolean

`Optional`name?: string

`Optional`screenshots?: boolean

`Optional`snapshots?: boolean

`Optional`sources?: boolean

`Optional`title?: string

`Optional`name?: string

`Optional`title?: string

`Optional`content?: "embed" | "attach" | "omit"

`Optional`mode?: "full" | "minimal"

`Optional`resourcesDir?: string

`Optional`urlFilter?: string | RegExp

`Optional`path?: string

`Optional`path?: string