# Playwright 错误索引

针对特定 Playwright 错误消息的快速参考手册。找到你的错误，了解原因，应用修复。

> **如何使用**：在此文件中搜索你在终端或测试报告中看到的确切错误文本。每条记录都给出了原因和可行的修复方案。

---

## 定位器与元素错误

---

### "locator.click: Target closed"

**原因**：Playwright 完成对元素的操作之前，页面或框架发生了导航跳转（或已被关闭）。

**常见触发场景**：

- 点击触发导航的链接时，另一个操作仍在等待中
- 表单提交导致页面重新加载，而后续的 `click()` 或 `fill()` 尚未完成
- 在 `finally` 块中调用了 `page.close()` 或 `context.close()`，与正在执行的操作产生竞态
- 应用程序中未处理的异常触发了错误页面的重定向

**修复**：在执行下一个操作之前等待导航完成，或者使用 `Promise.all` 协调点击和导航。

```typescript
// TypeScript — 等待由点击链接引起的导航完成
await Promise.all([
  page.waitForURL("**/dashboard"),
  page.getByRole("link", { name: "Dashboard" }).click(),
])
```

```javascript
// JavaScript — 相同的模式
await Promise.all([
  page.waitForURL("**/dashboard"),
  page.getByRole("link", { name: "Dashboard" }).click(),
])
```

如果页面是有意关闭的（例如弹窗），请在操作之前捕获引用：

```typescript
// TypeScript — 处理自动关闭的弹窗
const popupPromise = page.waitForEvent("popup")
await page.getByRole("button", { name: "Open popup" }).click()
const popup = await popupPromise
await popup.waitForLoadState()
// 在弹窗关闭前与其交互
await popup.getByRole("button", { name: "Confirm" }).click()
```

```javascript
// JavaScript — 处理自动关闭的弹窗
const popupPromise = page.waitForEvent("popup")
await page.getByRole("button", { name: "Open popup" }).click()
const popup = await popupPromise
await popup.waitForLoadState()
await popup.getByRole("button", { name: "Confirm" }).click()
```

**相关**：[core/assertions-and-waiting.md](assertions-and-waiting.md)、[core/multi-context-and-popups.md](multi-context-and-popups.md)

---

### "waiting for locator('...') to be visible"

**原因**：Playwright 的自动等待超时，因为元素从未出现在 DOM 中或一直处于隐藏状态（例如 `display: none`、`visibility: hidden`、零尺寸或位于 `aria-hidden` 之后）。

**常见触发场景**：

- 元素是条件渲染的，但条件未满足（缺少数据、未认证状态）
- 内容是异步加载的，定位器在 API 响应返回之前就被执行了
- 选择器错误——角色、名称或测试 ID 中有拼写错误
- 元素存在但在屏幕之外或位于折叠的容器内
- CSS 动画或过渡使元素保持 `opacity: 0`，而 Playwright 尚未判定为可见

**修复**：首先使用 Playwright Inspector 确认定位器与你期望的元素匹配。然后确保元素出现的先决条件已满足。

```typescript
// TypeScript — 调试：检查定位器解析出什么
console.log(await page.getByRole("button", { name: "Submit" }).count())
// 如果为 0，则元素不在 DOM 中——检查选择器或页面状态

// 正确做法：先等待数据加载完成
await page.waitForResponse((resp) => resp.url().includes("/api/data") && resp.status() === 200)
await expect(page.getByRole("button", { name: "Submit" })).toBeVisible()
```

```javascript
// JavaScript — 相同的做法
console.log(await page.getByRole("button", { name: "Submit" }).count())

await page.waitForResponse((resp) => resp.url().includes("/api/data") && resp.status() === 200)
await expect(page.getByRole("button", { name: "Submit" })).toBeVisible()
```

