第 21 天：Trace Viewer 与失败排查

今日目标

熟练使用 Trace Viewer。
能从 action、snapshot、network、console 中定位失败。

学习时间安排（60–120 分钟）

时间	模块	做什么
0-20 分钟	核心概念与词汇	读概念表，重点理解 trace 的六块信息面板。
20-45 分钟	官方文档阅读	读 Trace Viewer 文档，了解打开方式和面板结构。
45-75 分钟	实操练习	故意制造失败测试，用 Trace 定位根因。
75-105 分钟	示例代码改写	用 trace 的 network/console 信息修复失败案例。
105-120 分钟	复盘与作业	完成失败案例分析记录，完成今日问题。

核心概念与词汇

English	中文	场景用法
Trace Viewer	轨迹查看器	用于说明该术语在 Playwright 测试中的使用场景。
trace.zip	轨迹文件	用于说明该术语在 Playwright 测试中的使用场景。
`on-first-retry`	首次重试时录制	用于说明该术语在 Playwright 测试中的使用场景。
actions	操作列表	用于说明该术语在 Playwright 测试中的使用场景。
snapshot	页面快照	用于说明该术语在 Playwright 测试中的使用场景。
network	网络面板	用于说明该术语在 Playwright 测试中的使用场景。
console	控制台面板	用于说明该术语在 Playwright 测试中的使用场景。
source	源码面板	用于说明该术语在 Playwright 测试中的使用场景。
attachments	附件	用于说明该术语在 Playwright 测试中的使用场景。
root cause	根因	用于说明该术语在 Playwright 测试中的使用场景。

学习材料

必读：[Trace Viewer](https://playwright.dev/docs/trace-viewer)
必读：[Trace Viewer - Actions](https://playwright.dev/docs/trace-viewer#actions) 部分
选读：[Videos](https://playwright.dev/docs/videos) 和 [Screenshots](https://playwright.dev/docs/screenshots)

重点理解

配置 trace：

use: {
  trace: 'on-first-retry',
}

运行：

npx playwright test --trace on
npx playwright show-trace trace.zip

Trace 中重点看：

Actions：每一步操作。
Before / After snapshot：操作前后页面状态。
Network：接口请求。
Console：前端错误。
Source：测试代码位置。
Attachments：截图、视频。

实操步骤

故意制造一个失败测试，例如 locator 文本写错，然后用 Trace Viewer 定位失败原因。

示例代码

# 先跑一次让 trace 生成
npx playwright test tests/failing.spec.ts --trace on

# 在 report 里点开 trace，或直接打开文件
npx playwright show-trace test-results/failing-*.zip

排查路径示范：

打开 Actions，找到红色失败的那一步。
看 Before snapshot：页面当时长什么样、元素在不在。
看 Network：目标接口返回了什么、状态码是多少。
看 Console：有没有 JS 报错。
回 Source：对应测试代码哪一行。
修复后重跑验证。

常见坑

失败只读报错文本，从不打开 trace，反复猜测原因。
trace 配置为 off，CI 失败后无任何证据可查。
把 trace.zip 当成长期产物堆在服务器上，磁盘爆炸。
只看 snapshot 不看 network，把接口问题当成 locator 问题。
测试里 console 有报错就认定是它导致的失败——前端 error 不一定影响当前断言。

今日产出

一个失败案例分析记录。
截图标注失败发生在哪一步。

今日问题

Trace Viewer 比截图多了哪些信息？
如何判断失败是 locator 问题还是页面问题？
Network 信息能帮助定位什么问题？
Console error 是否一定导致测试失败？
Trace 文件是否应该长期保存？

复盘要点

Trace 是 Playwright 相比其他框架最大的调试优势，不看 trace 等于白用 Playwright。
排查顺序：Actions 定位步骤 → snapshot 看页面 → network 看数据 → console 看报错。
建立“失败必看 trace”的习惯，定位效率能提升一个数量级。

AI 时代扩展：AI 辅助 Playwright 测试

新增概念

English	中文
failure analysis	失败分析
trace summarization	轨迹摘要
root cause classification	根因分类

适用场景

把失败日志和报错信息交给 AI 做初步分类（locator/等待/数据/环境），或者让 AI 根据 trace 导出的错误上下文给出排查路径。AI 读不到 trace 二进制，给它报错文本和截图描述更有效。

可复用表达 / 提示词

以下是测试失败日志：...。请判断失败类型（locator/等待/断言/数据/环境），并给出证据和排查步骤。
我打开 trace 看到：点击按钮前页面有目标元素，点击后 URL 没变。请分析最可能的 3 个原因。

追问加练

AI 判断“这是等待问题”，你需要 trace 里哪些信息来确认？
AI 的失败分类和你的经验不一致时，如何裁决？
哪些失败原因 AI 从报错文本里永远看不出来？

今日作业

完成失败案例分析记录：失败现象、trace 证据、根因、修复、验证。
把项目 trace 配置改为 on-first-retry。
用 AI 对另一次失败做分类，对比你的判断是否一致。

自检清单

我能独立用 trace 定位一个失败用例的根因。
我能说出 trace 六块面板各自的用途。
我的项目 CI 失败时保留 trace。
我知道 console error 和测试失败不是等价关系。
明天学习报告时，我能说清 trace 和报告的关系。