# 调试 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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

```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**

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

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

```typescript
// 在特定点手动截图
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**

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

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

```javascript
// 手动截图
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**

```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**

```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()`）。

```bash
# 查看所有 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**

```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**

```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 检查：

```bash
# 添加到 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` 修复时序问题

```typescript
// 错误——任意延迟掩盖了真正的问题，使测试变得缓慢且不稳定
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')`

### 注释掉测试以隔离失败

```typescript
// 错误——注释掉测试以找出哪个导致失败
// 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 失败

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

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

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

```typescript
// 错误——到处散布 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()` 的代码

```typescript
// 错误——这些永远不应进入 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](error-index.md) — 查询特定错误信息
- [core/flaky-tests.md](flaky-tests.md) — 间歇性失败模式及修复
- [core/common-pitfalls.md](common-pitfalls.md) — 常见初学者错误
- [core/assertions-and-waiting.md](assertions-and-waiting.md) — 以 Web 为先的断言和自动等待
- [core/configuration.md](configuration.md) — 追踪、截图和重试配置
- [ci/reporting-and-artifacts.md](../ci/reporting-and-artifacts.md) — 用于追踪和截图的 CI 产物收集配置