Tracing

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

注意

建议您在配置文件中 启用追踪，而不是直接使用 context.tracing。

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

在执行操作之前开始记录追踪。最后，停止追踪并将其保存到文件中。

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

---

方法

GroupAsync

新增于: v1.49 tracing.GroupAsync

注意

如果可用，请改用test.step。

在追踪中创建一个新组，并将随后的所有 API 调用分配给该组，直到调用 Tracing.GroupEndAsync()。组可以嵌套，并将在 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.net.cn/");
await Page.GetByRole(AriaRole.Link, new() { Name = "API" }).ClickAsync();
await Page.Context.Tracing.GroupEndAsync();

参数

• name string#

  在追踪查看器中显示的组名。

• options TracingGroupOptions? (可选)

  • Location Location? (可选)#

    • File string

    • Line int? (可选)

    • Column int? (可选)

    指定在 trace viewer 中显示该组的自定义位置。默认为 Tracing.GroupAsync() 调用所在的位置。

返回

• [Disposable]#

---

GroupEndAsync

新增于: v1.49 tracing.GroupEndAsync

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

用法

await Tracing.GroupEndAsync();

返回

• void#

---

StartAsync

添加于：v1.12 tracing.StartAsync

开始追踪。

注意

建议您在配置文件中 启用追踪，而不是直接使用 Tracing.start。

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

用法

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

参数

• options TracingStartOptions? (可选)

  • Live bool? (可选)新增于: v1.59#

    启用后，追踪信息将写入一个未压缩的文件中，该文件会随操作实时更新，而不是在最后将更改缓存并归档为 zip 文件。这对于在测试执行期间进行实时追踪查看非常有用。

  • Name string? (可选)#

    如果指定，中间追踪文件将保存到 TracesDir 目录（由 BrowserType.LaunchAsync() 指定）中，并以给定名称作为前缀。若要指定最终的追踪 zip 文件名，需要改为将 path 选项传递给 Tracing.StopAsync()。

  • Screenshots bool? (可选)#

    是否在追踪期间捕获屏幕截图。屏幕截图用于构建时间线预览。

  • Snapshots bool? (可选)#

    如果此选项为 true，追踪将

    • 在每次操作时捕获 DOM 快照
    • 记录网络活动

  • Sources bool? (可选)新增于: v1.17#

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

  • Title string? (可选)新增于: v1.17#

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

返回

• void#

---

StartChunkAsync

新增于: v1.15 tracing.StartChunkAsync

开始一个新的追踪分块（chunk）。如果您想在同一个 BrowserContext 上记录多个追踪，请使用一次 Tracing.StartAsync()，然后通过 Tracing.StartChunkAsync() 和 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.net.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? (可选)

  • Name string? (可选)新增于: v1.32#

    如果指定，中间追踪文件将保存到 TracesDir 目录（由 BrowserType.LaunchAsync() 指定）中，并以给定名称作为前缀。若要指定最终的追踪 zip 文件名，需要改为将 path 选项传递给 Tracing.StopChunkAsync()。

  • Title string? (可选)新增于: v1.17#

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

返回

• void#

---

StartHarAsync

添加于: v1.60 tracing.StartHarAsync

在此上下文中开始记录网络活动的 HAR（HTTP Archive）。当调用 Tracing.StopHarAsync() 或销毁返回的 [Disposable] 对象时，HAR 文件将被写入磁盘。

每个 BrowserContext 一次只能激活一个 HAR 记录。

用法

await context.Tracing.StartHarAsync("trace.har");
var page = await context.NewPageAsync();
await page.GotoAsync("https://playwright.net.cn");
await context.Tracing.StopHarAsync();

参数

• path string#

  写入 HAR 文件的文件系统路径。如果文件名以 .zip 结尾，HAR 将被保存为 zip 压缩包，响应体将作为独立文件包含在其中。

• options TracingStartHarOptions? (可选)

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

    可选设置，用于控制资源内容管理。如果指定 omit，则不保留内容。如果指定 attach，则资源将作为单独的文件或 ZIP 存档中的条目进行持久化。如果指定 embed，则内容将内联存储在 HAR 文件中，符合 HAR 规范。对于 .zip 输出文件，默认为 attach；对于所有其他文件扩展名，默认为 embed。

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

    设置为 minimal 时，仅记录从 HAR 路由所需的信息。这会省略 HAR 的大小、时间、页面、Cookie、安全性和其他类型的 HAR 信息，这些信息在从 HAR 重放时不使用。默认为 full。

  • UrlFilter|UrlFilterRegex string? | Regex? (可选)#

    用于过滤存储在 HAR 中的请求的 glob 或正则表达式模式。默认为不过滤。

返回

• [Disposable]#

---

StopAsync

添加于：v1.12 tracing.StopAsync

停止追踪。

用法

await Tracing.StopAsync(options);

参数

• options TracingStopOptions? (可选)

  • Path string? (可选)#

    将追踪导出到给定路径的文件中。

返回

• void#

---

StopChunkAsync

新增于: v1.15 tracing.StopChunkAsync

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

用法

await Tracing.StopChunkAsync(options);

参数

• options TracingStopChunkOptions? (可选)

  • Path string? (可选)#

    将自上次调用 Tracing.StartChunkAsync() 以来收集的追踪导出到指定路径的文件中。

返回

• void#

---

StopHarAsync

添加于: v1.60 tracing.StopHarAsync

停止 HAR 记录并将 HAR 文件保存到 Tracing.StartHarAsync() 给定的路径中。

用法

await Tracing.StopHarAsync();

返回

• void#