# 错误状态与边界情况

> **使用场景**：测试应用程序如何处理错误、失败、边界条件和异常用户行为。这些测试能捕获快乐路径测试遗漏的缺陷。
> **前置条件**：[core/assertions-and-waiting.md](assertions-and-waiting.md)、[core/network-mocking.md](network-mocking.md)（用于路由拦截）

## 快速参考

```typescript
// 模拟 500 服务器错误
await page.route("**/api/data", (route) => route.fulfill({ status: 500 }))

// 模拟离线模式
await page.context().setOffline(true)

// 测试空状态
await page.route("**/api/items", (route) => route.fulfill({ status: 200, json: [] }))

// 浏览器前进/后退
await page.goBack()
await page.goForward()

// 中止网络请求（模拟网络故障）
await page.route("**/api/save", (route) => route.abort("connectionfailed"))
```

## 模式

### HTTP 错误状态码

**使用场景**：测试应用程序是否为 4xx 和 5xx 响应正确显示错误页面或提示信息。
**避免场景**：错误被静默处理（没有面向用户的反馈）。改为通过 API 或日志测试。

**TypeScript**

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

test("显示 404 页面（资源不存在）", async ({ page }) => {
  // 直接导航到不存在的 URL
  await page.goto("/this-page-does-not-exist")

  await expect(page.getByRole("heading", { name: /not found/i })).toBeVisible()
  await expect(page.getByRole("link", { name: "Go home" })).toBeVisible()
})

test("优雅处理 500 服务器错误", async ({ page }) => {
  // 拦截 API 调用并返回 500
  await page.route("**/api/dashboard", (route) =>
    route.fulfill({
      status: 500,
      contentType: "application/json",
      body: JSON.stringify({ error: "Internal server error" }),
    })
  )

  await page.goto("/dashboard")

  await expect(page.getByText("Something went wrong")).toBeVisible()
  await expect(page.getByRole("button", { name: "Try again" })).toBeVisible()
})

test("处理 403 禁止访问并重定向到登录页", async ({ page }) => {
  await page.route("**/api/admin/**", (route) => route.fulfill({ status: 403 }))

  await page.goto("/admin/settings")

  // 应重定向到登录页或显示拒绝访问
  await expect(page.getByText(/access denied|not authorized/i)).toBeVisible()
})

test("处理 429 请求限流", async ({ page }) => {
  await page.route("**/api/search*", (route) =>
    route.fulfill({
      status: 429,
      headers: { "Retry-After": "30" },
      body: JSON.stringify({ error: "Too many requests" }),
    })
  )

  await page.goto("/search")
  await page.getByLabel("Search").fill("test")
  await page.getByRole("button", { name: "Search" }).click()

  await expect(page.getByText(/too many requests|try again later/i)).toBeVisible()
})
```

**JavaScript**

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

test("显示 404 页面（资源不存在）", async ({ page }) => {
  await page.goto("/this-page-does-not-exist")

  await expect(page.getByRole("heading", { name: /not found/i })).toBeVisible()
  await expect(page.getByRole("link", { name: "Go home" })).toBeVisible()
})

test("优雅处理 500 服务器错误", async ({ page }) => {
  await page.route("**/api/dashboard", (route) =>
    route.fulfill({
      status: 500,
      contentType: "application/json",
      body: JSON.stringify({ error: "Internal server error" }),
    })
  )

  await page.goto("/dashboard")

  await expect(page.getByText("Something went wrong")).toBeVisible()
  await expect(page.getByRole("button", { name: "Try again" })).toBeVisible()
})

test("处理 403 禁止访问并重定向到登录页", async ({ page }) => {
  await page.route("**/api/admin/**", (route) => route.fulfill({ status: 403 }))

  await page.goto("/admin/settings")
  await expect(page.getByText(/access denied|not authorized/i)).toBeVisible()
})

test("处理 429 请求限流", async ({ page }) => {
  await page.route("**/api/search*", (route) =>
    route.fulfill({
      status: 429,
      headers: { "Retry-After": "30" },
      body: JSON.stringify({ error: "Too many requests" }),
    })
  )

  await page.goto("/search")
  await page.getByLabel("Search").fill("test")
  await page.getByRole("button", { name: "Search" }).click()

  await expect(page.getByText(/too many requests|try again later/i)).toBeVisible()
})
```

