skillhub-147-playwright-skill/core/debugging.md

调试 Playwright 测试

使用场景：测试失败，你需要理解原因——选择器错误、时序问题、网络故障或意外的应用程序状态。

快速参考

工具	命令	最适合的场景
UI 模式	npx playwright test --ui	交互式探索、可视化时间线、重新运行测试
Playwright Inspector	PWDEBUG=1 npx playwright test	逐步调试、选择器试验场
Trace Viewer（追踪查看器）	npx playwright show-trace trace.zip	CI 失败的事后分析
有头模式	npx playwright test --headed	在测试执行期间观察浏览器
慢速模式	npx playwright test --headed --slow-mo=500	可视地跟踪快速交互
page.pause()	插入测试代码中	在精确位置暂停以检查状态
详细 API 日志	DEBUG=pw:api npx playwright test	查看每个 Playwright API 调用及其耗时
VS Code 扩展	Playwright Test for VS Code	断点、逐步执行、拾取定位器

系统化调试工作流

按此顺序执行。不要直接跳到第 5 步——大多数问题在第 2 步即可解决。

1. 阅读完整的错误信息
   └─ 查阅 troubleshooting/error-index.md 了解已知模式
2. 使用 --ui 运行以直观查看发生了什么
   └─ 时间线显示每个操作，失败点附有截图
3. 如果尚未开启追踪，先启用
   └─ 在配置中临时使用 use: { trace: 'on' }
4. 在追踪的网络标签页中检查 API 故障
   └─ 缺失的响应、4xx/5xx、CORS 错误
5. 在失败点插入 page.pause()
   └─ 检查实时 DOM，在控制台中尝试选择器
6. 检查浏览器控制台中的 JavaScript 错误
   └─ page.on('console') 或追踪中的控制台标签页

模式

模式 1：使用 UI 模式进行交互式调试

适用场景：开发新测试、本地调查失败原因、探索应用程序行为。 避免场景：CI 环境（改用追踪）。

UI 模式提供可视化时间线、每一步的 DOM 快照、网络瀑布图，以及重新运行单个测试的能力。

TypeScript

// 从终端启动 UI 模式：
// npx playwright test --ui

// 在 UI 模式下运行特定测试文件：
// npx playwright test tests/checkout.spec.ts --ui

// playwright.config.ts — 为 UI 模式便利性配置
import { defineConfig } from "@playwright/test"

export default defineConfig({
  use: {
    // 在 UI 模式下，追踪始终可用，不受此设置影响，
    // 但此设置确保 CI 失败时也能捕获追踪
    trace: "on-first-retry",
  },
})

JavaScript

// 从终端启动 UI 模式：
// npx playwright test --ui

// 在 UI 模式下运行特定测试文件：
// npx playwright test tests/checkout.spec.js --ui

// playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  use: {
    trace: "on-first-retry",
  },
})

模式 2：使用 PWDEBUG 的 Playwright Inspector

适用场景：需要逐步执行每个操作、交互式测试选择器，或查看每个操作前后的精确状态。 避免场景：错误信息或追踪本身已能显示失败原因。

TypeScript

// 从终端启动 Inspector：
// PWDEBUG=1 npx playwright test tests/login.spec.ts

// Windows PowerShell：
// $env:PWDEBUG=1; npx playwright test tests/login.spec.ts

// Windows CMD：
// set PWDEBUG=1 && npx playwright test tests/login.spec.ts

// Inspector 自动打开。使用以下控件：
// - "Step over"（单步跳过）按钮：每次执行一个操作
// - "Pick locator"（拾取定位器）按钮：悬停元素以查看最佳定位器
// - "Resume"（继续）按钮：运行到下一个 page.pause() 或结束

import { test, expect } from "@playwright/test"

test("调试登录流程", async ({ page }) => {
  await page.goto("/login")

  // 当 PWDEBUG=1 时，Inspector 会在每个操作前暂停
  await page.getByLabel("Email").fill("user@example.com")
  await page.getByLabel("Password").fill("password123")
  await page.getByRole("button", { name: "Sign in" }).click()

  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
})