**相关**：[core/locators.md](locators.md)、[core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "locator.click: Error: strict mode violation"

**原因**：定位器匹配了多个元素，Playwright 的严格模式（默认启用）拒绝在模棱两可的匹配上执行操作。

**常见触发场景**：

- 页面上存在多个按钮时使用 `getByRole('button')`
- "Save" 和 "Save as draft" 同时存在时使用 `getByText('Save')`
- 需要 `exact: true` 时使用了部分文本匹配
- 同一个组件被渲染了多次（例如在列表中）

**修复**：使定位器更加具体，确保解析到唯一一个元素。

```typescript
// TypeScript

// 不好——匹配了多个按钮
await page.getByRole("button", { name: "Save" }).click()

// 好——使用精确匹配
await page.getByRole("button", { name: "Save", exact: true }).click()

// 好——限定到特定容器
await page.getByRole("dialog").getByRole("button", { name: "Save" }).click()

// 好——在顺序有意义时使用 .first()、.last()、.nth()
await page.getByRole("listitem").first().click()

// 好——针对列表项链式使用 filter
await page
  .getByRole("listitem")
  .filter({ hasText: "Project Alpha" })
  .getByRole("button", { name: "Delete" })
  .click()
```

```javascript
// JavaScript

// 不好——匹配了多个按钮
await page.getByRole("button", { name: "Save" }).click()

// 好——使用精确匹配
await page.getByRole("button", { name: "Save", exact: true }).click()

// 好——限定到特定容器
await page.getByRole("dialog").getByRole("button", { name: "Save" }).click()

// 好——在顺序有意义时使用 .first()、.last()、.nth()
await page.getByRole("listitem").first().click()

// 好——针对列表项链式使用 filter
await page
  .getByRole("listitem")
  .filter({ hasText: "Project Alpha" })
  .getByRole("button", { name: "Delete" })
  .click()
```

**相关**：[core/locators.md](locators.md)、[core/locator-strategy.md](locator-strategy.md)

---

### "Error: expect(locator).toBeVisible() — locator resolved to X elements"

**原因**：与上述严格模式违规的根因相同——断言的定位器匹配了多个元素，因此 Playwright 无法确定要对哪个元素进行断言。

**常见触发场景**：

- 与上述严格模式违规的触发场景相同
- 当存在多个 `.item` 元素时写 `expect(page.locator('.item')).toBeVisible()`

**修复**：将定位器缩小到单个元素（参见上方严格模式违规的修复方法）。或者，如果你有意要检查所有匹配：

```typescript
// TypeScript — 断言数量而非可见性
await expect(page.getByRole("listitem")).toHaveCount(5)

// 或者对特定元素进行断言
await expect(page.getByRole("listitem").first()).toBeVisible()

// 或者使用循环断言所有元素都可见
for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toBeVisible()
}
```

```javascript
// JavaScript — 断言数量而非可见性
await expect(page.getByRole("listitem")).toHaveCount(5)

// 或者对特定元素进行断言
await expect(page.getByRole("listitem").first()).toBeVisible()

// 或者使用循环断言所有元素都可见
for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toBeVisible()
}
```

**相关**：[core/locators.md](locators.md)、[core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "locator.fill: Error: Element is not an <input>, <textarea> or [contenteditable] element"

**原因**：`fill()` 只能用于 `<input>`、`<textarea>` 或带有 `contenteditable` 属性的元素。定位器解析到了不同的元素类型（例如 `<div>`、`<label>` 或 `<form>` 本身）。

**常见触发场景**：

- 按标签文本定位，但标签和输入框没有通过 `for`/`id` 正确关联
- 使用了 `getByText()` 而不是 `getByLabel()` 或 `getByRole('textbox')`
- 自定义组件将实际的 `<input>` 包裹在样式化的 `<div>` 中
- 富文本编辑器在内部元素上使用了 `contenteditable`，而不是外层包装器

**修复**：定位到实际的输入元素。

```typescript
// TypeScript

// 不好——定位到了标签，而不是输入框
await page.getByText("Email").fill("user@example.com")

// 好——getByLabel 找到关联的输入框
await page.getByLabel("Email").fill("user@example.com")

// 好——按角色定位
await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")

// 对于 contenteditable 富文本编辑器
await page.locator('[contenteditable="true"]').fill("Hello world")

// 如果 fill() 仍然不起作用（例如自定义组件），使用键盘输入
await page.getByRole("textbox", { name: "Email" }).click()
await page.keyboard.type("user@example.com")
```

```javascript
// JavaScript

// 不好——定位到了标签，而不是输入框
await page.getByText("Email").fill("user@example.com")

// 好——getByLabel 找到关联的输入框
await page.getByLabel("Email").fill("user@example.com")

// 好——按角色定位
await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")

// 对于 contenteditable 富文本编辑器
await page.locator('[contenteditable="true"]').fill("Hello world")

// 如果 fill() 仍然不起作用（例如自定义组件），使用键盘输入
await page.getByRole("textbox", { name: "Email" }).click()
await page.keyboard.type("user@example.com")
```

**相关**：[core/locators.md](locators.md)、[core/forms-and-validation.md](forms-and-validation.md)

---

### "Error: elementHandle.click: Node is not an Element"

**原因**：你正在使用旧的 ElementHandle API，并且该句柄已经过期——底层的 DOM 节点已被移除或被重新渲染所替换。

**常见触发场景**：

- 将 `elementHandle` 存储在变量中，并在导航或 React/Vue 重新渲染后使用它
- 使用 `page.$()` 或 `page.$$()` 而不是 Locator API
- 框架的水合（hydration）过程用客户端渲染的节点替换了服务端渲染的节点

**修复**：从 ElementHandle 切换到 Locator。Locator 在每次操作时都会重新查询 DOM，永不过期。

```typescript
// TypeScript

// 不好——过期的句柄
const button = await page.$("button.submit")
// ... 页面重新渲染 ...
await button!.click() // Node is not an Element

// 好——locator 始终重新查询
const button = page.getByRole("button", { name: "Submit" })
// ... 页面重新渲染 ...
await button.click() // 正常运行
```

```javascript
// JavaScript

// 不好——过期的句柄
const button = await page.$("button.submit")
// ... 页面重新渲染 ...
await button.click() // Node is not an Element

// 好——locator 始终重新查询
const button = page.getByRole("button", { name: "Submit" })
// ... 页面重新渲染 ...
await button.click() // 正常运行
```

**相关**：[core/locators.md](locators.md)

---

### "Error: locator.click: Timeout 30000ms exceeded"

**原因**：元素已在 DOM 中找到，但在超时时间内未能变得可操作。"可操作"意味着可见、稳定（无动画）、已启用且未被其他元素遮挡。

**常见触发场景**：

- 遮罩层、模态框或提示框覆盖了元素
- 元素处于禁用状态（`disabled` 属性或 `aria-disabled="true"`）
- CSS 动画尚未完成（元素仍在移动）
- 加载中的旋转图标覆盖在按钮上方
- 元素位于视口之外，Playwright 的自动滚动失败

**修复**：使用 trace 识别是什么阻止了操作，然后解决问题。

```typescript
// TypeScript

// 第 1 步：启用 tracing 以进行诊断
// 在 playwright.config.ts 中：
// use: { trace: 'on-first-retry' }
// 然后运行：npx playwright show-trace trace.zip

// 常见修复：等待遮罩层消失
await expect(page.locator(".loading-overlay")).toBeHidden()
await page.getByRole("button", { name: "Submit" }).click()

// 常见修复：当你确认遮罩层无害时使用强制点击
// （谨慎使用——这会跳过可操作性检查）
await page.getByRole("button", { name: "Submit" }).click({ force: true })

// 常见修复：等待元素变为可用
await expect(page.getByRole("button", { name: "Submit" })).toBeEnabled()
await page.getByRole("button", { name: "Submit" }).click()
```

```javascript
// JavaScript

// 常见修复：等待遮罩层消失
await expect(page.locator(".loading-overlay")).toBeHidden()
await page.getByRole("button", { name: "Submit" }).click()

// 常见修复：强制点击（谨慎使用）
await page.getByRole("button", { name: "Submit" }).click({ force: true })

// 常见修复：等待元素变为可用
await expect(page.getByRole("button", { name: "Submit" })).toBeEnabled()
await page.getByRole("button", { name: "Submit" }).click()
```

**相关**：[core/assertions-and-waiting.md](assertions-and-waiting.md)、[core/debugging.md](debugging.md)

---

## 导航与页面错误

---

### "page.goto: net::ERR_CONNECTION_REFUSED"

**原因**：Playwright 无法连接到目标 URL。服务器未运行，或未在预期的主机/端口上监听。

**常见触发场景**：

- 运行测试前忘记启动开发服务器
- 开发服务器端口与配置中的 `baseURL` 不一致
- 服务器在 `127.0.0.1` 上监听，但测试使用的是 `localhost`（或反之），且操作系统解析方式不同
- 在 CI 中，应用构建/启动步骤静默失败
- Docker 容器网络：应用在容器内运行，但测试试图访问 `localhost`

**修复**：使用 `webServer` 配置选项让 Playwright 自动启动和管理开发服务器。

```typescript
// TypeScript — playwright.config.ts
import { defineConfig } from "@playwright/test"

export default defineConfig({
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000, // 服务器启动等待 2 分钟
  },
  use: {
    baseURL: "http://localhost:3000",
  },
})
```

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

module.exports = defineConfig({
  webServer: {
    command: "npm run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
  use: {
    baseURL: "http://localhost:3000",
  },
})
```

**相关**：[core/configuration.md](configuration.md)、[ci/ci-github-actions.md](../ci/ci-github-actions.md)

---

### "page.goto: Timeout 30000ms exceeded"

**原因**：页面未能在导航超时时间内达到 `load` 状态（默认情况下）。服务器有响应，但页面加载完整花费的时间过长。

**常见触发场景**：

- 大型资源（图片、字体、脚本）拖慢了页面加载
- 第三方脚本（分析工具、广告）阻塞了加载事件
- 页面在变得可交互之前发出了大量 API 调用
- 服务器响应了一个耗时的重定向链

**修复**：使用更合适的 `waitUntil` 选项或增大导航超时时间。

```typescript
// TypeScript

// 如果不需要所有资源，使用 'domcontentloaded' 代替 'load'
await page.goto("/dashboard", { waitUntil: "domcontentloaded" })

// 或者为已知的慢页面增加导航超时时间
await page.goto("/dashboard", { timeout: 60_000 })

// 或者在配置中全局设置
// playwright.config.ts
export default defineConfig({
  use: {
    navigationTimeout: 60_000,
  },
})
```

```javascript
// JavaScript

await page.goto("/dashboard", { waitUntil: "domcontentloaded" })

await page.goto("/dashboard", { timeout: 60_000 })

// playwright.config.js
module.exports = defineConfig({
  use: {
    navigationTimeout: 60_000,
  },
})
```

**相关**：[core/configuration.md](configuration.md)

---

### "Error: page.goto: Navigation failed because page was closed!"

**原因**：`goto()` 还在进行中时，页面或浏览器上下文就被关闭了。这通常发生在拆卸/清理的竞态条件下。

**常见触发场景**：

- `afterEach` 或 fixture 在导航完成前关闭了页面/上下文
- 另一个测试或钩子过早调用了 `browser.close()`
- 测试失败，异步导航仍在等待时清理逻辑执行了
- 在异步操作开始后使用了 `test.fixme()` 或 `test.skip()`

**修复**：确保所有页面操作完成后才执行清理。使用 fixtures 进行生命周期管理，而不是手动 `afterEach`。

```typescript
// TypeScript

// 不好——测试体与清理之间存在竞态条件
test.afterEach(async ({ page }) => {
  await page.close() // 可能与正在进行的导航产生竞态
})

// 好——让 Playwright 通过 fixtures 管理页面生命周期
// Playwright 会自动为每个测试创建和销毁页面
// 无需手动清理

// 如果需要自定义清理，请确保先等待所有导航完成
test("navigates to dashboard", async ({ page }) => {
  const responsePromise = page.waitForResponse("**/api/user")
  await page.goto("/dashboard")
  await responsePromise // 确保所有异步操作完成
  // 测试断言在此
})
```

```javascript
// JavaScript — 相同的模式

test("navigates to dashboard", async ({ page }) => {
  const responsePromise = page.waitForResponse("**/api/user")
  await page.goto("/dashboard")
  await responsePromise
  // 测试断言在此
})
```

**相关**：[core/fixtures-and-hooks.md](fixtures-and-hooks.md)

---

### "page.waitForNavigation: Timeout 30000ms exceeded"

**原因**：`waitForNavigation()` 等待一个完整的页面导航，但该导航从未发生。在 SPA 中，客户端路由不会触发导航事件。

**常见触发场景**：

- 在使用 React Router、Vue Router 或 Next.js 客户端导航的 SPA 中使用了 `waitForNavigation()`
- 在 `waitForNavigation()` 被调用之前导航已经发生（竞态条件）
- 使用了已废弃的模式，而 `waitForURL()` 才是正确的替代方法

**修复**：将 `waitForNavigation()` 替换为 `waitForURL()`，后者同时适用于 SPA 和传统的页面加载。

```typescript
// TypeScript

// 不好——已废弃、易产生竞态、不支持 SPA 路由
await page.waitForNavigation()

// 好——同时适用于 SPA 和完整导航
await page.getByRole("link", { name: "Dashboard" }).click()
await page.waitForURL("**/dashboard")

// 好——结合 glob 模式使用
await page.waitForURL(/\/dashboard\/\d+/)

// 好——对于 SPA 路由变化，断言可见内容
await page.getByRole("link", { name: "Settings" }).click()
await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible()
```

```javascript
// JavaScript

// 不好——已废弃、易产生竞态
await page.waitForNavigation()

// 好——同时适用于 SPA 和完整导航
await page.getByRole("link", { name: "Dashboard" }).click()
await page.waitForURL("**/dashboard")

// 好——结合 glob 模式使用
await page.waitForURL(/\/dashboard\/\d+/)

// 好——对于 SPA 路由变化，断言可见内容
await page.getByRole("link", { name: "Settings" }).click()
await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible()
```

**相关**：[core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "Error: frame.goto: Frame was detached"

**原因**：Playwright 正在导航或与该 iframe 交互时，它被从 DOM 中移除了（已分离）。

**常见触发场景**：

- 父页面重新渲染并重新创建了 iframe 元素
- 父页面上的 JavaScript 移除后又重新添加了 iframe
- SPA 路由变化卸载了包含 iframe 的组件
- 广告 iframe 自行重新加载

**修复**：在父页面更新后重新获取 frame 引用。

```typescript
// TypeScript

// 不好——frame 引用变得过期
const frame = page.frameLocator("#my-iframe")
// ... 父页面重新渲染 ...
await frame.getByRole("button").click() // Frame was detached

// 好——使用 frameLocator（每次重新求值）
// frameLocator 本身是惰性的，但它指向的 frame 必须存在
await expect(page.frameLocator("#my-iframe").getByRole("button")).toBeVisible()
await page.frameLocator("#my-iframe").getByRole("button").click()

// 好——等待 iframe 在重新渲染后出现
await expect(page.locator("#my-iframe")).toBeAttached()
await page.frameLocator("#my-iframe").getByRole("button").click()
```

```javascript
// JavaScript

// 好——frameLocator 惰性重新求值
await expect(page.frameLocator("#my-iframe").getByRole("button")).toBeVisible()
await page.frameLocator("#my-iframe").getByRole("button").click()

// 好——等待 iframe 在重新渲染后出现
await expect(page.locator("#my-iframe")).toBeAttached()
await page.frameLocator("#my-iframe").getByRole("button").click()
```

**相关**：[core/iframes-and-shadow-dom.md](iframes-and-shadow-dom.md)

---

## 测试框架错误

---

### "Error: Test timeout of 30000ms exceeded"

**原因**：整个测试（包括所有钩子和断言）未能在配置的测试超时时间内完成。

**常见触发场景**：

- 等待一个永不出现的元素（错误的定位器、缺少数据）
- 未解决的 `page.waitForEvent()`——预期的事件从未触发
- 缓慢的测试环境（资源受限的 CI）
- 单个测试中包含过多顺序操作
- `beforeEach` 钩子执行了昂贵的设置（登录、数据填充）

**修复**：使用 `test.step()` 和 traces 识别慢速步骤，然后修复根本原因或调整超时时间。

```typescript
// TypeScript

// 为特定的慢速测试增加超时时间
test("generates large report", async ({ page }) => {
  test.setTimeout(120_000) // 仅此测试 2 分钟
  // ...
})

// 在配置中全局增加超时时间
// playwright.config.ts
export default defineConfig({
  timeout: 60_000, // 每个测试 60 秒
})

// 更好的做法：使用 test.step() 诊断哪些步骤慢
test("checkout flow", async ({ page }) => {
  await test.step("add item to cart", async () => {
    await page.goto("/products")
    await page.getByRole("button", { name: "Add to Cart" }).click()
  })

  await test.step("complete checkout", async () => {
    await page.getByRole("link", { name: "Cart" }).click()
    await page.getByRole("button", { name: "Checkout" }).click()
  })
})
```

```javascript
// JavaScript

test("generates large report", async ({ page }) => {
  test.setTimeout(120_000)
  // ...
})

// playwright.config.js
module.exports = defineConfig({
  timeout: 60_000,
})

test("checkout flow", async ({ page }) => {
  await test.step("add item to cart", async () => {
    await page.goto("/products")
    await page.getByRole("button", { name: "Add to Cart" }).click()
  })

  await test.step("complete checkout", async () => {
    await page.getByRole("link", { name: "Cart" }).click()
    await page.getByRole("button", { name: "Checkout" }).click()
  })
})
```

**相关**：[core/configuration.md](configuration.md)、[core/debugging.md](debugging.md)

---

### "Error: expect(received).toMatchSnapshot()"

**原因**：当前的截图或文本与存储的基线快照不匹配。

**常见触发场景**：

- 合法的 UI 更改需要更新快照
- 本地与 CI 之间的渲染差异（字体、抗锯齿、操作系统级渲染）
- 动态内容（时间戳、随机 ID、广告）在运行之间发生变化
- 不同环境之间的视口大小或设备模拟设置不同

**修复**：如果更改是有意的，则更新快照；或者遮罩/隐藏动态区域。

```typescript
// TypeScript

// 在有意更改后更新快照
// 运行：npx playwright test --update-snapshots

// 在截图前遮罩动态内容
await expect(page).toHaveScreenshot("dashboard.png", {
  mask: [page.locator(".timestamp"), page.locator(".random-ad")],
  maxDiffPixelRatio: 0.01, // 允许 1% 的像素差异
})

// 使用带清理器的文本快照处理动态值
const content = await page.getByRole("main").textContent()
const sanitized = content!.replace(/\d{4}-\d{2}-\d{2}/g, "DATE")
expect(sanitized).toMatchSnapshot("dashboard-content.txt")
```

```javascript
// JavaScript

// 更新快照：npx playwright test --update-snapshots

await expect(page).toHaveScreenshot("dashboard.png", {
  mask: [page.locator(".timestamp"), page.locator(".random-ad")],
  maxDiffPixelRatio: 0.01,
})

const content = await page.getByRole("main").textContent()
const sanitized = content.replace(/\d{4}-\d{2}-\d{2}/g, "DATE")
expect(sanitized).toMatchSnapshot("dashboard-content.txt")
```

**相关**：[core/visual-regression.md](visual-regression.md)

---

### "Error: browserType.launch: Executable doesn't exist"

**原因**：Playwright 浏览器二进制文件未在此机器上安装，或者安装的版本与当前的 Playwright 版本不匹配。

**常见触发场景**：

- 新克隆项目后未运行安装步骤
- 升级了 `@playwright/test` 但没有重新安装浏览器
- CI 环境缺少安装步骤
- 使用 `npm ci` 会清理 `node_modules`，但不会触发浏览器安装的 postinstall 脚本
- 安装了多个 Playwright 版本（全局与本地冲突）

**修复**：安装浏览器。

```bash
# 安装所有浏览器
npx playwright install

# 只安装需要的浏览器（CI 中更快）
npx playwright install chromium

# 安装浏览器及操作系统依赖（CI/Docker 中需要）
npx playwright install --with-deps

# 如果在 CI Dockerfile 中，将此添加到 Dockerfile
# RUN npx playwright install --with-deps chromium
```

对于 CI 流水线，始终包含安装步骤：

```yaml
# GitHub Actions 示例
- name: Install Playwright Browsers
  run: npx playwright install --with-deps
```

**相关**：[ci/ci-github-actions.md](../ci/ci-github-actions.md)、[ci/docker-and-containers.md](../ci/docker-and-containers.md)

---

### "Error: Cannot use import statement outside a module"

**原因**：Node.js 以 CommonJS 模式运行测试文件，但文件使用了 ES 模块的 `import` 语法，且没有正确的配置。

**常见触发场景**：

- 缺少或配置错误的 `tsconfig.json`
- 使用了 `.ts` 文件，但 `@playwright/test` 未能正确解析 TypeScript
- `package.json` 没有 `"type": "module"` 设置，但测试文件使用了 `import`
- 直接使用 `node` 而不是通过 `npx playwright test` 运行测试文件
- 冲突的 Babel 或 ts-node 配置

**修复**：确保 TypeScript 配置正确，并始终通过 Playwright CLI 运行测试。

```bash
# 始终通过 Playwright CLI 运行测试——绝不要直接使用 node
npx playwright test

# 不要这样：
# node tests/example.spec.ts  <-- 会失败
```

```typescript
// TypeScript — tsconfig.json（最小工作配置）
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}
```

如果使用 JavaScript 而非 TypeScript：

```javascript
// JavaScript — 确保 package.json 有 "type": "module"
// 或将文件重命名为 .mjs

// 在 playwright.config.js 中——如果 package.json 缺少 "type": "module"，则使用 require
const { defineConfig } = require("@playwright/test")
module.exports = defineConfig({
  /* ... */
})
```

**相关**：[core/configuration.md](configuration.md)

---

### "Error: fixture \"xxx\" has already been registered"

**原因**：在多个 `test.extend()` 调用中定义了同名的自定义 fixture，且这些调用被合并了；或者同一 fixture 名称在同一个扩展中被注册了两次。

**常见触发场景**：

- 两个不同的 fixture 文件都定义了同名 fixture
- 从多个文件中导入扩展后的 `test` 对象，这些文件各自添加了重叠的 fixture
- 复制粘贴 fixture 定义时没有重命名

**修复**：确保每个 fixture 名称在你合并后的 fixture 链中是唯一的。使用一个统一的 fixture 文件来组合所有扩展。

```typescript
// TypeScript

// 不好——两个独立的扩展包含同名的 fixture
// fixtures/auth.ts
export const test = base.extend<{ user: User }>({
  user: async ({}, use) => {
    /* ... */
  },
})

// fixtures/data.ts — 冲突："user" 已存在
export const test = base.extend<{ user: User }>({
  user: async ({}, use) => {
    /* ... */
  },
})

// 好——单个合并后的 fixture 文件
// fixtures/index.ts
import { test as base } from "@playwright/test"

type MyFixtures = {
  authenticatedUser: User
  testData: TestData
}

export const test = base.extend<MyFixtures>({
  authenticatedUser: async ({}, use) => {
    const user = await createUser()
    await use(user)
    await deleteUser(user)
  },
  testData: async ({}, use) => {
    const data = await seedData()
    await use(data)
    await cleanupData(data)
  },
})

export { expect } from "@playwright/test"
```

```javascript
// JavaScript

// 好——单个合并后的 fixture 文件
// fixtures/index.js
const { test: base } = require("@playwright/test")

const test = base.extend({
  authenticatedUser: async ({}, use) => {
    const user = await createUser()
    await use(user)
    await deleteUser(user)
  },
  testData: async ({}, use) => {
    const data = await seedData()
    await use(data)
    await cleanupData(data)
  },
})

module.exports = { test }
```

**相关**：[core/fixtures-and-hooks.md](fixtures-and-hooks.md)

---

## 网络与 API 错误

---

### "page.route: Pattern should start with..."

**原因**：传递给 `page.route()` 的 URL 模式不符合预期格式。Playwright 期望一个 glob 模式（以 `**/` 或 `http` 开头）、一个正则表达式或一个谓词函数。

**常见触发场景**：

- 传递裸路径如 `/api/users` 而不是 `**/api/users`
- 对于相对模式缺少 `**` glob 前缀
- 传递了对象或无效类型而不是字符串/正则表达式

**修复**：使用正确的模式格式。

```typescript
// TypeScript

// 不好——没有 glob 前缀的裸路径
await page.route("/api/users", (route) => route.fulfill({ body: "[]" }))

// 好——glob 模式
await page.route("**/api/users", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify([{ id: 1, name: "Alice" }]),
  })
)