### 网络故障与离线模式

**使用场景**：测试应用在网络断开、请求失败或连接不稳定时的行为。
**避免场景**：应用没有离线或错误处理行为需要测试。

**TypeScript**

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

test("离线模式显示离线横幅", async ({ page }) => {
  await page.goto("/dashboard")
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  // 切换为离线
  await page.context().setOffline(true)

  // 触发一个依赖网络的操作
  await page.getByRole("button", { name: "Refresh" }).click()

  await expect(page.getByText(/offline|no connection/i)).toBeVisible()

  // 恢复在线
  await page.context().setOffline(false)

  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByText(/offline|no connection/i)).not.toBeVisible()
})

test("网络请求失败显示错误状态", async ({ page }) => {
  // 中止特定请求以模拟网络故障
  await page.route("**/api/user/profile", (route) => route.abort("connectionfailed"))

  await page.goto("/profile")

  await expect(page.getByText("Failed to load profile")).toBeVisible()
  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible()
})

test("请求超时显示超时消息", async ({ page }) => {
  // 延迟响应，超过应用的超时阈值
  await page.route("**/api/reports", async (route) => {
    await new Promise((resolve) => setTimeout(resolve, 30_000))
    await route.fulfill({ status: 200, json: { data: [] } })
  })

  await page.goto("/reports")

  // 应用应在 Playwright 自身超时之前显示超时消息
  await expect(page.getByText(/timed out|taking too long/i)).toBeVisible({
    timeout: 20_000,
  })
})

test("间歇性连接——请求先失败后成功", async ({ page }) => {
  let requestCount = 0

  await page.route("**/api/data", (route) => {
    requestCount++
    if (requestCount <= 2) {
      return route.abort("connectionfailed")
    }
    return route.fulfill({ status: 200, json: { items: ["a", "b", "c"] } })
  })

  await page.goto("/data")

  // 首次加载失败
  await expect(page.getByText(/failed|error/i)).toBeVisible()

  // 用户重试——仍然失败
  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByText(/failed|error/i)).toBeVisible()

  // 第三次尝试成功
  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByRole("listitem")).toHaveCount(3)
})
```

**JavaScript**

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

test("离线模式显示离线横幅", async ({ page }) => {
  await page.goto("/dashboard")
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  await page.context().setOffline(true)

  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByText(/offline|no connection/i)).toBeVisible()

  await page.context().setOffline(false)

  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByText(/offline|no connection/i)).not.toBeVisible()
})

test("网络请求失败显示错误状态", async ({ page }) => {
  await page.route("**/api/user/profile", (route) => route.abort("connectionfailed"))

  await page.goto("/profile")

  await expect(page.getByText("Failed to load profile")).toBeVisible()
  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible()
})

test("间歇性连接——请求先失败后成功", async ({ page }) => {
  let requestCount = 0

  await page.route("**/api/data", (route) => {
    requestCount++
    if (requestCount <= 2) {
      return route.abort("connectionfailed")
    }
    return route.fulfill({ status: 200, json: { items: ["a", "b", "c"] } })
  })

  await page.goto("/data")

  await expect(page.getByText(/failed|error/i)).toBeVisible()

  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByText(/failed|error/i)).toBeVisible()

  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByRole("listitem")).toHaveCount(3)
})
```

### 空状态与边界测试

**使用场景**：测试 UI 在无数据、输入为最小值或最大值、或输入包含特殊字符时的显示情况。
**避免场景**：永远不需要避免。每个功能都应有空状态和边界测试。

**TypeScript**

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

test("无项目时显示空状态", async ({ page }) => {
  // 模拟空响应
  await page.route("**/api/tasks", (route) => route.fulfill({ status: 200, json: [] }))

  await page.goto("/tasks")

  await expect(page.getByText("No tasks yet")).toBeVisible()
  await expect(page.getByRole("link", { name: "Create your first task" })).toBeVisible()

  // 列表元素不应存在
  await expect(page.getByRole("listitem")).toHaveCount(0)
})

