Tracing

用于收集和保存 Playwright 追踪信息的 API。在 Playwright 脚本运行后，追踪信息可以在 追踪查看器 中打开。

备注

你可能更希望 在配置文件中启用追踪，而不是使用 context.tracing。

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

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

Browser browser = chromium.launch();
BrowserContext context = browser.newContext();
context.tracing().start(new Tracing.StartOptions()
  .setScreenshots(true)
  .setSnapshots(true));
Page page = context.newPage();
page.navigate("https://playwright.dev");
context.tracing().stop(new Tracing.StopOptions()
  .setPath(Paths.get("trace.zip")));

---

方法

group

新增于：v1.49 tracing.group

警告

如果可用，请使用 test.step 替代。

在追踪信息中创建一个新组，将后续的任何 API 调用分配到该组，直到调用 Tracing.groupEnd()。组可以嵌套，并会在追踪查看器中显示。

用法

// group 和 groupEnd 之间的所有操作
// 会在追踪查看器中显示为一个组。
page.context().tracing().group("打开 Playwright.dev > API");
page.navigate("https://playwright.dev/");
page.getByRole(AriaRole.LINK, new Page.GetByRoleOptions().setName("API")).click();
page.context().tracing().groupEnd();

参数

• name String#

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

• options Tracing.GroupOptions（可选）

  • setLocation Location（可选）#

    • setFile String

    • setLine int（可选）

    • setColumn int（可选）

    指定跟踪查看器中显示的组的自定义位置。默认为 Tracing.group() 调用的位置。

返回值

• void#

---

groupEnd

新增于：v1.49 tracing.groupEnd

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

用法

Tracing.groupEnd();

返回值

• void#

---

start

新增于：v1.12 tracing.start

开始跟踪。

备注

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

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

用法

context.tracing().start(new Tracing.StartOptions()
  .setScreenshots(true)
  .setSnapshots(true));
Page page = context.newPage();
page.navigate("https://playwright.dev");
context.tracing().stop(new Tracing.StopOptions()
  .setPath(Paths.get("trace.zip")));

参数

• options Tracing.StartOptions（可选）

  • setName [字符串]（可选）#

    如果指定，中间跟踪文件将保存到 BrowserType.launch() 中指定的 setTracesDir 目录内，文件名前缀为给定名称。若要指定最终的跟踪压缩文件名，需改为将 path 选项传递给 Tracing.stop()。

  • setScreenshots [布尔值]（可选）#

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

  • setSnapshots [布尔值]（可选）#

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

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

  • setSources [布尔值]（可选） 新增于：v1.17#

    是否包含跟踪操作的源文件。应用程序源代码的目录列表必须通过 PLAYWRIGHT_JAVA_SRC 环境变量提供（在 Windows 上路径用 ';' 分隔，在其他平台上用 ':' 分隔）。

  • setTitle [字符串]（可选） 新增于：v1.17#

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

返回值

• void#

---

startChunk

新增于：v1.15 tracing.startChunk

开始一个新的追踪块。如果你想在同一个 BrowserContext 上记录多个追踪信息，可以先使用 Tracing.start() 一次，然后使用 Tracing.startChunk() 和 Tracing.stopChunk() 创建多个追踪块。

用法

context.tracing().start(new Tracing.StartOptions()
  .setScreenshots(true)
  .setSnapshots(true));
Page page = context.newPage();
page.navigate("https://playwright.dev");

context.tracing().startChunk();
page.getByText("Get Started").click();
// startChunk 和 stopChunk 之间的所有操作都将记录在追踪信息中。
context.tracing().stopChunk(new Tracing.StopChunkOptions()
  .setPath(Paths.get("trace1.zip")));

context.tracing().startChunk();
page.navigate("http://example.com");
// 保存包含不同操作的第二个追踪文件。
context.tracing().stopChunk(new Tracing.StopChunkOptions()
  .setPath(Paths.get("trace2.zip")));

参数

• options Tracing.StartChunkOptions（可选）

  • setName String（可选） 新增于：v1.32#

    如果指定了该参数，中间追踪文件将保存到 BrowserType.launch() 中指定的 setTracesDir 目录下，文件名前缀为给定的名称。若要指定最终的追踪压缩文件名，需改为向 Tracing.stopChunk() 传递 path 选项。

  • setTitle String（可选） 新增于：v1.17#

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

返回值

• void#

---

stop

新增于：v1.12 tracing.stop

停止追踪。

用法

Tracing.stop();
Tracing.stop(options);

参数

• options Tracing.StopOptions（可选）

  • setPath Path（可选）#

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

返回值

• void#

---

stopChunk

新增于：v1.15 tracing.stopChunk

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

用法

Tracing.stopChunk();
Tracing.stopChunk(options);

参数

• options Tracing.StopChunkOptions (可选)

  • setPath Path (可选)#

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

返回值

• void#