// 好——正则表达式模式
await page.route(/\/api\/users\/\d+/, (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ id: 1, name: "Alice" }),
  })
)

// 好——用于复杂匹配的谓词函数
await page.route(
  (url) => url.pathname.startsWith("/api/") && url.searchParams.has("filter"),
  (route) => route.fulfill({ body: "[]" })
)
```

```javascript
// JavaScript

// 好——glob 模式
await page.route("**/api/users", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify([{ id: 1, name: "Alice" }]),
  })
)

// 好——正则表达式模式
await page.route(/\/api\/users\/\d+/, (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ id: 1, name: "Alice" }),
  })
)

// 好——谓词函数
await page.route(
  (url) => url.pathname.startsWith("/api/") && url.searchParams.has("filter"),
  (route) => route.fulfill({ body: "[]" })
)
```

**相关**：[core/network-mocking.md](network-mocking.md)

---

### "Error: apiRequestContext.get: connect ECONNREFUSED"

**原因**：通过 `request.get()`（或 `.post()`、`.put()` 等）发出的 API 请求无法连接到目标服务器。与 `page.goto: net::ERR_CONNECTION_REFUSED` 的根本原因相同，但针对 API 测试。

**常见触发场景**：

- 使用 `request` fixture 时 API 服务器未运行
- 配置或 API 请求上下文中的 `baseURL` 错误
- 对尚未启动的服务运行 API 测试
- 在 CI 中，API 服务容器尚未就绪

**修复**：确保 API 服务器正在运行。使用 `webServer` 配置自动启动它，或添加健康检查。

```typescript
// TypeScript — playwright.config.ts
import { defineConfig } from "@playwright/test"

