Archon 中的 Playwright CLI Tracing 实战指南：捕获 DOM、网络与控制台的完整执行轨迹

Archon 中的 Playwright CLI Tracing 实战指南：捕获 DOM、网络与控制台的完整执行轨迹

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon

导读

本文围绕 Archon 仓库中.claude/skills/playwright-cli技能包的 Tracing（执行轨迹追踪）能力展开，系统讲解如何通过playwright-cli tracing-start/tracing-stop录制浏览器自动化全过程的执行轨迹。轨迹文件中包含每次操作的 DOM 快照、分步截图、完整网络活动与控制台日志，是排查点击失败、定位慢资源、留存自动化证据的核心工具。读完本文，你将掌握 trace 输出文件的组织方式与解析方法、三种典型使用场景（调试、性能分析、证据捕获），以及 trace 与视频、截图的选型对比和磁盘清理等最佳实践。

一、Tracing 是什么：执行轨迹的"黑匣子"

在 Archon 的 playwright-cli 技能包 中，Tracing 是一对配套命令：

• playwright-cli tracing-start：开始录制执行轨迹；
• playwright-cli tracing-stop：停止录制并落盘。

启动录制后，浏览器自动化过程中的每一次动作都会被记录，形成一份"可回放"的详细轨迹。与单纯的截图或录屏不同，trace 捕获的是结构化数据：DOM 快照、网络请求/响应、控制台消息和精确计时信息。这意味着当某个点击动作失败时，你可以回看点击发生那一刻页面的真实 DOM 状态，而不是只能对着静态图片猜测。

从技能包的 DevTools 命令列表可以看到，tracing 与console（查看控制台）、requests（查看网络请求）、video-start/video-stop（录屏）同属调试工具家族，但 trace 是其中信息密度最高、最适合深入分析的一项。

二、基本用法：三行命令开启一次完整录制

trace 的用法非常轻量，核心就三步：开始录制 → 执行操作 → 停止录制。

# 1. 开始轨迹录制 playwright-cli tracing-start # 2. 正常执行页面操作 playwright-cli open https://example.com playwright-cli click e1 playwright-cli fill e2 "test" # 3. 停止轨迹录制 playwright-cli tracing-stop

关键原则：tracing 录制的是"过程"，而非"结果"。因此应把tracing-start放在整个操作序列的最前面（甚至可以在open之前），把tracing-stop放在最后，确保从导航到交互的每一个环节都被完整记录。停止录制后，trace 会立即写入磁盘，供后续在 Trace Viewer 等工具中查看分析。

三、Trace 输出文件：traces/目录里有什么

启动录制后，Playwright 会在本地创建traces/目录，其中包含三类文件，各司其职：

1.trace-{timestamp}.trace—— 动作日志（主文件）

这是 trace 的核心文件，记录从录制开始到结束的全部动作信息：

• 执行的每一个动作（点击、填表、导航等）及顺序；
• 每个动作前后的 DOM 快照（用于对比操作前后的页面状态变化）；
• 每个步骤对应的页面截图（可视化还原操作现场）；
• 每个操作的计时信息（耗时分布）；
• 页面产生的控制台消息；
• 源码位置（动作对应的定位器/选择器来源）。

正因为"动作前后 DOM 快照"的存在，当某个点击没有产生预期效果时，可以精确比对快照差异来定位原因——这正是 trace 优于录屏的核心价值。

2.trace-{timestamp}.network—— 网络日志

完整记录录制窗口内的网络活动：

• 所有 HTTP 请求与响应；
• 请求头与请求体、响应头与响应体；
• 各阶段计时：DNS 解析、TCP 连接、TLS 握手、TTFB（首字节时间）、下载耗时；
• 资源大小（响应体积、传输体积）；
• 失败请求与错误信息。

这份网络日志是性能分析的直接数据源，可以据此绘制瀑布图（network waterfall），定位是哪个资源拖慢了页面加载。

3.resources/—— 资源目录

录制过程中缓存的静态资源：

• 图片、字体、样式表、脚本；
• 用于回放的响应体；
• 重建页面状态所需的资源。

resources 目录让 trace 具备"离线回放"能力——即使目标站点已不可访问，也能基于缓存的资源重建当时的页面状态。

四、Trace 捕获内容一览

其中"动作前后 DOM 快照"与"分步截图"组合，使 trace 可以逐帧还原用户操作路径；"控制台消息"则能直接捕捉页面运行时的 JS 报错与警告，无需额外打开 DevTools。

五、实战使用场景

场景一：调试失败的动作