test("处理最大长度输入", async ({ page }) => {
  await page.goto("/profile")

  // 使用最大长度字符串填充
  const maxLengthName = "A".repeat(255)
  await page.getByLabel("Display name").fill(maxLengthName)
  await page.getByRole("button", { name: "Save" }).click()

  // 验证名称已保存（或已截断，取决于应用行为）
  await expect(page.getByText("Profile updated")).toBeVisible()
})

test("处理输入中的特殊字符", async ({ page }) => {
  await page.goto("/search")

  const specialInputs = [
    '<script>alert("xss")</script>',
    '"; DROP TABLE users; --',
    "unicode: \u00e9\u00e0\u00fc\u00f1 \u4f60\u597d \ud83d\ude80",
    "null bytes: \x00\x01\x02",
    "path traversal: ../../etc/passwd",
  ]

  for (const input of specialInputs) {
    await page.getByLabel("Search").fill(input)
    await page.getByRole("button", { name: "Search" }).click()

    // 应用不应崩溃——要么显示结果，要么显示"无结果"
    await expect(page.getByText(/results|no results|no matches/i)).toBeVisible()
  }
})

test("处理零个、一个和多个项目（0-1-N 模式）", async ({ page }) => {
  // 零个项目
  await page.route("**/api/notifications", (route) => route.fulfill({ status: 200, json: [] }))
  await page.goto("/notifications")
  await expect(page.getByText("No notifications")).toBeVisible()

  // 一个项目
  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: [{ id: 1, message: "Welcome!" }],
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem")).toHaveCount(1)
  await expect(page.getByText("No notifications")).not.toBeVisible()

  // 多个项目——验证分页或"加载更多"
  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: Array.from({ length: 50 }, (_, i) => ({
        id: i + 1,
        message: `Notification ${i + 1}`,
      })),
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem").first()).toBeVisible()
  await expect(page.getByRole("button", { name: /load more|show all/i })).toBeVisible()
})
```

**JavaScript**

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

test("无项目时显示空状态", async ({ page }) => {
  await page.route("**/api/tasks", (route) => route.fulfill({ status: 200, json: [] }))

  await page.goto("/tasks")

  await expect(page.getByText("No tasks yet")).toBeVisible()
  await expect(page.getByRole("link", { name: "Create your first task" })).toBeVisible()
  await expect(page.getByRole("listitem")).toHaveCount(0)
})

test("处理最大长度输入", async ({ page }) => {
  await page.goto("/profile")

  const maxLengthName = "A".repeat(255)
  await page.getByLabel("Display name").fill(maxLengthName)
  await page.getByRole("button", { name: "Save" }).click()

  await expect(page.getByText("Profile updated")).toBeVisible()
})

test("处理输入中的特殊字符", async ({ page }) => {
  await page.goto("/search")

  const specialInputs = [
    '<script>alert("xss")</script>',
    '"; DROP TABLE users; --',
    "unicode: \u00e9\u00e0\u00fc\u00f1 \u4f60\u597d \ud83d\ude80",
    "path traversal: ../../etc/passwd",
  ]

  for (const input of specialInputs) {
    await page.getByLabel("Search").fill(input)
    await page.getByRole("button", { name: "Search" }).click()

    await expect(page.getByText(/results|no results|no matches/i)).toBeVisible()
  }
})

test("处理零个、一个和多个项目（0-1-N 模式）", async ({ page }) => {
  await page.route("**/api/notifications", (route) => route.fulfill({ status: 200, json: [] }))
  await page.goto("/notifications")
  await expect(page.getByText("No notifications")).toBeVisible()

  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: [{ id: 1, message: "Welcome!" }],
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem")).toHaveCount(1)

  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: Array.from({ length: 50 }, (_, i) => ({
        id: i + 1,
        message: `Notification ${i + 1}`,
      })),
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem").first()).toBeVisible()
  await expect(page.getByRole("button", { name: /load more|show all/i })).toBeVisible()
})
```

### 加载状态与骨架屏

**使用场景**：验证加载指示器、骨架屏或加载动画在数据获取期间出现，并在数据到达后消失。
**避免场景**：应用同步渲染，没有加载指示器（无客户端数据请求的 SSR）。

**TypeScript**

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

