47. Trace 追踪深度使用

测试在 CI 上挂了，你不在现场，只有一行报错。这时候最管用的是 Trace（追踪）——它把测试跑的过程全程录下来，事后能一步步回放。

Trace 长什么样

Trace 是一份 zip 包，里面记录了每次操作的截图、DOM 快照、控制台日志、网络请求。你用 Trace Viewer（追踪查看器）打开它，就能「穿越」回测试现场。

本地怎么开

开发时，加个 --trace 开关就行：

npx playwright test --trace on

跑完先打开 HTML 报告，点测试条目里的 Trace 图标即可：

npx playwright show-report

也可以跳过报告，直接对着 zip 文件开：

npx playwright show-trace path/to/trace.zip

在线看 Trace

不想下载文件，可以上 trace.playwright.dev，把 zip 拖进去即可。它全程在你浏览器里跑，数据不外传。

你还能直接传远程地址，省去手动下载：

npx playwright show-trace https://example.com/trace.zip

在线版也支持这招：把地址塞进 ?trace= 参数里就行，比如 https://trace.playwright.dev/?trace=https://你的存储/trace.zip。注意对方服务器得允许跨域（CORS），否则加载不出来。

CI 上怎么配

CI 不该每个测试都录（太吃性能）。官方推荐：在第一次重试失败时录。

import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 1,
  use: {
    trace: 'on-first-retry',
  },
});

trace 的几个取值：

• 'on-first-retry'：第一次重试时录（推荐）。
• 'on-all-retries'：每次重试都录。
• 'retain-on-failure'：都录，通过就删。
• 'on'：每个都录（不建议，太重）。
• 'off'：关。

用库模式手动录

不走测试运行器，也能自己录。要点是：先开录，再操作，最后导出。

import { chromium } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext();

// 建页面之前就开录
await context.tracing.start({ screenshots: true, snapshots: true });

const page = await context.newPage();
await page.goto('https://playwright.dev');

// 停录并导出成 zip
await context.tracing.stop({ path: 'trace.zip' });
await browser.close();

这套用法属于库模式，第 53 章会专门讲。

Trace Viewer 里看什么

打开后，左侧是 Actions（操作）列表，每个操作点开有这些面板：

• Actions：用了哪个 Locator、花了多久。鼠标悬停能看操作前后的 DOM 变化。
• Screenshots：每一帧像电影胶片。双击某步能看它的时间范围。
• Snapshots：每次操作的完整 DOM 快照，分 Before（操作前）、Action（点击瞬间）、After（操作后）三种。
• Source：点操作就高亮对应代码行。
• Call：这次调用的细节，比如用的什么键、是否严格模式。
• Log：Playwright 背后干了啥，比如滚动、等待元素稳定。
• Errors：失败信息，时间线上用红线标出出错点。
• Console：浏览器和测试两头的控制台日志，图标区分来源。
• Network：所有网络请求，按类型、状态码、耗时排序；点开看请求头、响应体。
• Metadata：这次跑的环境信息，浏览器、视口尺寸、总耗时都在这。
• Attachments：附件。做视觉对比时，期望图、实际图、差异图都在这里，还能拖滑块叠着比。

我的排错习惯

CI 一挂，我先看 Trace 的 Errors 红线，再点进那一步看 Snapshots 和 Network。八成问题出在接口返回不对、或元素没按预期出现。比看视频省事，比看文字靠谱。

一句话：Trace 是 Playwright 排错的「黑匣子」，CI 上必开，本地调试更香。

小结

Trace 是 Playwright 排错的黑匣子，CI 上必开。它把 DOM 快照、网络请求、操作步骤全录下来，比视频信息全多了。我的习惯是先看 Errors 红线，再点进去看 Snapshots 和 Network，八成问题一眼就定位。别设成 on，on-first-retry 最划算。