JavaScript

// 从终端启动 Inspector：
// PWDEBUG=1 npx playwright test tests/login.spec.js

const { test, expect } = require("@playwright/test")

test("调试登录流程", async ({ page }) => {
  await page.goto("/login")

  await page.getByLabel("Email").fill("user@example.com")
  await page.getByLabel("Password").fill("password123")
  await page.getByRole("button", { name: "Sign in" }).click()

  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
})

模式 3：使用 Trace Viewer 分析 CI 失败

适用场景：测试在 CI 中失败，你需要理解发生了什么，而无需在本地重新运行。 避免场景：你能在本地复现失败（改用 UI 模式或 Inspector）。

TypeScript

// playwright.config.ts — 追踪配置
import { defineConfig } from "@playwright/test"

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: {
    // 'on-first-retry' — 仅在首次重试时捕获追踪（推荐用于 CI）
    // 'on' — 每次运行都捕获（临时用于顽固失败）
    // 'retain-on-failure' — 每次运行都捕获，仅保留失败的追踪
    trace: "on-first-retry",
  },
})

// CI 失败后，下载追踪产物并打开：
// npx playwright show-trace test-results/tests-login-Login-test-chromium/trace.zip

// 或者通过 URL 打开：
// npx playwright show-trace https://ci.example.com/artifacts/trace.zip

// 或者使用 trace.playwright.dev 在浏览器中查看追踪——拖放 zip 文件即可

JavaScript

// playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: "on-first-retry",
  },
})

// CI 失败后，下载追踪产物并打开：
// npx playwright show-trace test-results/tests-login-Login-test-chromium/trace.zip

阅读追踪——按顺序检查的内容：

1. Actions（操作）标签页——查看每个 Playwright 操作及其前后截图
2. Console（控制台）标签页——浏览器控制台输出（错误、警告、日志）
3. Network（网络）标签页——每个 HTTP 请求及其状态、耗时、请求/响应体
4. Source（源码）标签页——高亮显示失败行的测试源代码
5. Call（调用）标签页——每个 Playwright 调用的精确参数和返回值

模式 4：有头模式加慢速

适用场景：希望观察浏览器执行过程，而不想承受完整的 Inspector 开销。 避免场景：即使使用慢速模式，测试运行仍然太快而难以跟踪（改用 Inspector）。

TypeScript

// 从终端——快速可视化调试：
// npx playwright test tests/checkout.spec.ts --headed --slow-mo=500

// playwright.config.ts — 为本地开发配置有头模式
import { defineConfig } from "@playwright/test"

export default defineConfig({
  use: {
    // 不要提交这些设置——改用 CLI 标志或环境变量检查
    headless: !process.env.HEADED,
    launchOptions: {
      slowMo: process.env.SLOW_MO ? parseInt(process.env.SLOW_MO) : 0,
    },
  },
})

// 然后运行：
// HEADED=1 SLOW_MO=500 npx playwright test tests/checkout.spec.ts

JavaScript

// 从终端：
// npx playwright test tests/checkout.spec.js --headed --slow-mo=500

// playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  use: {
    headless: !process.env.HEADED,
    launchOptions: {
      slowMo: process.env.SLOW_MO ? parseInt(process.env.SLOW_MO) : 0,
    },
  },
})

模式 5：VS Code 集成

适用场景：你更喜欢基于 IDE 的调试，包括断点、变量检查和集成测试运行。 避免场景：你在调试 CI 独有的失败，且该失败无法在本地复现。

安装 Playwright Test for VS Code 扩展（ms-playwright.playwright）。

关键功能：

• 运行/调试单个测试——点击任意 test() 旁的绿色播放按钮
• 设置断点——点击左侧装订线设置断点；测试会自动在断点处暂停
• 拾取定位器——使用 "Pick locator" 命令悬停在元素上以获取最佳选择器
• 显示浏览器——在测试侧边栏中勾选 "Show Browser" 以在测试执行期间查看浏览器
• 监听模式——启用后可在保存文件时重新运行测试

