8. 调试利器 UI Mode 与 Trace Viewer

为什么需要专门调试工具

测试一失败，最怕「只给个红字，不知道当时页面长啥样」。Playwright 给了两把钥匙：一个在跑的时候看（UI Mode），一个在跑完之后看（Trace Viewer）。

UI Mode：带时间旅行的调试界面

打开方式就一行：

npx playwright test --ui

它会开一个界面，列出所有测试文件。你可以：点三角跑全部、跑单个文件、跑单个用例；还能按名称、@tag、项目、通过/失败状态来筛选。

时间线视图

每条测试顶部有一条彩色时间线，不同颜色代表导航、操作等类型。鼠标左右滑动，能看每个动作的画面快照。双击某个动作，还能看它的时间区间。

Actions 面板

这里列出每一步用了什么定位器、花了多久。悬停某个动作，右侧 DOM 快照会跟着变，你能直观看到「点之前」和「点之后」页面差在哪。

挑定位器

点 Pick locator 按钮，在 DOM 快照上悬停，每个元素下方会高亮它的定位器。你觉得满意了就复制，粘进测试。

源码联动

悬停某个动作，左侧源码面板会高亮对应的那行代码。点右上角「Open in VSCode」，直接跳到编辑器对应行。

Watch 模式

每条测试名旁边有个眼睛图标。点一下开启 watch 模式（监视模式，改动文件就自动重跑）。可以同时监视多条，也可以点顶部眼睛监视全部。

容器或 GitHub Codespaces 环境里，可把界面绑到 0.0.0.0 用浏览器访问：

npx playwright test --ui-host=0.0.0.0 --ui-port=8080

Trace Viewer：跑完之后回看

UI Mode 很爽，但 CI（持续集成）里没界面。这时候靠 Trace Viewer（追踪查看器，回放测试过程的工具）。

本地开发时直接开 trace：

npx playwright test --trace on

跑完用报告打开，点 trace 图标即可：

npx playwright show-report

在 CI 上留痕

CI 上不应每条都录（太重）。推荐配成「首次重试才录」：

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

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

trace 的全部可选值：

值	行为
off	不录（默认）
on	每次运行都录并保留，最重，不推荐常开
on-first-retry	只在第一次重试时录，CI 首选
on-all-retries	每次重试都录
retain-on-failure	每次都录，但只保留失败那次
retain-on-first-failure	只录首跑，且失败才保留
retain-on-failure-and-retries	每次都录，失败的和重试的都保留

打开 trace 文件

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

也能上传到浏览器里的 trace.playwright.dev，拖进去即可。它全程在本地解析，不上传数据。

还能直接给远程 trace 的 URL：

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

Trace Viewer 里看什么

和 UI Mode 类似，它也有 Actions、Snapshots、Source、Call、Log、Errors、Console、Network、Metadata、Attachments 这些面板。

最实用的是 Snapshots：每个动作会抓三张 DOM 快照——动作前、动作瞬间、动作后。动作瞬间那张还会高亮「点在了哪个节点、具体哪个坐标」，定位误点特别方便。

Network 面板能看每个动作期间的所有请求，Console 面板能看浏览器和测试各自打的日志。两者都能按动作筛选。

顺带一提：Inspector 与 —debug

命令行还有个轻量调试入口：

# 调试全部
npx playwright test --debug

# 调试某文件某行的单条用例
npx playwright test example.spec.ts:10 --debug

# 指定浏览器调试
npx playwright test --project=webkit --debug

--debug 会开 Playwright Inspector（检查器），浏览器以有头模式跑、超时设为 0。你能单步执行、实时改定位器、看 actionability 日志（可见性、稳定性、是否被遮挡等检查结果）。

更有极客味的是：

PWDEBUG=console npx playwright test

浏览器 DevTools 的控制台里会多一个 playwright 对象。playwright.$('css=button') 直接试选择器，playwright.selector($0) 反过来告诉你「当前选中的这个元素，Playwright 会怎么定位它」。

小结

UI Mode 适合本地边写边调，带时间旅行和 watch 模式。Trace Viewer 适合 CI 失败回看，用 trace 文件还原每一步的 DOM、控制台和网络。两者互补：一个在跑时看，一个在跑后看。

下一章起，我们进入定位器（Locator）的世界——这是 Playwright 最灵魂的部分。