Skip to main content

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.

using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.LaunchAsync();
await using var context = await browser.NewContextAsync();
await context.Tracing.StartAsync(new()
{
  Screenshots = true,
  Snapshots = true
});
var page = await context.NewPageAsync();
await page.GotoAsync("https://playwright.dev");
await context.Tracing.StopAsync(new()
{
  Path = "trace.zip"
});

Methods​

GroupAsync​

Added in: v1.49 tracing.GroupAsync
caution

Use test.step instead when available.

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

Usage

// All actions between GroupAsync and GroupEndAsync
// will be shown in the trace viewer as a group.
await Page.Context.Tracing.GroupAsync("Open Playwright.dev > API");
await Page.GotoAsync("https://playwright.dev/");
await Page.GetByRole(AriaRole.Link, new() { Name = "API" }).ClickAsync();
await Page.Context.Tracing.GroupEndAsync();

Arguments

  • name string#

    Group name shown in the trace viewer.

  • options TracingGroupOptions? (optional)

    • Location Location? (optional)#

      Specifies a custom location for the group to be shown in the trace viewer. Defaults to the location of the Tracing.GroupAsync() call.

Returns

  • [Disposable]#

GroupEndAsync​

Added in: v1.49 tracing.GroupEndAsync

Closes the last group created by Tracing.GroupAsync().

Usage

await Tracing.GroupEndAsync();

Returns

StartAsync​

Added in: v1.12 tracing.StartAsync

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

using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.LaunchAsync();
await using var context = await browser.NewContextAsync();
await context.Tracing.StartAsync(new()
{
  Screenshots = true,
  Snapshots = true
});
var page = await context.NewPageAsync();
await page.GotoAsync("https://playwright.dev");
await context.Tracing.StopAsync(new()
{
  Path = "trace.zip"
});

Arguments

  • options TracingStartOptions? (optional)

    • Live bool? (optional) Added in: v1.59#

      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.

    • Name string? (optional)#

      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.LaunchAsync(). To specify the final trace zip file name, you need to pass path option to Tracing.StopAsync() instead.

    • Screenshots bool? (optional)#

      Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview.

    • Snapshots bool? (optional)#

      If this option is true tracing will

      • capture DOM snapshot on every action
      • record network activity

    • Sources bool? (optional) Added in: v1.17#

      Whether to include source files for trace actions.

    • Title string? (optional) Added in: v1.17#

      Trace name to be shown in the Trace Viewer.

Returns

StartChunkAsync​

Added in: v1.15 tracing.StartChunkAsync

Start a new trace chunk. If you'd like to record multiple traces on the same BrowserContext, use Tracing.StartAsync() once, and then create multiple trace chunks with Tracing.StartChunkAsync() and Tracing.StopChunkAsync().

Usage

using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.LaunchAsync();
await using var context = await browser.NewContextAsync();
await context.Tracing.StartAsync(new()
{
  Screenshots = true,
  Snapshots = true
});
var page = await context.NewPageAsync();
await page.GotoAsync("https://playwright.dev");

await context.Tracing.StartChunkAsync();
await page.GetByText("Get Started").ClickAsync();
// Everything between StartChunkAsync and StopChunkAsync will be recorded in the trace.
await context.Tracing.StopChunkAsync(new()
{
  Path = "trace1.zip"
});

await context.Tracing.StartChunkAsync();
await page.GotoAsync("http://example.com");
// Save a second trace file with different actions.
await context.Tracing.StopChunkAsync(new()
{
  Path = "trace2.zip"
});

Arguments

  • options TracingStartChunkOptions? (optional)

    • Name string? (optional) Added in: v1.32#

      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.LaunchAsync(). To specify the final trace zip file name, you need to pass path option to Tracing.StopChunkAsync() instead.

    • Title string? (optional) Added in: v1.17#

      Trace name to be shown in the Trace Viewer.

Returns

StartHarAsync​

Added in: v1.60 tracing.StartHarAsync

Start recording a HAR (HTTP Archive) of network activity in this context. The HAR file is written to disk when Tracing.StopHarAsync() 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.StartHarAsync("trace.har");
var page = await context.NewPageAsync();
await page.GotoAsync("https://playwright.dev");
await context.Tracing.StopHarAsync();

Arguments

  • 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.

  • options TracingStartHarOptions? (optional)

    • Content enum HarContentPolicy { Omit, Embed, Attach }? (optional)#

      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.

    • Mode enum HarMode { Full, Minimal }? (optional)#

      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.

    • UrlFilter|UrlFilterRegex string? | Regex? (optional)#

      A glob or regex pattern to filter requests that are stored in the HAR. Defaults to none.

Returns

  • [Disposable]#

StopAsync​

Added in: v1.12 tracing.StopAsync

Stop tracing.

Usage

await Tracing.StopAsync(options);

Arguments

  • options TracingStopOptions? (optional)

    • Path string? (optional)#

      Export trace into the file with the given path.

Returns

StopChunkAsync​

Added in: v1.15 tracing.StopChunkAsync

Stop the trace chunk. See Tracing.StartChunkAsync() for more details about multiple trace chunks.

Usage

await Tracing.StopChunkAsync(options);

Arguments

  • options TracingStopChunkOptions? (optional)

Returns

StopHarAsync​

Added in: v1.60 tracing.StopHarAsync

Stop HAR recording and save the HAR file to the path given to Tracing.StartHarAsync().

Usage

await Tracing.StopHarAsync();

Returns