test("骨架屏出现并解析完成", async ({ page }) => {
  // 延迟 API 响应以观察加载状态
  let resolveResponse: () => void
  const responseReady = new Promise<void>((resolve) => {
    resolveResponse = resolve
  })

  await page.route("**/api/dashboard", async (route) => {
    await responseReady
    await route.fulfill({
      status: 200,
      json: { revenue: 12400, users: 350 },
    })
  })

  await page.goto("/dashboard")

  // 加载时骨架屏应可见
  await expect(page.getByTestId("skeleton-revenue")).toBeVisible()
  await expect(page.getByTestId("skeleton-users")).toBeVisible()

  // 真实内容此时应不可见
  await expect(page.getByText("$12,400")).not.toBeVisible()

  // 释放响应
  resolveResponse!()

  // 骨架屏消失，真实内容出现
  await expect(page.getByTestId("skeleton-revenue")).not.toBeVisible()
  await expect(page.getByText("$12,400")).toBeVisible()
  await expect(page.getByText("350")).toBeVisible()
})

test("表单提交时显示加载动画", async ({ page }) => {
  let resolveSubmit: () => void
  const submitReady = new Promise<void>((resolve) => {
    resolveSubmit = resolve
  })

  await page.route("**/api/contact", async (route) => {
    await submitReady
    await route.fulfill({ status: 200, json: { success: true } })
  })

  await page.goto("/contact")
  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")

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

  // 提交期间的加载动画/状态
  await expect(page.getByRole("button", { name: /sending/i })).toBeVisible()
  await expect(page.getByRole("button", { name: /sending/i })).toBeDisabled()

  // 完成提交
  resolveSubmit!()

  await expect(page.getByText("Message sent")).toBeVisible()
})
```

**JavaScript**

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

test("骨架屏出现并解析完成", async ({ page }) => {
  let resolveResponse
  const responseReady = new Promise((resolve) => {
    resolveResponse = resolve
  })

  await page.route("**/api/dashboard", async (route) => {
    await responseReady
    await route.fulfill({
      status: 200,
      json: { revenue: 12400, users: 350 },
    })
  })

  await page.goto("/dashboard")

  await expect(page.getByTestId("skeleton-revenue")).toBeVisible()
  await expect(page.getByTestId("skeleton-users")).toBeVisible()
  await expect(page.getByText("$12,400")).not.toBeVisible()

  resolveResponse()

  await expect(page.getByTestId("skeleton-revenue")).not.toBeVisible()
  await expect(page.getByText("$12,400")).toBeVisible()
  await expect(page.getByText("350")).toBeVisible()
})

test("表单提交时显示加载动画", async ({ page }) => {
  let resolveSubmit
  const submitReady = new Promise((resolve) => {
    resolveSubmit = resolve
  })

  await page.route("**/api/contact", async (route) => {
    await submitReady
    await route.fulfill({ status: 200, json: { success: true } })
  })

  await page.goto("/contact")
  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")

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

  await expect(page.getByRole("button", { name: /sending/i })).toBeVisible()
  await expect(page.getByRole("button", { name: /sending/i })).toBeDisabled()

  resolveSubmit()

  await expect(page.getByText("Message sent")).toBeVisible()
})
```

### 重试行为测试

**使用场景**：测试应用是否自动重试失败的请求，或是否通过用户触发的"重试"按钮进行重试。
**避免场景**：应用没有重试机制。

**TypeScript**

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

test("重试按钮从失败的 API 调用中恢复", async ({ page }) => {
  let callCount = 0

  await page.route("**/api/feed", (route) => {
    callCount++
    if (callCount === 1) {
      return route.fulfill({ status: 500 })
    }
    return route.fulfill({
      status: 200,
      json: { posts: [{ id: 1, title: "Hello World" }] },
    })
  })

  await page.goto("/feed")

  // 首次加载失败
  await expect(page.getByText(/something went wrong/i)).toBeVisible()

  // 点击重试——第二次调用成功
  await page.getByRole("button", { name: "Try again" }).click()

  await expect(page.getByText("Hello World")).toBeVisible()
  expect(callCount).toBe(2)
})

