Playwright 调试工具
本章介绍 Playwright 的三大调试工具：UI Mode、Trace Viewer 和命令行 Debug 模式。
UI Mode 完整介绍
UI Mode 是 Playwright 内置的图形化测试界面，提供探索、运行和调试测试的一站式体验。
启动 UI Mode
npx playwright test --ui
测试列表浏览
启动后，左侧边栏显示所有测试文件。
你可以展开每个文件和 describe 块，单独运行、查看、Watch 或调试每个测试。
Watch Mode
点击 Watch 按钮后，Playwright 会监听文件变化，一旦测试代码或源代码更新，自动重新运行受影响的测试。
时间轴视图（Timeline）
在测试执行后，顶部会显示时间轴视图，用不同颜色标记导航和操作。
你可以悬停查看每个步骤的快照，双击选中一个时间段，查看该时间段的详细日志。
DOM Snapshot
在时间轴中点击某个步骤，右侧会显示该时刻的 DOM 快照。
你可以看到页面在操作前后的实际状态，快速定位问题。
测试过滤
UI Mode 支持多种过滤方式：
- 按测试名称搜索
- 按
@tag
过滤 - 按项目（Project）过滤
- 按状态过滤：通过（passed）、失败（failed）、跳过（skipped）
Trace Viewer 深度调试
Trace Viewer 是 Playwright 的记录回放工具，能让你像调试录制一样检查测试的每一步。
配置 Trace 收集
实例
// 文件路径：playwright.config.ts
export default defineConfig({
use: {
// 只在失败重试时收集 Trace
trace: 'on-first-retry',
// 可选值：
// 'off' —— 不收集
// 'on' —— 每次都收集
// 'on-first-retry' —— 只在第一次重试时收集（推荐）
// 'retain-on-failure' —— 只在失败时保留 Trace
},
});
export default defineConfig({
use: {
// 只在失败重试时收集 Trace
trace: 'on-first-retry',
// 可选值：
// 'off' —— 不收集
// 'on' —— 每次都收集
// 'on-first-retry' —— 只在第一次重试时收集（推荐）
// 'retain-on-failure' —— 只在失败时保留 Trace
},
});
打开 Trace
# 本地打开 npx playwright show-trace path/to/trace.zip
也可以上传到 trace.playwright.dev 在线查看。
Trace 包含的信息
| 内容 | 说明 |
|---|---|
| DOM 快照 | 每一步执行前后的完整页面 DOM 快照 |
| 网络请求 | 所有 HTTP 请求和响应（URL、状态码、Header、Body） |
| 控制台日志 | 浏览器控制台输出的所有消息 |
| 截图 | 每一步的页面截图 |
| 操作记录 | 所有 Playwright 操作的调用参数和执行时间 |
| 源代码 | 每个操作对应的测试源码位置 |
使用 Trace 定位失败
在 Trace Viewer 的时间线中找到失败步骤，查看该步骤前后页面的 DOM 状态和网络请求，定位失败原因。
Trace 是最强大的调试工具。当测试在 CI 上失败但你无法本地重现时，下载 CI 生成的 Trace 文件可以离线分析失败原因。
--debug 模式与 page.pause()
--debug 命令行模式
npx playwright test --debug
功能：
- 自动打开 Playwright Inspector 窗口
- 逐个操作单步执行
- 在浏览器 DevTools 中调试
- 使用
F10
（Step Over）和F11
（Step Into）控制执行
page.pause() 暂停执行
实例
// 在代码中设置断点
test('调试用测试', async ({ page }) => {
await page.goto('https://www.runoob.com/');
// 暂停执行，打开 Inspector
await page.pause();
// 在 Inspector 中可以逐步执行后续操作
await page.getByText('RUNOOB 教程').click();
});
test('调试用测试', async ({ page }) => {
await page.goto('https://www.runoob.com/');
// 暂停执行，打开 Inspector
await page.pause();
// 在 Inspector 中可以逐步执行后续操作
await page.getByText('RUNOOB 教程').click();
});
使用 page.pause() 后运行测试，Playwright 会自动打开 Inspector 窗口，让你逐步骤检查页面状态。
三种调试方式的选择
| 方式 | 适用场景 |
|---|---|
| UI Mode | 日常开发，浏览测试列表，快速查看测试状态 |
| Trace Viewer | 定位 CI 失败、分析复杂测试的每一步 |
| --debug / page.pause() | 开发新测试，深入调试特定步骤 |