Playwright Trace Viewer 上手：一个 trace 文件怎么看出用例挂在哪一步

一行 timeout 是查不出东西的

流水线红了，点进日志，只有一句超时和一个定位器字符串。你在本地把同一条用例跑十遍，十遍都过。这时候能救命的不是加日志，而是让那一次失败的运行本身留下可回放的记录——这就是 trace 要解决的事。

Playwright 仓库 docs/src/trace-viewer.md 开篇写明，Trace Viewer 是一个 GUI 工具，用来在脚本跑完之后浏览已录制的 trace；同一句里点名了它的典型用途是排查 CI 上失败的用例。换句话说，trace 不是「实时调试器」，是事后回放：它把那一次运行里每个动作、动作前后的 DOM 快照、网络请求、控制台输出打成一个 trace.zip，你事后再拆开看。

前置条件：先看清你用的是哪套绑定

这一步最容易踩坑，因为四种语言绑定的开启方式不是一回事。docs/src/trace-viewer.md 里「Recording a trace」这一节被 langs 标记拆成了四段，各写各的：

• JavaScript / TypeScript：既可以在配置文件里用 TestOptions.trace（docs/src/test-api/class-testoptions.md 里标明该属性自 v1.10 起可用），也可以用命令行开关；不使用 Test Runner 时走 BrowserContext.tracing API。
• Python：文档写的是通过 pytest 插件的 --tracing 开关；不用 pytest 时，改用 context.tracing.start(...) / context.tracing.stop(...)，同步与异步两套写法在文档里是分开给的。
• Java：文档只给了 BrowserContext.tracing 这一条路径，用 Tracing.StartOptions 组装参数。
• C#：文档给的是各测试框架的 SetUp/TearDown 里调 Context.Tracing.StartAsync 与 StopAsync。

另有一处 Windows 用户要留意：docs/src/api/class-tracing.md 里 sources 这个选项（自 v1.17 起可用）在 Java 绑定下有额外要求——源码目录列表必须通过 PLAYWRIGHT_JAVA_SRC 环境变量提供，且文档明写「Windows 上用 ; 分隔，其它平台用 :」。写 Java 的同学在 Windows 上按 Linux 习惯用冒号，Source 面板就是空的。

开启 trace：三个取值，先分清「录」和「留」

docs/src/trace-viewer.md 在 JS 那一段列出了几个可用取值，实际工程里最常落地的是这三个：

其一，本地临时强开。

npx playwright test --trace on

其二，CI 上的常规配置。 文档明确建议在 CI 上只对失败用例的第一次重试录制：

import { defineConfig } from '@playwright/test';
export default defineConfig({
  retries: 1,
  use: {
    trace: 'on-first-retry',
  },
});

其三，不开重试但想要失败现场。 文档原话是：如果你没有启用 retries，但仍然想拿到失败用例的 trace，可以用 trace: 'retain-on-failure'。

上面这些是仓库文档里给出的示例配置，直接抄即可，不要自己改成相近的写法。理解这几个取值的关键，在 docs/src/test-use-options-js.md 的「Trace modes」一节里说得最清楚：每个模式其实是两个维度的组合——在哪些运行上录制，以及录完之后在什么条件下保留。'on' 是每次运行都录、且一律保留；'retain-on-failure' 是每次都录、但只留下失败那次；'on-first-retry' 是只在第一次重试时录、录了就留。想清楚这两维，你就不必背取值表了。该节还有一张按「首次通过 / 首次失败后重试通过 / 每次都失败」三种场景列出保留结果的对照表，需要时回仓库查那一张即可。

顺带一提 'on'：docs/src/trace-viewer.md 在列这个取值时自己加了括注，说不推荐，因为它开销大。这是仓库文档的自述，照实转达。

想更细地控制录什么，trace 还可以传对象而不是字符串。docs/src/test-api/class-testoptions.md 里列出的字段包括 mode、attachments、screenshots、snapshots、sources；其中 snapshots 在 JS 绑定下可以是对象，含 dom、aria、screen 三个子开关，文档写明传 true 等价于 { dom: true }。screenshots、snapshots、sources 在文档里都标注默认为 true——这是仓库当前文档里的默认值，随版本可能变动。要注意 docs/src/api/class-tracing.md 里同一个 snapshots 选项被写了两遍：标 langs: js 的那一份是对象形式，标 langs: java, python, csharp 的那一份只是布尔值。写非 JS 绑定时别照着 JS 的对象写法抄。