test("带指数退避的自动重试", async ({ page }) => {
  const callTimestamps: number[] = []

  await page.route("**/api/status", (route) => {
    callTimestamps.push(Date.now())
    if (callTimestamps.length <= 3) {
      return route.fulfill({ status: 503 })
    }
    return route.fulfill({ status: 200, json: { status: "ok" } })
  })

  await page.goto("/status")

  // 等待自动重试最终成功
  await expect(page.getByText("System operational")).toBeVisible({
    timeout: 30_000,
  })

  // 验证进行了多次重试尝试
  expect(callTimestamps.length).toBeGreaterThanOrEqual(4)

  // 验证退避：重试间隔应递增
  if (callTimestamps.length >= 3) {
    const gap1 = callTimestamps[1] - callTimestamps[0]
    const gap2 = callTimestamps[2] - callTimestamps[1]
    expect(gap2).toBeGreaterThanOrEqual(gap1)
  }
})
```

**JavaScript**

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

test("重试按钮从失败的 API 调用中恢复", async ({ page }) => {
  let callCount = 0

  await page.route("**/api/feed", (route) => {
    callCount++
    if (callCount === 1) {
      return route.fulfill({ status: 500 })
    }
    return route.fulfill({
      status: 200,
      json: { posts: [{ id: 1, title: "Hello World" }] },
    })
  })

  await page.goto("/feed")

  await expect(page.getByText(/something went wrong/i)).toBeVisible()

  await page.getByRole("button", { name: "Try again" }).click()

  await expect(page.getByText("Hello World")).toBeVisible()
  expect(callCount).toBe(2)
})

test("带指数退避的自动重试", async ({ page }) => {
  const callTimestamps = []

  await page.route("**/api/status", (route) => {
    callTimestamps.push(Date.now())
    if (callTimestamps.length <= 3) {
      return route.fulfill({ status: 503 })
    }
    return route.fulfill({ status: 200, json: { status: "ok" } })
  })

  await page.goto("/status")

  await expect(page.getByText("System operational")).toBeVisible({
    timeout: 30_000,
  })

  expect(callTimestamps.length).toBeGreaterThanOrEqual(4)
})
```

### 浏览器前进/后退导航

**使用场景**：测试应用程序是否正确处理浏览器历史导航——后退或前进后保持状态、URL 更新和内容。
**避免场景**：应用是单页应用且不使用浏览器历史 API。应专注于客户端路由测试。

**TypeScript**

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

test("浏览器后退保留导航上下文", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  // 后退
  await page.goBack()

  await expect(page).toHaveURL(/\/products$/)
  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
})

test("浏览器前进返回到上一页", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  await page.goBack()
  await page.goForward()

  await expect(page).toHaveURL(/\/products\/running-shoes/)
  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
})

test("浏览器后退后的表单状态", async ({ page }) => {
  await page.goto("/checkout")

  // 填写步骤 1 的表单
  await page.getByLabel("Address").fill("123 Main St")
  await page.getByRole("button", { name: "Continue" }).click()

  // 到达步骤 2
  await expect(page.getByRole("heading", { name: "Payment" })).toBeVisible()

  // 后退到步骤 1
  await page.goBack()

  // 数据应保留（取决于应用实现）
  await expect(page.getByLabel("Address")).toHaveValue("123 Main St")
})

test("表单提交后点击后退按钮不会重新提交", async ({ page }) => {
  await page.goto("/contact")

  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")
  await page.getByRole("button", { name: "Send" }).click()

  await expect(page.getByText("Message sent")).toBeVisible()

  // 后退应显示表单，而不是重新提交
  await page.goBack()
  await expect(page.getByLabel("Name")).toBeVisible()
})
```

**JavaScript**

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

test("浏览器后退保留导航上下文", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  await page.goBack()

  await expect(page).toHaveURL(/\/products$/)
  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
})

test("浏览器前进返回到上一页", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  await page.goBack()
  await page.goForward()

  await expect(page).toHaveURL(/\/products\/running-shoes/)
  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
})

test("浏览器后退后的表单状态", async ({ page }) => {
  await page.goto("/checkout")

  await page.getByLabel("Address").fill("123 Main St")
  await page.getByRole("button", { name: "Continue" }).click()

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

  await page.goBack()
  await expect(page.getByLabel("Address")).toHaveValue("123 Main St")
})

test("表单提交后点击后退按钮不会重新提交", async ({ page }) => {
  await page.goto("/contact")

  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")
  await page.getByRole("button", { name: "Send" }).click()

  await expect(page.getByText("Message sent")).toBeVisible()

  await page.goBack()
  await expect(page.getByLabel("Name")).toBeVisible()
})
```