export default defineConfig({
  webServer: [
    {
      command: "npm run start:api",
      url: "http://localhost:4000/health",
      reuseExistingServer: !process.env.CI,
    },
    {
      command: "npm run start:web",
      url: "http://localhost:3000",
      reuseExistingServer: !process.env.CI,
    },
  ],
  use: {
    baseURL: "http://localhost:3000",
  },
})

// 在测试中，使用带有显式 baseURL 的 request fixture 进行 API 调用
test("fetch users", async ({ request }) => {
  const response = await request.get("http://localhost:4000/api/users")
  expect(response.ok()).toBeTruthy()
})
```

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

module.exports = defineConfig({
  webServer: [
    {
      command: "npm run start:api",
      url: "http://localhost:4000/health",
      reuseExistingServer: !process.env.CI,
    },
    {
      command: "npm run start:web",
      url: "http://localhost:3000",
      reuseExistingServer: !process.env.CI,
    },
  ],
  use: {
    baseURL: "http://localhost:3000",
  },
})
```

**相关**：[core/api-testing.md](api-testing.md)、[core/configuration.md](configuration.md)

---

### "Request was not handled: GET https://..."

**原因**：使用 `page.route()` 注册了路由处理器并设置了 `{ times: N }`，或者调用了 `page.unrouteAll()`，之后一个匹配该模式的后续请求未被拦截——Playwright 警告你有一个请求未被处理。