TypeScript

// 在 VS Code 中调试时，使用 test.only() 聚焦单个测试，
// 而不是通过调试器运行整个套件
import { test, expect } from "@playwright/test"

test.only("调试这个特定测试", async ({ page }) => {
  await page.goto("/products")

  // 在这一行设置 VS Code 断点，然后在调试面板中检查 `page`
  const productCard = page.getByRole("listitem").filter({ hasText: "Widget" })
  await expect(productCard).toBeVisible()

  await productCard.getByRole("button", { name: "Add to cart" }).click()
  await expect(page.getByTestId("cart-count")).toHaveText("1")
})

JavaScript

const { test, expect } = require("@playwright/test")

test.only("调试这个特定测试", async ({ page }) => {
  await page.goto("/products")

  const productCard = page.getByRole("listitem").filter({ hasText: "Widget" })
  await expect(productCard).toBeVisible()

  await productCard.getByRole("button", { name: "Add to cart" }).click()
  await expect(page.getByTestId("cart-count")).toHaveText("1")
})

模式 6：捕获浏览器控制台日志

适用场景：怀疑存在 JavaScript 错误、客户端 API 调用失败，或应用程序级别的日志能解释失败原因。 避免场景：问题显然是追踪中可见的选择器或时序问题。

TypeScript

import { test, expect } from "@playwright/test"

test("捕获控制台输出", async ({ page }) => {
  // 收集所有控制台消息
  const consoleLogs: string[] = []
  page.on("console", (msg) => {
    consoleLogs.push(`[${msg.type()}] ${msg.text()}`)
  })

  // 捕获未捕获的异常
  page.on("pageerror", (error) => {
    console.error("页面错误:", error.message)
  })

  await page.goto("/dashboard")
  await page.getByRole("button", { name: "Load data" }).click()
  await expect(page.getByRole("table")).toBeVisible()

  // 失败时打印收集的日志以提供调试上下文
  console.log("浏览器控制台输出:", consoleLogs)
})

// 用于所有测试的控制台日志记录可复用 fixture
import { test as base } from "@playwright/test"

type ConsoleFixtures = {
  consoleMessages: string[]
}

export const test = base.extend<ConsoleFixtures>({
  consoleMessages: async ({ page }, use) => {
    const messages: string[] = []
    page.on("console", (msg) => messages.push(`[${msg.type()}] ${msg.text()}`))
    page.on("pageerror", (err) => messages.push(`[pageerror] ${err.message}`))
    await use(messages)
  },
})

JavaScript

const { test, expect } = require("@playwright/test")

test("捕获控制台输出", async ({ page }) => {
  const consoleLogs = []
  page.on("console", (msg) => {
    consoleLogs.push(`[${msg.type()}] ${msg.text()}`)
  })

  page.on("pageerror", (error) => {
    console.error("页面错误:", error.message)
  })

  await page.goto("/dashboard")
  await page.getByRole("button", { name: "Load data" }).click()
  await expect(page.getByRole("table")).toBeVisible()

  console.log("浏览器控制台输出:", consoleLogs)
})

// 用于控制台日志记录的可复用 fixture
const { test: base } = require("@playwright/test")

const test = base.extend({
  consoleMessages: async ({ page }, use) => {
    const messages = []
    page.on("console", (msg) => messages.push(`[${msg.type()}] ${msg.text()}`))
    page.on("pageerror", (err) => messages.push(`[pageerror] ${err.message}`))
    await use(messages)
  },
})

module.exports = { test }

模式 7：失败时截图

适用场景：你需要在失败发生的精确时刻获取可视化快照。 避免场景：已启用追踪（追踪已经在每一步包含了截图）。

TypeScript

// playwright.config.ts — 失败时自动截图
import { defineConfig } from "@playwright/test"

export default defineConfig({
  use: {
    // 'off' — 不截图（默认）
    // 'on' — 每次测试后截图
    // 'only-on-failure' — 仅在测试失败时截图（推荐）
    screenshot: "only-on-failure",
  },
})

// 在特定点手动截图
import { test, expect } from "@playwright/test"

test("调试视觉状态", async ({ page }) => {
  await page.goto("/checkout")
  await page.getByLabel("Promo code").fill("SAVE20")
  await page.getByRole("button", { name: "Apply" }).click()

  // 在断言前捕获截图以进行调试
  await page.screenshot({ path: "test-results/before-discount.png", fullPage: true })

  await expect(page.getByTestId("discount-amount")).toHaveText("-$20.00")
})

JavaScript

// playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  use: {
    screenshot: "only-on-failure",
  },
})

// 手动截图
const { test, expect } = require("@playwright/test")

test("调试视觉状态", async ({ page }) => {
  await page.goto("/checkout")
  await page.getByLabel("Promo code").fill("SAVE20")
  await page.getByRole("button", { name: "Apply" }).click()

  await page.screenshot({ path: "test-results/before-discount.png", fullPage: true })

  await expect(page.getByTestId("discount-amount")).toHaveText("-$20.00")
})

模式 8：网络调试

适用场景：怀疑 API 失败、请求负载错误、缺少认证头，或响应缓慢导致超时。 避免场景：追踪的网络标签页已显示问题所在。

TypeScript

import { test, expect } from "@playwright/test"

test("调试网络请求", async ({ page }) => {
  // 记录所有请求
  page.on("request", (request) => {
    console.log(`>> ${request.method()} ${request.url()}`)
  })

  // 记录所有响应及其状态码
  page.on("response", (response) => {
    console.log(`<< ${response.status()} ${response.url()}`)
  })

  // 记录失败的请求（网络错误，而非 HTTP 错误）
  page.on("requestfailed", (request) => {
    console.log(`失败: ${request.url()} ${request.failure()?.errorText}`)
  })

  await page.goto("/dashboard")
  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByRole("table")).toBeVisible()
})

// 等待特定 API 响应并检查它
test("检查 API 响应", async ({ page }) => {
  await page.goto("/products")

  const responsePromise = page.waitForResponse(
    (resp) => resp.url().includes("/api/products") && resp.status() === 200
  )

  await page.getByRole("button", { name: "Load products" }).click()

  const response = await responsePromise
  const body = await response.json()
  console.log("API 响应:", JSON.stringify(body, null, 2))

  await expect(page.getByRole("listitem")).toHaveCount(body.products.length)
})

JavaScript

const { test, expect } = require("@playwright/test")

test("调试网络请求", async ({ page }) => {
  page.on("request", (request) => {
    console.log(`>> ${request.method()} ${request.url()}`)
  })

  page.on("response", (response) => {
    console.log(`<< ${response.status()} ${response.url()}`)
  })

  page.on("requestfailed", (request) => {
    console.log(`失败: ${request.url()} ${request.failure()?.errorText}`)
  })

  await page.goto("/dashboard")
  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByRole("table")).toBeVisible()
})

test("检查 API 响应", async ({ page }) => {
  await page.goto("/products")

  const responsePromise = page.waitForResponse(
    (resp) => resp.url().includes("/api/products") && resp.status() === 200
  )

  await page.getByRole("button", { name: "Load products" }).click()

  const response = await responsePromise
  const body = await response.json()
  console.log("API 响应:", JSON.stringify(body, null, 2))

  await expect(page.getByRole("listitem")).toHaveCount(body.products.length)
})

模式 9：详细 API 日志

适用场景：你需要查看每个 Playwright API 调用及其耗时，以确定测试在何处花费时间或卡住。 避免场景：你已经知道哪个操作正在失败（改用 Inspector 或 page.pause()）。

# 查看所有 Playwright API 调用及时间戳
DEBUG=pw:api npx playwright test tests/slow-test.spec.ts

# 查看浏览器协议消息（非常详细——谨慎使用）
DEBUG=pw:protocol npx playwright test tests/slow-test.spec.ts

# 组合多个调试通道
DEBUG=pw:api,pw:browser npx playwright test tests/slow-test.spec.ts

# Windows PowerShell
$env:DEBUG="pw:api"; npx playwright test tests/slow-test.spec.ts

# Windows CMD
set DEBUG=pw:api && npx playwright test tests/slow-test.spec.ts

模式 10：page.pause() — 内联断点

适用场景：你需要在精确位置暂停执行，以检查实时 DOM、尝试定位器或检查应用程序状态。 避免场景：你可以使用 PWDEBUG=1，它会自动在每个步骤暂停。

TypeScript

import { test, expect } from "@playwright/test"

test("使用暂停进行调试", async ({ page }) => {
  await page.goto("/checkout")
  await page.getByLabel("Email").fill("user@example.com")

  // 执行在此处暂停——Inspector 会打开，提供：
  // - 实时 DOM 检查
  // - 选择器试验场（在控制台中尝试定位器）
  // - 逐步执行剩余操作
  await page.pause()

  // 这些操作会等待你在 Inspector 中点击 "Resume"
  await page.getByRole("button", { name: "Continue" }).click()
  await expect(page.getByText("Order confirmed")).toBeVisible()
})

JavaScript

const { test, expect } = require("@playwright/test")

test("使用暂停进行调试", async ({ page }) => {
  await page.goto("/checkout")
  await page.getByLabel("Email").fill("user@example.com")

  // 执行在此处暂停——Inspector 会打开
  await page.pause()

  await page.getByRole("button", { name: "Continue" }).click()
  await expect(page.getByText("Order confirmed")).toBeVisible()
})

重要提示：在提交前删除 page.pause()。它会在 CI 中无限挂起。使用此 lint 规则或 CI 检查：

# 添加到 pre-commit 钩子或 CI 流水线
grep -r "page.pause()" tests/ && echo "错误：提交前请移除 page.pause()" && exit 1

决策指南

使用此表格根据失败类型选择正确的工具。

失败类型	首选工具	原因
元素未找到（选择器错误）	UI 模式（--ui）	在失败时刻查看 DOM，在 Pick Locator 中尝试选择器
元素未找到（时序问题）	Trace Viewer — Actions（操作）标签页	比较前后截图，查看元素是否在超时后才出现
文本/值错误	Trace Viewer — Actions（操作）标签页	检查每个操作步骤的实际 DOM 内容
测试挂起/超时	DEBUG=pw:api	查看哪个 API 调用正在等待且从未完成
网络/API 失败	Trace Viewer — Network（网络）标签页	查看请求/响应状态码、负载、耗时
认证/会话问题	网络调试（page.on('response')）	检查 401/403 响应、缺少的 cookie/token
视觉渲染错误	--headed --slow-mo=500	在浏览器中观察实际渲染
应用中的 JavaScript 错误	控制台日志记录（page.on('console')）	捕获未捕获的异常和错误日志
仅 CI 失败	Trace Viewer（来自 CI 产物）	无需在本地运行即可重现精确的 CI 状态
不稳定/间歇性失败	每次运行追踪（trace: 'on'）加重试	并排比较通过和失败的追踪
状态污染	使用 test.only() 运行单个测试	与其他测试隔离；如果单独通过，则状态来自其他测试的泄漏

反模式

使用 waitForTimeout 修复时序问题

// 错误——任意延迟掩盖了真正的问题，使测试变得缓慢且不稳定
await page.getByRole("button", { name: "Submit" }).click()
await page.waitForTimeout(3000) // "加上这个延迟就能工作"
await expect(page.getByText("Success")).toBeVisible()

// 正确——等待实际条件
await page.getByRole("button", { name: "Submit" }).click()
await expect(page.getByText("Success")).toBeVisible() // 自动重试最长 5 秒