### 并发用户操作

**使用场景**：测试快速用户交互是否导致竞态条件——双击提交、数据加载时打字、异步操作期间导航。
**避免场景**：UI 没有可能与用户操作冲突的异步操作。

**TypeScript**

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

test("双击提交不会创建重复条目", async ({ page }) => {
  const requests: string[] = []

  await page.route("**/api/orders", (route) => {
    requests.push(route.request().method())
    return route.fulfill({
      status: 201,
      json: { id: 1, status: "created" },
    })
  })

  await page.goto("/checkout")
  await page.getByLabel("Item").fill("Widget")

  const submitButton = page.getByRole("button", { name: "Place order" })

  // 快速双击
  await submitButton.dblclick()

  // 等待结果
  await expect(page.getByText("Order confirmed")).toBeVisible()

  // 应用应阻止重复提交
  //（第一次点击后按钮禁用，或服务端去重）
  expect(requests.filter((m) => m === "POST").length).toBeLessThanOrEqual(1)
})

test("导航期间打字不会崩溃", async ({ page }) => {
  await page.goto("/search")

  // 开始打字并立即导航
  await page.getByLabel("Search").pressSequentially("test query", { delay: 30 })
  await page.getByRole("link", { name: "Home" }).click()

  // 应无错误地到达首页
  await page.waitForURL("**/")
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
})

test("快速筛选变更使用最新值", async ({ page }) => {
  const requestUrls: string[] = []

  await page.route("**/api/products*", (route) => {
    requestUrls.push(route.request().url())
    return route.fulfill({
      status: 200,
      json: { products: [{ name: "Latest result" }] },
    })
  })

  await page.goto("/products")

  // 快速切换筛选条件
  await page.getByLabel("Category").selectOption("electronics")
  await page.getByLabel("Category").selectOption("clothing")
  await page.getByLabel("Category").selectOption("books")

  // 等待最终结果
  await expect(page.getByText("Latest result")).toBeVisible()

  // UI 应显示"books"的结果，而不是之前的选项
  // 某些应用会防抖；某些会取消正在进行的请求
})
```

**JavaScript**

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

test("双击提交不会创建重复条目", async ({ page }) => {
  const requests = []

  await page.route("**/api/orders", (route) => {
    requests.push(route.request().method())
    return route.fulfill({
      status: 201,
      json: { id: 1, status: "created" },
    })
  })

  await page.goto("/checkout")
  await page.getByLabel("Item").fill("Widget")

  const submitButton = page.getByRole("button", { name: "Place order" })
  await submitButton.dblclick()

  await expect(page.getByText("Order confirmed")).toBeVisible()

  expect(requests.filter((m) => m === "POST").length).toBeLessThanOrEqual(1)
})

test("导航期间打字不会崩溃", async ({ page }) => {
  await page.goto("/search")

  await page.getByLabel("Search").pressSequentially("test query", { delay: 30 })
  await page.getByRole("link", { name: "Home" }).click()

  await page.waitForURL("**/")
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
})

test("快速筛选变更使用最新值", async ({ page }) => {
  const requestUrls = []

  await page.route("**/api/products*", (route) => {
    requestUrls.push(route.request().url())
    return route.fulfill({
      status: 200,
      json: { products: [{ name: "Latest result" }] },
    })
  })

  await page.goto("/products")

  await page.getByLabel("Category").selectOption("electronics")
  await page.getByLabel("Category").selectOption("clothing")
  await page.getByLabel("Category").selectOption("books")

  await expect(page.getByText("Latest result")).toBeVisible()
})
```

### 优雅降级

**使用场景**：测试非关键服务（分析、聊天组件、推荐）失败时应用是否仍能正常运行。
**避免场景**：失败的服务对核心工作流程至关重要。

**TypeScript**

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

