Skip to main content

Tracing

用于收集和保存 Playwright 跟踪的 API。Playwright 脚本运行后，可以在 Trace Viewer 中打开 Playwright 跟踪。

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

note

你可能想在配置文件中启用跟踪，而不是使用 context.tracing。

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

context.tracing API 会捕获浏览器操作和网络活动，但不会记录测试断言（如 expect 调用）。我们建议 通过 Playwright Test 配置启用跟踪，这样可以包括这些断言，并为调试测试失败提供更完整的跟踪。

🌐 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.nodejs.cn");
await context.Tracing.StopAsync(new()
{
  Path = "trace.zip"
});

方法​

🌐 Methods

GroupAsync​

Added in: v1.49 tracing.GroupAsync
caution

在可用时，请改用 test.step。

🌐 Use test.step instead when available.

在追踪中创建一个新组，将随后的所有 API 调用分配给该组，直到调用 Tracing.GroupEndAsync()。组可以嵌套，并将在追踪查看器中可见。

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

用法

// 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.nodejs.cn/");
await Page.GetByRole(AriaRole.Link, new() { Name = "API" }).ClickAsync();
await Page.Context.Tracing.GroupEndAsync();

参数

  • name string#

    跟踪查看器中显示的组名称。

  • options TracingGroupOptions? (optional)

    • Location Location? (optional)#

      指定在跟踪查看器中显示该组的自定义位置。默认情况下为 Tracing.GroupAsync() 调用的位置。

返回

GroupEndAsync​

Added in: v1.49 tracing.GroupEndAsync

关闭由 Tracing.GroupAsync() 创建的最后一个组。

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

用法

await Tracing.GroupEndAsync();

返回

StartAsync​

Added in: v1.12 tracing.StartAsync

开始追踪。

🌐 Start tracing.

note

你可能想在配置文件中启用跟踪，而不是使用 Tracing.start。

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

context.tracing API 会捕获浏览器操作和网络活动，但不会记录测试断言（如 expect 调用）。我们建议 通过 Playwright Test 配置启用跟踪，这样可以包括这些断言，并为调试测试失败提供更完整的跟踪。

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

用法

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.nodejs.cn");
await context.Tracing.StopAsync(new()
{
  Path = "trace.zip"
});

参数

  • options TracingStartOptions? (optional)

    • Name string? (optional)#

      如果指定，中间跟踪文件将保存到位于 BrowserType.LaunchAsync() 指定的 TracesDir 目录中、具有给定名称前缀的文件中。要指定最终的跟踪压缩文件名，需要将 path 选项传递给 Tracing.StopAsync() 。

    • Screenshots bool? (optional)#

      是否在跟踪过程中捕获屏幕截图。屏幕截图用于构建时间线预览。

    • Snapshots bool? (optional)#

      如果此选项为 true，则跟踪将

      • 捕获每个动作的 DOM 快照
      • 记录网络活动

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

      是否包含跟踪操作的源文件。

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

      要在跟踪查看器中显示的跟踪名称。

返回

StartChunkAsync​

Added in: v1.15 tracing.StartChunkAsync

开始一个新的跟踪片段。如果你想在同一个 BrowserContext 上记录多个跟踪，请先调用一次 Tracing.StartAsync()，然后使用 Tracing.StartChunkAsync() 和 Tracing.StopChunkAsync() 创建多个跟踪片段。

🌐 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().

用法

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.nodejs.cn");

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"
});

参数

  • options TracingStartChunkOptions? (optional)

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

      如果指定，中间跟踪文件将会保存到 BrowserType.LaunchAsync() 指定的 TracesDir 目录中，并使用给定的名称前缀。要指定最终的跟踪压缩文件名称，需要将 path 选项传递给 Tracing.StopChunkAsync()。

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

      要在跟踪查看器中显示的跟踪名称。

返回

StopAsync​

Added in: v1.12 tracing.StopAsync

停止追踪。

🌐 Stop tracing.

用法

await Tracing.StopAsync(options);

参数

  • options TracingStopOptions? (optional)

    • Path string? (optional)#

      将跟踪导出到具有给定路径的文件中。

返回

StopChunkAsync​

Added in: v1.15 tracing.StopChunkAsync

停止跟踪块。有关多个跟踪块的更多详细信息，请参见 Tracing.StartChunkAsync()。

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

用法

await Tracing.StopChunkAsync(options);

参数

  • options TracingStopChunkOptions? (optional)

返回