如果默认超时不够，请调查操作缓慢的_原因_，然后要么：

• 修复应用程序性能
• 增加特定断言的超时时间：await expect(locator).toBeVisible({ timeout: 15000 })
• 等待前置条件：await page.waitForResponse('**/api/submit')

注释掉测试以隔离失败

// 错误——注释掉测试以找出哪个导致失败
// test('test A', ...);
// test('test B', ...);
test("test C — 这个会失败", async ({ page }) => {
  /* ... */
})

// 正确——使用 .only 运行单个测试
test.only("test C — 这个会失败", async ({ page }) => {
  /* ... */
})

// 正确——使用 grep 运行匹配模式的测试
// npx playwright test --grep "test C"

不阅读完整的错误信息

Playwright 错误信息包括：

• 预期值与实际值
• 使用的定位器
• 调用日志，显示 Playwright 在超时前尝试的操作
• 测试中的行号

阅读全部内容。仅凭调用日志通常就能精确显示问题所在（例如，元素存在但被隐藏时显示"等待选择器可见"）。

在没有追踪的情况下调试 CI 失败

// 错误——CI 中没有追踪，无法调试失败
export default defineConfig({
  use: {
    trace: "off",
  },
})

// 正确——始终在 CI 失败时捕获追踪
export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: "on-first-retry",
  },
})

使用 console.log 代替正确的调试工具

// 错误——到处散布 console.log
test("使用日志调试", async ({ page }) => {
  await page.goto("/dashboard")
  console.log("页面已加载")
  const el = page.getByRole("button", { name: "Save" })
  console.log("按钮已找到:", await el.isVisible())
  console.log("按钮文本:", await el.textContent())
  // ...另外 20 个 console.log 调用

  // 正确——在感兴趣的点使用 page.pause()
  await page.goto("/dashboard")
  await page.pause() // 交互式检查所有内容
})

提交包含 page.pause() 或 test.only() 的代码

// 错误——这些永远不应进入 CI
test.only("聚焦测试", async ({ page }) => {
  // 跳过所有其他测试
  await page.goto("/")
  await page.pause() // 在 CI 中永远挂起
})

// 如果在开发中需要，添加 CI 防护
if (!process.env.CI) {
  await page.pause()
}

故障排查

症状	可能原因	修复方法
Inspector 在 PWDEBUG=1 时不打开	在无头模式下运行，或 workers 大于 1	使用 --headed 和 --workers=1 运行
追踪为空或缺失	配置中 trace: 'off'，或测试未重试	临时设置为 trace: 'on'，或 trace: 'retain-on-failure'
UI 模式显示过时的测试结果	文件监听器未检测到更改	停止 UI 模式，清除 test-results/，重新启动
page.pause() 无效果	未设置 PWDEBUG 且在无头模式下运行	使用 --headed 运行或设置 PWDEBUG=1
截图空白或尺寸错误	未设置视口或测试在错误的浏览器项目中运行	在配置中设置 viewport；检查哪个浏览器项目运行了
详细日志信息量过大	使用了 DEBUG=pw:protocol	使用 DEBUG=pw:api 以获得可管理的详细级别
追踪文件过大	对所有测试都开启 trace: 'on'，包括通过的测试	切换到 trace: 'on-first-retry' 或 trace: 'retain-on-failure'
VS Code 未检测到测试	testDir 或 testMatch 配置错误	确保配置路径匹配，且扩展设置指向你的 playwright.config
网络事件未触发	请求在监听器附加之前已发出	在 page.goto() 之前附加 page.on('request') 和 page.on('response')

相关文档

• core/error-index.md — 查询特定错误信息
• core/flaky-tests.md — 间歇性失败模式及修复
• core/common-pitfalls.md — 常见初学者错误
• core/assertions-and-waiting.md — 以 Web 为先的断言和自动等待
• core/configuration.md — 追踪、截图和重试配置
• ci/reporting-and-artifacts.md — 用于追踪和截图的 CI 产物收集配置