test("分析服务失败时页面仍正常工作", async ({ page }) => {
  // 拦截分析和跟踪脚本
  await page.route("**/analytics/**", (route) => route.abort())
  await page.route("**/tracking/**", (route) => route.abort())

  await page.goto("/products")

  // 核心功能仍然可用
  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()
})

test("推荐引擎失败时页面仍正常工作", async ({ page }) => {
  await page.route("**/api/recommendations", (route) => route.fulfill({ status: 500 }))

  await page.goto("/products/running-shoes")

  // 主要产品内容加载
  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()

  // 推荐区域显示后备内容
  await expect(page.getByText(/recommendations unavailable|you may also like/i)).toBeVisible()
})

test("第三方聊天组件加载失败时页面仍正常工作", async ({ page }) => {
  // 拦截聊天组件脚本
  await page.route("**/chat-widget.js", (route) => route.abort())

  await page.goto("/support")

  // 核心支持页面加载
  await expect(page.getByRole("heading", { name: "Help Center" })).toBeVisible()

  // 被拦截组件不应导致页面崩溃
  const errors: string[] = []
  page.on("pageerror", (error) => errors.push(error.message))

  // 导航以确认没有级联故障
  await page.getByRole("link", { name: "FAQ" }).click()
  await expect(page.getByRole("heading", { name: "FAQ" })).toBeVisible()
})
```

**JavaScript**

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

test("分析服务失败时页面仍正常工作", async ({ page }) => {
  await page.route("**/analytics/**", (route) => route.abort())
  await page.route("**/tracking/**", (route) => route.abort())

  await page.goto("/products")

  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()
})

test("推荐引擎失败时页面仍正常工作", async ({ page }) => {
  await page.route("**/api/recommendations", (route) => route.fulfill({ status: 500 }))

  await page.goto("/products/running-shoes")

  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()
})

test("第三方聊天组件加载失败时页面仍正常工作", async ({ page }) => {
  await page.route("**/chat-widget.js", (route) => route.abort())

  await page.goto("/support")

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

  await page.getByRole("link", { name: "FAQ" }).click()
  await expect(page.getByRole("heading", { name: "FAQ" })).toBeVisible()
})
```

## 决策指南

| 场景                     | 方法                                                           | 关键 API                                                         |
| ------------------------ | -------------------------------------------------------------- | --------------------------------------------------------------- |
| 404 页面                 | 导航到不存在的 URL，断言错误页面                                | `page.goto('/nonexistent')`                                     |
| 500 服务器错误           | 使用 `status: 500` 模拟路由                                    | `page.route(url, route => route.fulfill({ status: 500 }))`      |
| 网络故障                 | 中止路由                                                       | `route.abort('connectionfailed')`                               |
| 离线模式                 | 在浏览器上下文中切换离线状态                                     | `page.context().setOffline(true)`                               |
| 慢响应                   | 使用 Promise 延迟路由完成                                       | 路由处理器中的 `await new Promise(r => setTimeout(r, delay))` |
| 空状态                   | 模拟 API 返回空数组                                             | `route.fulfill({ json: [] })`                                   |
| 边界值                   | 用最小/最大/特殊值填充输入                                      | `locator.fill('A'.repeat(255))`                                 |
| 骨架屏                   | 延迟路由，断言骨架屏可见，释放响应，断言内容                      | 基于 Promise 的路由处理器                                        |
| 重试行为                 | 跟踪路由调用次数，前 N 次失败，之后成功                          | 路由处理器中的计数器                                              |
| 浏览器历史               | 使用 `page.goBack()` 和 `page.goForward()`                     | 导航后断言 URL 和内容                                             |
| 双击提交                 | 在提交按钮上 `dblclick()`，验证单个 POST 请求                   | 在路由处理器中跟踪请求                                             |
| 第三方服务失败           | 中止非关键路由，验证核心功能正常                                  | 对可选服务使用 `route.abort()`                                    |
| 控制台错误监控           | 监听 `pageerror` 事件                                          | `page.on('pageerror', handler)`                                 |

## 反模式

| 不要这样做                                                 | 问题                                                                           | 应该这样做                                                                   |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| 只测试快乐路径                                             | 真实用户会遇到错误。生产环境中的错误比测试时间更昂贵。                            | 为每个功能添加错误/边界情况测试                                                |
| `page.route('**/*', route => route.abort())`               | 会拦截所有请求，包括页面本身                                                    | 指定目标 URL：`page.route('**/api/specific', ...)`                           |
| 使用 `page.waitForTimeout()` 模拟慢加载                     | 随意性、不稳定、拖慢测试速度                                                     | 使用基于 Promise 的路由处理器精确控制时序                                     |
| 在断言中硬编码错误消息                                     | 消息会变更。测试因文案修改而失败。                                                | 使用正则或部分匹配：`getByText(/error/i)`                                    |
| 在一个巨型测试中测试所有错误码                              | 难以调试、速度慢，第一个失败会掩盖后续问题                                        | 每个错误场景一个测试，或使用 `test.describe` 分组                             |
| 跳过空状态测试                                             | 空状态是新用户最先看到的内容；往往最容易出问题                                     | 始终在测试 0 项状态的同时测试 1 项和 N 项                                     |
| 通过断开真实网络来测试离线                                  | 不稳定、影响并行测试、CI 可能不支持                                               | 使用 `context.setOffline(true)`——确定性强且作用域隔离                         |
| 测试间未清理路由模拟                                        | 路由在页面上持续存在。测试 B 继承了测试 A 的模拟。                                 | 每个测试设置自己的路由；Playwright 默认在测试间重置                            |
| 对来自服务器的精确错误字符串进行断言                          | 将测试与后端实现细节耦合                                                        | 断言 UI 消息，而非原始 API 响应体                                              |
| 使用 `try/catch` 来"处理"预期错误                            | 吞掉真正的缺陷；测试本应失败时却通过                                              | 让错误自然传播；使用路由模拟来控制响应                                          |

## 故障排除

### 路由处理器未拦截请求

**原因**：URL 模式不匹配，或路由在触发请求的导航之后才注册。

```typescript
// 始终在导航之前注册路由
await page.route("**/api/data", (route) => route.fulfill({ status: 500 }))
await page.goto("/dashboard") // 页面加载前路由已激活

// 调试：记录所有请求以查找实际 URL 模式
page.on("request", (req) => console.log(req.url()))
```

### `context.setOffline(true)` 不影响 Service Worker

**原因**：Service Worker 有自己的网络处理机制。`setOffline` 在浏览器层面模拟离线，但 Service Worker 可能提供缓存响应。

```typescript
// 先注销 service worker
await page.evaluate(async () => {
  const registrations = await navigator.serviceWorker.getRegistrations()
  for (const registration of registrations) {
    await registration.unregister()
  }
})
await page.context().setOffline(true)
```

### 延迟的路由处理器导致测试超时

**原因**：路由处理器中的 Promise 从未解析，或延迟超过了测试超时时间。

```typescript
// 始终确保延迟小于断言超时时间
await page.route("**/api/slow", async (route) => {
  await new Promise((resolve) => setTimeout(resolve, 5_000)) // 5 秒延迟
  await route.fulfill({ status: 200, json: {} })
})

// 增大断言超时时间以容纳人为延迟
await expect(page.getByText("Data loaded")).toBeVisible({ timeout: 10_000 })
```

### `goBack()` 未导航

**原因**：没有历史记录可返回。`goBack()` 需要至少一次先前的导航。

```typescript
// 确保在调用 goBack 之前有历史记录
await page.goto("/page-a")
await page.goto("/page-b")
await page.goBack() // 返回到 /page-a

// 如果使用 SPA 客户端路由，goBack 可能无法工作（如果路由器未推送到浏览器历史）
// 改为使用应用自身的后退按钮
await page.getByRole("button", { name: "Back" }).click()
```

## 相关文档

- [core/assertions-and-waiting.md](assertions-and-waiting.md) —— 错误状态的断言策略
- [core/network-mocking.md](network-mocking.md) —— 详细的网络拦截与模拟模式
- [core/forms-and-validation.md](forms-and-validation.md) —— 表单验证错误测试
- [core/flaky-tests.md](flaky-tests.md) —— 修复错误/边界情况测试中的时序问题
- [core/service-workers-and-pwa.md](service-workers-and-pwa.md) —— 离线优先和 PWA 测试模式
- [core/multi-context-and-popups.md](multi-context-and-popups.md) —— 测试并发浏览器上下文