这里还有一处文档内部的出入值得记一笔：class-testoptions.md 中 trace 的类型行里，顶层 TraceMode 联合类型没有列出 'on-all-retries'，而紧接着的 mode 字段和下方的取值说明里都有它。两处白纸黑字放在一起就是不一致，具体以你所用版本的类型定义为准。

至于不走 Test Runner 的库用法，class-tracing.md 在 Tracing.start 下有一条 note 直接劝退：context.tracing 只捕获浏览器操作与网络活动，不会记录测试断言（例如 expect 调用），因此推荐通过 Playwright Test 的配置开启 tracing，那样得到的 trace 更完整。这条是排查断言失败时最容易被忽略的差别。

打开 trace 的两种方式

方式一，本地 CLI。 文档提醒要写清 trace.zip 的完整路径：

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

Python 绑定用 playwright show-trace trace.zip；C# 绑定文档给的是 pwsh bin/Debug/netX/playwright.ps1 show-trace trace.zip——注意它走的是 PowerShell 脚本，Windows 上就是 pwsh 这条路径，别拿 npx 那条套。docs/src/test-cli-js.md 的 Trace Viewer 小节还写明：不带任何参数直接 npx playwright show-trace 也能开，界面里再加载 trace；参数也可以是一个目录（npx playwright show-trace trace/）。该节的选项表列了 -b, --browser、-h, --host、-p, --port，其中 browser 默认 chromium——这是仓库当前文档里的默认值，随版本可能变动。

如果你用的是 HTML 报告，docs/src/trace-viewer-intro-js.md 给的是另一个入口：先 npx playwright show-report，在报告里点用例文件名旁边的 trace 图标直接打开，或者进入用例详情页滚到 Traces 那一栏点开快照。

方式二，浏览器里的托管版。 trace.playwright.dev 是 Trace Viewer 的静态托管版本，支持拖拽上传或用 Select file 按钮选文件。文档写明：它在你的浏览器里完整加载 trace，不向外传输任何数据。远程 trace 还可以直接用 URL 打开——CLI 侧 npx playwright show-trace https://example.com/trace.zip 可以，托管版则把 trace 地址作为查询参数传进去，形如 https://trace.playwright.dev/?trace=<你的 trace 地址>；文档同时提示这种用法可能受 CORS 规则限制。

以上命令按仓库文档中的参数语义组合，未经实测，以仓库最新内容与 --help 的实际输出为准。

界面各栏分别对着 trace 里的什么

打开之后不要乱点，按区域理解会快很多。界面的构成可以在 packages/trace-viewer/src/ui/workbench.tsx 里直接读到。

最上面是时间轴。 workbench.tsx 里它由 Timeline 组件渲染，接收 boundaries、selectedTime、highlightedTime 这些参数。开着 screenshots 时，trace 会录一段录屏并渲染成胶片条（对应 filmStrip.tsx），鼠标划过能看到放大的画面。文档写明两个交互：双击某个动作可以看到该动作的时间区间；在时间轴上按下起点拖到终点可以框选一段时间，框选之后 Actions、Console、Network 都会跟着只显示这段时间内的记录，点 Show all 恢复。用例失败时，时间轴上还会有一条红线标出错误发生的位置。

左侧是导航区，只有两栏。 workbench.tsx 里定义为 actionsTab（id actions）与 metadataTab（id metadata）。Actions 栏按顺序列出这次运行的每个动作，栏内还有一个 aria-label 为 Filter actions 的搜索框可以过滤；文档说选中一个动作会同时给出动作快照、动作日志和源码位置。Metadata 栏给的是这次运行的环境信息，文档举的例子是浏览器、视口尺寸、用例耗时等。