**常见触发场景**：

- 使用 `page.route()` 时设置了 `{ times: 1 }`，但应用发出了多次相同请求
- 调用了 `route.fallback()` 或 `route.continue()`，但没有处理器来捕获该请求
- 在测试中途调用了 `page.unrouteAll({ behavior: 'wait' })`，而应用又发出了另一个请求

**修复**：确保你的路由处理器覆盖所有预期的请求，或者让未处理的请求正常通过。

```typescript
// TypeScript

// 不好——只处理第一次请求，第二次请求未处理
await page.route("**/api/data", (route) => route.fulfill({ body: "{}" }), { times: 1 })

// 好——处理所有到此 URL 的请求
await page.route("**/api/data", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ items: [] }),
  })
)

// 好——如果只想拦截一次，后续请求使用 waitForResponse
await page.route("**/api/data", (route) => route.fulfill({ body: '{"items": []}' }), { times: 1 })
// 对于第二次调用，让它去真实服务器（不需要路由）
```

```javascript
// JavaScript

// 好——处理所有到此 URL 的请求
await page.route("**/api/data", (route) =>
  route.fulfill({
    status: 200,
    contentType: "application/json",
    body: JSON.stringify({ items: [] }),
  })
)
```

**相关**：[core/network-mocking.md](network-mocking.md)

---

## 认证与状态错误

---

### "Error: browserContext.storageState: No such file"

**原因**：配置或测试中引用的 `storageState` 路径指向一个不存在的文件。认证状态文件尚未生成。

**常见触发场景**：

- 在运行认证设置项目之前就运行了测试
- `globalSetup` 或认证设置项目未成功完成
- 配置中的文件路径与设置中使用的路径不匹配
- `.gitignore` 排除了 storage state 文件，新克隆后未重新生成
- CI 缓存过期，状态文件未被重新创建

**修复**：确保认证设置先运行，并且文件路径保持一致。

```typescript
// TypeScript — playwright.config.ts
import { defineConfig } from "@playwright/test"

const authFile = "playwright/.auth/user.json"

export default defineConfig({
  projects: [
    // 设置项目先运行，创建认证状态文件
    {
      name: "setup",
      testMatch: /.*\.setup\.ts/,
    },
    {
      name: "chromium",
      use: {
        storageState: authFile,
      },
      dependencies: ["setup"], // 确保 setup 先运行
    },
  ],
})

// auth.setup.ts
import { test as setup, expect } from "@playwright/test"

const authFile = "playwright/.auth/user.json"

setup("authenticate", 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 page.waitForURL("/dashboard")
  // 保存认证后的状态
  await page.context().storageState({ path: authFile })
})
```

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

const authFile = "playwright/.auth/user.json"

module.exports = defineConfig({
  projects: [
    {
      name: "setup",
      testMatch: /.*\.setup\.js/,
    },
    {
      name: "chromium",
      use: {
        storageState: authFile,
      },
      dependencies: ["setup"],
    },
  ],
})

// auth.setup.js
const { test: setup, expect } = require("@playwright/test")

const authFile = "playwright/.auth/user.json"