自动化中最常见的困惑是"点击没生效"。trace 能回答"点击发生时页面到底是什么状态"：

playwright-cli tracing-start playwright-cli open https://app.example.com # 这个点击失败了——为什么？ playwright-cli click e5 playwright-cli tracing-stop # 打开 trace，查看点击尝试时刻的 DOM 状态

回看 trace 中的 DOM 快照，通常能立刻发现：元素被遮罩层遮挡、按钮处于 disabled 状态、页面尚未加载完成、元素被动态替换等根因。也可以配合 playwright-tests.md 中npx playwright test --debug=cli的方式，把 trace 录制与测试调试串起来使用。

场景二：分析性能

playwright-cli tracing-start playwright-cli open https://slow-site.com playwright-cli tracing-stop # 查看网络瀑布图，识别慢资源

打开.network日志后，按 DNS/连接/TLS/TTFB/下载各阶段耗时分段排查：TTFB 过长指向服务端响应慢，下载阶段过长指向资源体积大或带宽受限。配合 skill 包中的--raw全局选项（如playwright-cli --raw eval "JSON.stringify(performance.timing)"），还能用页面性能计时 API 与 trace 网络数据交叉验证。

场景三：捕获证据

trace 可以完整记录一条用户流程，作为文档、演示或回归验证的证据：

# 录制完整的结账流程 playwright-cli tracing-start playwright-cli open https://app.example.com/checkout playwright-cli fill e1 "4111111111111111" playwright-cli fill e2 "12/25" playwright-cli fill e3 "123" playwright-cli click e4 playwright-cli tracing-stop # trace 中记录了事件的精确执行顺序

这份 trace 既能作为功能验收的"留痕"，也能在后续回归时与新的 trace 做动作序列比对。

六、Trace vs Video vs Screenshot：如何选型

选型建议：排查问题时优先 trace（信息最全、可逐步回放）；面向用户或演示产出时选 video（可读性最好）；只需要"看一眼"当前状态时用 screenshot（开销最小）。技能包中 video-recording.md 也给出了同样的结论：trace 面向"调试与分析"，video 面向"演示与文档"。注意 trace 与录屏可以同时开启，二者互补不冲突——需要对外演示又担心出问题时，先录 trace 再转录视频是稳妥的组合。

七、最佳实践

1. 在问题发生前就开始录制

trace 的价值在于"全过程"，而不是"失败的那一步"：

# 录制完整流程，而非仅录制失败步骤 playwright-cli tracing-start playwright-cli open https://example.com # ... 导致问题的所有前置步骤 ... playwright-cli tracing-stop

只录制失败步骤的 trace 往往缺少前置上下文（例如某个状态变更、某次网络请求），难以定位根因。

2. 及时清理旧 trace

trace 会持续占用磁盘空间，应纳入定期清理：

# 删除 7 天前的 trace find .playwright-cli/traces -mtime +7 -delete

建议把这条命令挂入 cron 或 CI 的收尾步骤；录制频率高或页面体积大的场景，可将清理周期缩短到 1~3 天。类似的清理思路也适用于 session-management.md 中提到的delete-data命令——定期清理旧会话数据与旧 trace，能避免自动化环境长期运行后磁盘被撑满。

3. 善用命名会话与状态管理

虽然 trace 录制本身不区分会话，但配合-s=session命名会话（见 session-management.md）可以在多浏览器并行录制时避免 trace 相互混淆；配合state-save/state-load（见 storage-state.md）可以在已登录状态下录制，让 trace 覆盖更真实的业务场景。

八、限制与注意事项

• 性能开销：trace 录制会给自动化过程增加额外开销，录制期间页面操作可能略慢；
• 磁盘占用：大型 trace（尤其是包含丰富网络与资源缓存的录制）会显著占用磁盘空间，务必定期清理；
• 回放保真度：部分动态内容（实时推送、流式渲染、依赖外部 API 的页面区域）在回放时可能无法完美还原，此时应结合.network日志中的原始响应体与resources/目录核对。

结语

Tracing 是 playwright-cli 技能包中信息密度最高的调试工具：一份 trace 同时承载 DOM 快照、分步截图、完整网络活动与控制台日志，既能回答"哪里错了"，也能回答"为什么慢"，还能作为自动化过程的权威证据留存。在 Archon 的自动化与验证工作流中，将tracing-start/tracing-stop嵌入关键流程，配合 video-recording.md、request-mocking.md 等参考文档按需取用，即可构建一套完整的"录制 — 回放 — 分析 — 复盘"调试闭环。

【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon