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.

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.nodejs.cn");
context.tracing().stop(new Tracing.StopOptions()
  .setPath(Paths.get("trace.zip")));

方法​

🌐 Methods

group​

Added in: v1.49 tracing.group
caution

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

🌐 Use test.step instead when available.

在跟踪中创建一个新组，将随后的任何 API 调用分配到此组，直到调用 Tracing.groupEnd() 为止。组可以嵌套，并且将在跟踪查看器中可见。

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

用法

// All actions between group and groupEnd
// will be shown in the trace viewer as a group.
page.context().tracing().group("Open Playwright.dev > API");
page.navigate("https://playwright.nodejs.cn/");
page.getByRole(AriaRole.LINK, new Page.GetByRoleOptions().setName("API")).click();
page.context().tracing().groupEnd();

参数

  • name String#

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

  • options Tracing.GroupOptions (optional)

    • setLocation Location (optional)#

      • setFile String

      • setLine int (optional)

      • setColumn int (optional)

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

返回

  • [Disposable]#

groupEnd​

Added in: v1.49 tracing.groupEnd

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

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

用法

Tracing.groupEnd();

返回

start​

Added in: v1.12 tracing.start

开始追踪。

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

用法

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

参数

  • options Tracing.StartOptions (optional)

    • setLive boolean (optional) Added in: v1.59#

      启用后，跟踪将写入一个未归档的文件，该文件会在操作发生时实时更新，而不是将更改缓存后在结束时归档到 zip 文件中。这对于在测试执行期间进行实时跟踪查看非常有用。

    • setName String (optional)#

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

    • setScreenshots boolean (optional)#

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

    • setSnapshots boolean (optional)#

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

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

    • setSources boolean (optional) Added in: v1.17#

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

    • setTitle String (optional) Added in: v1.17#

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

返回

startChunk​

Added in: v1.15 tracing.startChunk

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

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

用法

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

context.tracing().startChunk();
page.getByText("Get Started").click();
// Everything between startChunk and stopChunk will be recorded in the trace.
context.tracing().stopChunk(new Tracing.StopChunkOptions()
  .setPath(Paths.get("trace1.zip")));

context.tracing().startChunk();
page.navigate("http://example.com");
// Save a second trace file with different actions.
context.tracing().stopChunk(new Tracing.StopChunkOptions()
  .setPath(Paths.get("trace2.zip")));

参数

  • options Tracing.StartChunkOptions (optional)

    • setName String (optional) Added in: v1.32#

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

    • setTitle String (optional) Added in: v1.17#

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

返回

startHar​

Added in: v1.60 tracing.startHar

在此上下文中开始记录网络活动的 HAR（HTTP 存档）。当调用 Tracing.stopHar() 或当返回的 [Disposable] 被释放时，HAR 文件会写入磁盘。

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

每个 BrowserContext 同时只能有一个 HAR 录制处于活动状态。

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

用法

context.tracing().startHar(Paths.get("trace.har"));
Page page = context.newPage();
page.navigate("https://playwright.nodejs.cn");
context.tracing().stopHar();

参数

  • path Path#

    在文件系统上写入 HAR 文件的路径。如果文件名以 .zip 结尾，HAR 将以 zip 压缩档的形式保存，响应正文作为单独的文件附加。

  • options Tracing.StartHarOptions (optional)

    • setContent enum HarContentPolicy { OMIT, EMBED, ATTACH } (optional)#

      可选设置，用于控制资源内容管理。如果指定 omit，内容不会被保存。如果指定 attach，资源将作为单独的文件或 ZIP 压缩包中的条目保存。如果指定 embed，内容将根据 HAR 规范内联存储在 HAR 文件中。默认情况下，对于 .zip 输出文件为 attach，对于所有其他文件扩展名为 embed。

    • setMode enum HarMode { FULL, MINIMAL } (optional)#

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

    • setUrlFilter String | Pattern (optional)#

      用于筛选存储在 HAR 中的请求的全局通配符或正则表达式模式。默认为无。

返回

  • [Disposable]#

stop​

Added in: v1.12 tracing.stop

停止追踪。

🌐 Stop tracing.

用法

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

参数

  • options Tracing.StopOptions (optional)

    • setPath Path (optional)#

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

返回

stopChunk​

Added in: v1.15 tracing.stopChunk

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

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

用法

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

参数

  • options Tracing.StopChunkOptions (optional)

返回

stopHar​

Added in: v1.60 tracing.stopHar

停止 HAR 记录并将 HAR 文件保存到 Tracing.startHar() 提供的路径。

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

用法

Tracing.stopHar();

返回