setup("authenticate", 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 page.waitForURL("/dashboard")
  await page.context().storageState({ path: authFile })
})
```

确保认证目录存在并已添加到 `.gitignore`：

```bash
mkdir -p playwright/.auth
echo "playwright/.auth/" >> .gitignore
```

**相关**：[core/authentication.md](authentication.md)、[core/auth-flows.md](auth-flows.md)

---

### "Error: Target page, context or browser has been closed"

**原因**：代码尝试使用一个已经关闭或销毁的 `page`、`context` 或 `browser` 对象。

**常见触发场景**：

- 在 `page.close()` 被调用后使用了 `page` 引用
- 将 `page` 或 `context` 存储在模块级变量中并在多个测试间重用
- 在异步回调仍在运行时，fixture 拆除了浏览器上下文
- `beforeAll` 创建了一个上下文，但该上下文在所有测试完成使用之前就被关闭了
- 手动使用 `browser.newContext()` 但忘记管理其生命周期

**修复**：绝不要在共享的可变状态中存储 page/context 引用。使用 Playwright fixtures 进行生命周期管理。

```typescript
// TypeScript

// 不好——共享的模块级变量
let sharedPage: Page
test.beforeAll(async ({ browser }) => {
  sharedPage = await browser.newPage()
})
test.afterAll(async () => {
  await sharedPage.close()
})
test("first", async () => {
  await sharedPage.goto("/") // 如果另一个 describe 的 afterAll 先运行，可能会失败
})

// 好——使用内置的 page fixture（每个测试一个，自动管理）
test("first", async ({ page }) => {
  await page.goto("/") // 始终是一个全新的、打开的页面
})

// 好——对于跨测试的共享状态，使用 worker 作用域的 fixture
import { test as base } from "@playwright/test"

export const test = base.extend<{}, { adminContext: BrowserContext }>({
  adminContext: [
    async ({ browser }, use) => {
      const context = await browser.newContext()
      await use(context)
      await context.close()
    },
    { scope: "worker" },
  ],
})
```

```javascript
// JavaScript

// 好——使用内置的 page fixture
test("first", async ({ page }) => {
  await page.goto("/")
})

// 好——对于共享状态，使用 worker 作用域的 fixture
const { test: base } = require("@playwright/test")

const test = base.extend({
  adminContext: [
    async ({ browser }, use) => {
      const context = await browser.newContext()
      await use(context)
      await context.close()
    },
    { scope: "worker" },
  ],
})
```

**相关**：[core/fixtures-and-hooks.md](fixtures-and-hooks.md)

---

## CI 特定错误

---

### "Error: browserType.launch: Browser closed unexpectedly"

**原因**：浏览器进程在启动后立即崩溃，通常是因为 CI 环境中缺少所需的操作系统级依赖。

**常见触发场景**：

- 在最小化 Docker 镜像（如 `node:alpine`）上运行，缺少浏览器依赖
- Linux CI 上缺少共享库（`libgbm`、`libnss3`、`libatk-bridge` 等）
- 共享内存不足（`/dev/shm` 太小）——浏览器使用共享内存进行渲染
- 在 Docker 中以 root 身份运行，没有 `--no-sandbox` 参数（Chromium 拒绝以 root 身份运行沙箱）
- CI 中因内存不足被杀死（浏览器进程被操作系统 OOM 杀死）

**修复**：安装操作系统级依赖并配置环境。

```bash
# 安装浏览器及其操作系统依赖（推荐）
npx playwright install --with-deps chromium

# 如果使用 Docker，使用官方的 Playwright 镜像
# Dockerfile
FROM mcr.microsoft.com/playwright:v1.50.0-noble
WORKDIR /app
COPY . .
RUN npm ci
RUN npx playwright install chromium
CMD ["npx", "playwright", "test"]
```

针对共享内存问题：

```yaml
# GitHub Actions — 增加 /dev/shm
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: mcr.microsoft.com/playwright:v1.50.0-noble
      options: --shm-size=2gb

# Docker run — 增加共享内存
# docker run --shm-size=2gb my-test-image
```

针对在 Docker 中以 root 身份运行：

```typescript
// TypeScript — playwright.config.ts（仅用于 Docker/CI）
export default defineConfig({
  use: {
    launchOptions: {
      args: process.env.CI ? ["--no-sandbox", "--disable-setuid-sandbox"] : [],
    },
  },
})
```

```javascript
// JavaScript — playwright.config.js
module.exports = defineConfig({
  use: {
    launchOptions: {
      args: process.env.CI ? ["--no-sandbox", "--disable-setuid-sandbox"] : [],
    },
  },
})
```

**相关**：[ci/ci-github-actions.md](../ci/ci-github-actions.md)、[ci/docker-and-containers.md](../ci/docker-and-containers.md)

---

### "Error: Playwright Test needs to be invoked via 'npx playwright test'"

**原因**：测试文件是直接通过 `node` 或 `ts-node` 执行的，而不是通过 Playwright 测试运行器。

**常见触发场景**：

- 运行 `node tests/example.spec.ts` 或 `ts-node tests/example.spec.ts`
- 配置错误的 IDE 运行配置直接调用了 `node`
- 使用 Jest 或 Mocha 来运行从 `@playwright/test` 导入的 Playwright 测试文件
- CI 脚本调用了错误的命令

**修复**：始终使用 Playwright CLI 来运行测试。

```bash
# 正确的调用方式
npx playwright test                           # 运行所有测试
npx playwright test tests/login.spec.ts       # 运行特定文件
npx playwright test --grep "login"            # 运行匹配模式的测试
npx playwright test --project=chromium        # 运行特定项目
npx playwright test --debug                   # 使用检查器运行

# 如果使用 package.json 脚本
# package.json
# "scripts": { "test:e2e": "playwright test" }
npm run test:e2e
```

针对 IDE 配置（VS Code）：

```json
// .vscode/settings.json — 安装 Playwright VS Code 扩展而非自定义配置
{
  "playwright.reuseBrowser": true
}
```

**相关**：[core/configuration.md](configuration.md)

---

## 其他常见错误

---

### "Error: page.evaluate: Execution context was destroyed"

**原因**：在 `page.evaluate()` 正在浏览器上下文中执行 JavaScript 时，页面发生了导航或重新加载。

**常见触发场景**：

- 在页面处于导航过程中时调用 `evaluate()`
- 页面上的定时器或事件在评估期间触发了重定向
- 在 `beforeEach` 中运行 `evaluate()`，与 `page.goto()` 产生竞态

**修复**：确保页面在评估前处于稳定状态。

```typescript
// TypeScript

// 不好——evaluate 与导航产生竞态
await page.goto("/dashboard")
const title = await page.evaluate(() => document.title) // 上下文可能已被销毁

// 好——先等待加载状态
await page.goto("/dashboard")
await page.waitForLoadState("domcontentloaded")
const title = await page.evaluate(() => document.title)

// 好——优先使用基于定位器的断言（不需要 evaluate）
await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard")
```

```javascript
// JavaScript

// 好——先等待加载状态
await page.goto("/dashboard")
await page.waitForLoadState("domcontentloaded")
const title = await page.evaluate(() => document.title)