右侧是属性区，是一组标签页。 workbench.tsx 里 tabs 数组的顺序是 inspector（标题 Locator）、call、log、errors、console、network、source、attachments，另有 annotations 一栏仅在 annotations !== undefined 时才被 push 进去。这个顺序不是死的：源码里紧接着还有一段判断，showSourcesFirst 为真时会把 sourceTab 从原位置移走、插到第二位——所以你看到的标签页排列和上面这一串对不上，未必是版本差异。逐个对应关系是：Call 显示这个动作的调用信息，文档举例包括耗时、用了哪个定位器、是否处于严格模式、按了什么键；Log 是 Playwright 内部的过程日志，滚动进视图、等待元素可见/可用/稳定这些步骤都在这里；Errors 汇总错误信息，点进去能跳到源码对应行；Console 同时收浏览器和测试文件两侧的输出，用不同图标区分来源；Network 列出全部请求，可按类型、状态码、方法、内容类型、耗时、大小排序，点开单条能看请求头、响应头、请求体和响应体；Source 在你选中动作时高亮对应的那行代码；Attachments 这一栏在文档里标了 langs: js，做视觉回归时用来比对期望图与实际图。

值得一提的是，源码里排在第一位、标题为 Locator 的 inspectorTab，在 docs/src/trace-viewer.md 的「Trace Viewer features」一节里没有对应小节。两处放在一起就是这个差异，实际以你所用版本的界面为准。

动作快照有三态。 docs/src/trace-viewer.md 用一张表说明了按动作类型捕获的快照：Before 是动作被调用时刻的快照，Action 是实际输入发生那一刻的快照（文档说这一态在你想确认 Playwright 究竟点在哪里时特别有用），After 是动作之后的快照。定位器点歪了、点到了遮挡层上，看 Action 这一态最直接——文档提到该视图会同时高亮 DOM 节点与精确的点击位置。

边界与几件要先知道的事

• 'on' 取值文档自己标了不推荐、开销大，别在全量流水线上长期开着。
• Attachments 栏在文档里标注 langs: js，非 JS 绑定不要指望这一栏。
• snapshots 的对象形式（dom / aria / screen）只在 JS 绑定下存在。
• Tracing.start 的 live 选项标注自 v1.59 起可用，文档说明它把 trace 写成实时更新的非归档文件，供执行过程中实时查看，与常规的「跑完打成 zip」是两条路。
• 托管版走 URL 加载远程 trace 时可能撞上 CORS，文档已经提醒。
• trace 的 Network 面板会存下请求头、响应头与请求体、响应体。把 trace 文件发到工单或群里之前，先想清楚里面可能带着会话凭据这类内容——这一条是通用做法，不是该项目的官方说明。

怎么确认自己配对了

第一步看文件。docs/src/test-use-options-js.md 写明 trace 文件、截图和视频会出现在测试输出目录，通常是 test-results；Python 侧文档也说 --tracing 会把 trace 放到 test-results 目录下名为 trace.zip 的文件里。跑一次预期会失败的用例，去这个目录看有没有产物——没有产物就说明模式没生效，回头核对是不是配了 'on-first-retry' 却没开 retries。

第二步看内容。用 npx playwright show-trace <你的 trace 路径> 打开，确认三件事：Actions 栏能按顺序看到你写的动作；选中某个动作后 Source 栏能高亮到你的源码行（高亮不了通常是 sources 没开，Java 侧则先查 PLAYWRIGHT_JAVA_SRC）；Metadata 栏能读到浏览器与视口信息。这三项都在，说明 trace 录全了，接下来才谈得上定位那一步到底挂在哪里。

该项目持续更新，以上涉及的命令、配置项、字段名与默认值随版本变动，以仓库最新内容为准。

---

本文依据 github.com/microsoft/playwright 仓库于 2026-08-18 的公开内容整理， 事实来自仓库内的文档与源码。我们没有对文中涉及的功能做过实测， 因此不涉及运行速度、稳定性与实际表现的任何描述。 该项目迭代频繁，文中涉及的 API 签名、配置项与默认值随版本变动，请以仓库最新内容为准。 本文不涉及浏览器版本矩阵与版本清单，相关信息请以官方发布说明为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。