// 好——优先使用基于定位器的断言
await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard")
```

**相关**：[core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "Error: page.screenshot: Cannot take a screenshot larger than..."

**原因**：请求的截图尺寸超过了 Playwright 的限制（通常为 16384x16384 像素）。在对非常长的页面进行全页截图时会发生这种情况。

**常见触发场景**：

- 在无限滚动的页面上调用 `page.screenshot({ fullPage: true })`
- 内容极高的页面（长数据表格、聊天记录）
- CSS 错误导致元素高度巨大

**修复**：将截图裁剪到特定区域或限制视口大小。

```typescript
// TypeScript

// 不好——在很高的页面上可能超出尺寸限制
await page.screenshot({ fullPage: true, path: "full.png" })

// 好——裁剪到特定区域
await page.screenshot({
  path: "clipped.png",
  clip: { x: 0, y: 0, width: 1280, height: 2000 },
})

// 好——改为截取特定元素
await page.getByRole("main").screenshot({ path: "main-content.png" })

// 好——在全页截图前设置合理的视口大小
await page.setViewportSize({ width: 1280, height: 720 })
await page.screenshot({ fullPage: true, path: "full.png" })
```

```javascript
// JavaScript

// 好——裁剪到特定区域
await page.screenshot({
  path: "clipped.png",
  clip: { x: 0, y: 0, width: 1280, height: 2000 },
})

// 好——截取特定元素
await page.getByRole("main").screenshot({ path: "main-content.png" })
```

**相关**：[core/visual-regression.md](visual-regression.md)

---

### "Error: waiting for locator('...').toBeAttached()"

**原因**：元素在断言超时时间内从未进入 DOM。与 `toBeVisible()` 不同，`toBeAttached()` 只检查 DOM 存在性——但该元素根本从未被渲染过。

**常见触发场景**：

- 组件是条件渲染的，但条件未满足
- 提供数据的网络请求尚未完成
- 错误的选择器，不与任何元素匹配
- 元素由延迟加载的代码块渲染，但该代码块尚未下载完成

**修复**：验证元素渲染的先决条件。

```typescript
// TypeScript

// 在断言之前确保数据已加载
await page.goto("/users")
await page.waitForResponse((resp) => resp.url().includes("/api/users"))
await expect(page.getByRole("table")).toBeAttached()

// 对于延迟加载的内容，等待更长时间或触发加载
await page.getByRole("tab", { name: "Advanced" }).click()
await expect(page.getByTestId("advanced-panel")).toBeAttached({ timeout: 10_000 })
```

```javascript
// JavaScript

await page.goto("/users")
await page.waitForResponse((resp) => resp.url().includes("/api/users"))
await expect(page.getByRole("table")).toBeAttached()

await page.getByRole("tab", { name: "Advanced" }).click()
await expect(page.getByTestId("advanced-panel")).toBeAttached({ timeout: 10_000 })
```

**相关**：[core/assertions-and-waiting.md](assertions-and-waiting.md)、[core/locators.md](locators.md)

---

### "Error: protocol error: Target.createTarget: Failed to create target"

**原因**：浏览器无法创建新的标签页或上下文，通常是由于资源耗尽。

**常见触发场景**：

- 打开了太多页面或上下文而没有关闭它们
- 测试中的内存泄漏——每个测试都打开一个上下文但从未关闭
- 在资源受限的 CI 机器上运行大量并行 worker
- 浏览器进程在上一次崩溃后处于不稳定状态

**修复**：降低并行度、关闭未使用的上下文，或使用更少的 worker。

```typescript
// TypeScript — playwright.config.ts

export default defineConfig({
  // 如果资源有限，降低并行度
  workers: process.env.CI ? 2 : undefined,

  // 限制每个 worker 一个浏览器上下文
  fullyParallel: false, // 在 worker 内串行运行测试文件
})
```

```javascript
// JavaScript — playwright.config.js

module.exports = defineConfig({
  workers: process.env.CI ? 2 : undefined,
  fullyParallel: false,
})
```

如果你手动创建上下文，务必关闭它们：

```typescript
// TypeScript
test("multi-user test", async ({ browser }) => {
  const userContext = await browser.newContext()
  const adminContext = await browser.newContext()
  try {
    const userPage = await userContext.newPage()
    const adminPage = await adminContext.newPage()
    // ... 测试逻辑
  } finally {
    await userContext.close()
    await adminContext.close()
  }
})
```

```javascript
// JavaScript
test("multi-user test", async ({ browser }) => {
  const userContext = await browser.newContext()
  const adminContext = await browser.newContext()
  try {
    const userPage = await userContext.newPage()
    const adminPage = await adminContext.newPage()
    // ... 测试逻辑
  } finally {
    await userContext.close()
    await adminContext.close()
  }
})
```

**相关**：[ci/parallel-and-sharding.md](../ci/parallel-and-sharding.md)、[core/multi-user-and-collaboration.md](multi-user-and-collaboration.md)

---

### "Error: expect(locator).toHaveText() — expected string but received array"

**原因**：定位器匹配了多个元素，`toHaveText()` 返回了一个字符串数组而不是单个字符串。

**常见触发场景**：

- 使用了宽泛的定位器如 `page.locator('.item')`，匹配了一个列表
- 期望一个单独的标题，但选择器匹配了多个
- 没有将定位器限定到特定容器

**修复**：要么将定位器缩小到一个元素，要么使用 `toHaveText()` 的数组形式。

```typescript
// TypeScript

// 不好——定位器匹配了多个元素
await expect(page.locator(".item")).toHaveText("First Item")

// 好——缩小到一个元素
await expect(page.locator(".item").first()).toHaveText("First Item")

// 好——在期望多个元素时使用数组断言
await expect(page.locator(".item")).toHaveText(["First Item", "Second Item", "Third Item"])

// 好——使用更具体的定位器
await expect(page.getByRole("heading", { level: 1 })).toHaveText("Welcome")
```

```javascript
// JavaScript

// 好——缩小到一个元素
await expect(page.locator(".item").first()).toHaveText("First Item")

// 好——使用数组断言
await expect(page.locator(".item")).toHaveText(["First Item", "Second Item", "Third Item"])

// 好——使用更具体的定位器
await expect(page.getByRole("heading", { level: 1 })).toHaveText("Welcome")
```

**相关**：[core/assertions-and-waiting.md](assertions-and-waiting.md)、[core/locators.md](locators.md)

---

### "Error: page.waitForSelector: Timeout 30000ms exceeded (deprecated)"

**原因**：`page.waitForSelector()` 超时。此方法已废弃，推荐使用基于定位器的断言。

**常见触发场景**：

- 从旧教程或从 Puppeteer 迁移时使用了旧的 `page.waitForSelector()`
- 选择器不匹配 DOM 中的任何元素
- 元素存在但不符合状态要求（例如 `{ state: 'visible' }` 但元素处于隐藏状态）

**修复**：将 `waitForSelector()` 替换为基于定位器的断言。

```typescript
// TypeScript

// 不好——已废弃、无自动重试、不可组合
await page.waitForSelector(".loading", { state: "hidden" })
await page.waitForSelector(".content", { state: "visible" })

// 好——基于定位器的断言，带自动重试
await expect(page.locator(".loading")).toBeHidden()
await expect(page.locator(".content")).toBeVisible()

// 好——使用基于角色的定位器以获得更强的鲁棒性
await expect(page.getByRole("progressbar")).toBeHidden()
await expect(page.getByRole("main")).toBeVisible()
```

```javascript
// JavaScript

// 不好——已废弃
await page.waitForSelector(".loading", { state: "hidden" })
await page.waitForSelector(".content", { state: "visible" })

// 好——基于定位器的断言
await expect(page.locator(".loading")).toBeHidden()
await expect(page.locator(".content")).toBeVisible()

// 好——基于角色的定位器
await expect(page.getByRole("progressbar")).toBeHidden()
await expect(page.getByRole("main")).toBeVisible()
```

**相关**：[core/locators.md](locators.md)、[core/assertions-and-waiting.md](assertions-and-waiting.md)、[migration/from-selenium.md](../migration/from-selenium.md)

---

### "Error: Test was expected to have a title matching /.../"

**原因**：`expect(page).toHaveTitle()` 断言失败，因为页面标题在超时时间内未匹配期望的值或模式。

**常见触发场景**：

- 页面尚未完成加载，标题仍是初始的空值或默认值
- SPA 在渲染后异步更新文档标题
- 期望的标题有拼写错误或大小写不匹配
- 页面重定向到了具有不同标题的错误页面

**修复**：确保页面已完全加载，并使用正确的期望值。

```typescript
// TypeScript

// toHaveTitle 会自动重试，但要确保页面已加载
await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard | MyApp")

// 使用正则表达式进行灵活匹配
await expect(page).toHaveTitle(/Dashboard/)

// 调试：查看实际标题是什么
console.log(await page.title())
```

```javascript
// JavaScript

await page.goto("/dashboard")
await expect(page).toHaveTitle("Dashboard | MyApp")

// 使用正则表达式进行灵活匹配
await expect(page).toHaveTitle(/Dashboard/)

// 调试：查看实际标题是什么
console.log(await page.title())
```

**相关**：[core/assertions-and-waiting.md](assertions-and-waiting.md)

---

### "Error: page.type: Element is not focusable"

**原因**：`page.type()` 或 `locator.type()` 在输入前无法聚焦目标元素。该元素可能处于隐藏、禁用状态，或者不是一个输入元素。

**常见触发场景**：

- 元素被遮罩层或模态框覆盖
- 元素设置了 `tabindex="-1"`，本身不可聚焦
- 使用了 `type()` 而不是 `fill()`——在几乎所有情况下都应优先使用 `fill()`
- 元素位于 Shadow DOM 内部，定位器无法穿透

**修复**：使用 `fill()` 代替 `type()`。仅在确实需要模拟逐个按键时才使用 `type()`。

```typescript
// TypeScript

// 不好——type() 更慢且更脆弱
await page.locator("#search").type("hello")

// 好——fill() 直接清除并设置值
await page.getByRole("searchbox").fill("hello")

// 当真正需要逐键输入时（例如触发自动补全）
await page.getByRole("searchbox").pressSequentially("hello", { delay: 100 })
```

```javascript
// JavaScript

// 好——fill() 是首选
await page.getByRole("searchbox").fill("hello")

// 需要时逐键输入（例如自动补全）
await page.getByRole("searchbox").pressSequentially("hello", { delay: 100 })
```

**相关**：[core/locators.md](locators.md)、[core/forms-and-validation.md](forms-and-validation.md)

---

### "Error: page.setInputFiles: Non-multiple file input can only accept single file"

**原因**：尝试向没有 `multiple` 属性的 `<input type="file">` 上传多个文件。

**常见触发场景**：

- 向单文件上传输入框传递了一个文件数组
- 应用使用了一个自定义的上传组件，每次只能处理一个文件

**修复**：一次只上传一个文件，或者确保输入框支持多个文件。

```typescript
// TypeScript

// 不好——输入框没有 multiple 属性
await page.getByLabel("Upload file").setInputFiles([
  "file1.pdf",
  "file2.pdf", // 错误：非多文件输入
])

// 好——单个文件
await page.getByLabel("Upload file").setInputFiles("file1.pdf")

// 好——对于多文件输入（HTML 中必须有 multiple 属性）
await page.getByLabel("Upload files").setInputFiles(["file1.pdf", "file2.pdf"])

// 清除文件输入
await page.getByLabel("Upload file").setInputFiles([])
```

```javascript
// JavaScript

// 好——单个文件
await page.getByLabel("Upload file").setInputFiles("file1.pdf")

// 好——多个文件（输入框必须有 multiple 属性）
await page.getByLabel("Upload files").setInputFiles(["file1.pdf", "file2.pdf"])

// 清除文件输入
await page.getByLabel("Upload file").setInputFiles([])
```

**相关**：[core/file-operations.md](file-operations.md)、[core/file-upload-download.md](file-upload-download.md)

---

### "Error: browser.newContext: Could not parse content-type application/json"

**原因**：`storageState` 选项指向了一个包含无效 JSON 内容的文件，或者该文件不是有效的 Playwright storage state 格式。

**常见触发场景**：

- 认证设置写入了一个空文件或不完整的 JSON
- storage state 文件被损坏或截断
- 手动编辑 storage state 文件引入了语法错误
- 认证设置静默失败（登录未完成）并保存了无效状态

**修复**：删除 storage state 文件并重新生成。

```bash
# 删除损坏的文件
rm -f playwright/.auth/user.json

# 重新运行设置
npx playwright test --project=setup
```

为防止此问题，在认证设置中添加错误检查：

```typescript
// TypeScript — auth.setup.ts
import { test as setup, expect } from "@playwright/test"

const authFile = "playwright/.auth/user.json"

setup("authenticate", 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()

  await page.context().storageState({ path: authFile })
})
```

```javascript
// JavaScript — auth.setup.js
const { test: setup, expect } = require("@playwright/test")

const authFile = "playwright/.auth/user.json"

setup("authenticate", 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()

  await page.context().storageState({ path: authFile })
})
```

**相关**：[core/authentication.md](authentication.md)、[core/auth-flows.md](auth-flows.md)

---

## 快速诊断清单

当你遇到上面未列出的错误时，请逐一检查此清单：

1. **阅读完整的错误信息**——Playwright 错误信息包含定位器、操作和页面状态的片段。答案往往就在细节中。
2. **启用 traces**——临时添加 `trace: 'on'` 或在配置中添加 `trace: 'on-first-retry'`。运行 `npx playwright show-trace trace.zip` 查看失败时的截图、DOM、网络和控制台信息。
3. **使用 Playwright Inspector**——运行 `npx playwright test --debug` 以交互方式逐步执行测试。
4. **检查定位器**——运行 `npx playwright codegen <url>` 验证定位器是否与实时页面匹配。
5. **检查 Playwright 版本**——运行 `npx playwright --version`。确保 `@playwright/test` 和浏览器二进制文件版本一致。
6. **搜索 Playwright 问题追踪器**——许多错误在 [github.com/microsoft/playwright/issues](https://github.com/microsoft/playwright/issues) 上有已知的解决方案。