> > 译文开始。

# 不稳定测试

> **使用时机**：测试有时通过、有时失败，需要诊断根本原因、修复并防止再次发生。
> **前置知识**：[core/assertions-and-waiting.md](assertions-and-waiting.md)、[core/fixtures-and-hooks.md](fixtures-and-hooks.md)

## 快速参考

```bash
# 压力测试——运行 10 次以暴露不稳定性
npx playwright test tests/checkout.spec.ts --repeat-each=10

# 带重试运行以捕获间歇性失败
npx playwright test --retries=3

# 隔离运行单个测试以排除状态泄漏
npx playwright test tests/checkout.spec.ts --grep "adds item" --workers=1

# 每次尝试均开启跟踪以进行对比
npx playwright test --retries=3 --trace=on

# 全并行模式运行以暴露隔离问题
npx playwright test --fully-parallel --workers=4

# 列出不稳定测试（先失败后通过重试的测试）
npx playwright test --retries=2 --reporter=json | jq '.suites[].specs[] | select(.ok == true and (.tests[].results | length > 1))'
```

## 模式

### 不稳定性分类

每个不稳定测试都属于以下四类之一。先识别类别，再应用相应的修复方案。

| 类别 | 症状 | 典型根本原因 | 诊断方法 |
| ------------------ | -------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **时序/异步** | 在任何环境下间歇性失败 | 竞态条件、缺少 `await`、随意等待 | 本地使用 `--repeat-each=20` 会失败 |
| **测试隔离** | 仅与其他测试一起运行时失败，单独运行通过 | 共享可变状态、数据冲突、测试顺序依赖 | 使用 `--workers=1 --grep "this test"` 通过，在完整套件中失败 |
| **环境** | 仅在 CI 中失败，本地通过 | 不同的操作系统、视口、字体、网络延迟、缺少依赖 | 对比 CI 截图/跟踪与本地结果；在本地 Docker 中运行 |
| **基础设施** | 与测试逻辑无关的随机失败 | 浏览器崩溃、OOM、DNS 解析、文件系统竞态 | 失败无规律；错误信息涉及浏览器内部机制 |

### 诊断流程图

按此决策树识别你的不稳定测试属于哪一类别。

```
测试不稳定
|
+-- 本地使用 --repeat-each=20 会失败吗？
|   |
|   +-- 是 --> 时序/异步问题
|   |           - 缺少 await
|   |           - 使用 waitForTimeout 而非断言
|   |           - 操作与断言之间的竞态条件
|   |           - 断言前未等待网络响应
|   |
|   +-- 否 --> 仅在 CI 中失败吗？
|       |
|       +-- 是 --> 环境问题
|       |           - 不同的视口/屏幕尺寸
|       |           - 缺少字体导致布局偏移
|       |           - CI 机器较慢导致超时
|       |           - 外部服务不可用
|       |
|       +-- 否 --> 仅与其他测试一起运行时失败吗？
|           |
|           +-- 是 --> 隔离问题
|           |           - 共享可变状态（模块级变量）
|           |           - 前一个测试留下的数据库/API 状态
|           |           - localStorage/cookies 在测试之间泄漏
|           |           - 并行测试在唯一约束上冲突
|           |
|           +-- 否 --> 基础设施问题
|                       - 浏览器进程崩溃
|                       - 内存不足
|                       - 文件系统或网络不稳定
|                       - 不稳定的第三方服务
```

### 修复：时序和异步问题

**使用时机**：本地使用 `--repeat-each=20` 会失败，或者出现 `waitForTimeout`、缺少 `await` 或竞态条件。

最常导致不稳定的根源。修复方法始终相同：用 Playwright 的自动重试机制替换随意等待和手动检查。

**TypeScript**

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

// ---- 修复 1：用断言替换 waitForTimeout ----

// 不好——随意延迟，在慢机器上失败，在快机器上浪费时间
test("bad: uses arbitrary wait", async ({ page }) => {
  await page.goto("/dashboard")
  await page.getByRole("button", { name: "Refresh" }).click()
  await page.waitForTimeout(3000) // 希望数据在 3 秒内加载完成
  await expect(page.getByTestId("data-table")).toBeVisible()
})

// 好——自动重试断言等待恰好所需的时间
test("good: uses auto-retrying assertion", async ({ page }) => {
  await page.goto("/dashboard")
  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByTestId("data-table")).toBeVisible()
})

// ---- 修复 2：断言前等待网络响应 ----

// 不好——点击按钮后立即断言，但数据来自 API
test("bad: does not wait for API response", async ({ page }) => {
  await page.goto("/users")
  await page.getByRole("button", { name: "Load More" }).click()
  // 不稳定：API 响应可能尚未到达
  await expect(page.getByRole("listitem")).toHaveCount(20)
})

// 好——等待填充数据的特定 API 响应
test("good: waits for API response", async ({ page }) => {
  await page.goto("/users")

  const responsePromise = page.waitForResponse(
    (resp) => resp.url().includes("/api/users") && resp.status() === 200
  )
  await page.getByRole("button", { name: "Load More" }).click()
  await responsePromise

  await expect(page.getByRole("listitem")).toHaveCount(20)
})

// ---- 修复 3：处理动画和过渡 ----

// 不好——元素存在但正在动画中，点击落在错误目标上
test("bad: clicks during animation", async ({ page }) => {
  await page.goto("/modal-demo")
  await page.getByRole("button", { name: "Open" }).click()
  // 模态框正在动画进入——点击可能错过其中的按钮
  await page.getByRole("button", { name: "Confirm" }).click()
})

// 好——等待模态框完全稳定后再交互
test("good: waits for stable state", async ({ page }) => {
  await page.goto("/modal-demo")
  await page.getByRole("button", { name: "Open" }).click()
  // toBeVisible 自动等待稳定性（无动画进行中）
  await expect(page.getByRole("dialog")).toBeVisible()
  await page.getByRole("button", { name: "Confirm" }).click()
})

// ---- 修复 4：对必须整体成功的多步骤断言使用 toPass() ----

test("good: retry entire assertion block", async ({ page }) => {
  await page.goto("/search")

  await expect(async () => {
    await page.getByLabel("Search").fill("playwright")
    await page.getByRole("button", { name: "Search" }).click()
    await expect(page.getByTestId("result-count")).toHaveText("10 results")
  }).toPass({
    timeout: 15_000,
    intervals: [1_000, 2_000, 5_000],
  })
})
```

**JavaScript**

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

// 修复 1：用断言替换 waitForTimeout
test("good: uses auto-retrying assertion", async ({ page }) => {
  await page.goto("/dashboard")
  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByTestId("data-table")).toBeVisible()
})

// 修复 2：断言前等待网络响应
test("good: waits for API response", async ({ page }) => {
  await page.goto("/users")

  const responsePromise = page.waitForResponse(
    (resp) => resp.url().includes("/api/users") && resp.status() === 200
  )
  await page.getByRole("button", { name: "Load More" }).click()
  await responsePromise

  await expect(page.getByRole("listitem")).toHaveCount(20)
})

// 修复 3：处理动画和过渡
test("good: waits for stable state", async ({ page }) => {
  await page.goto("/modal-demo")
  await page.getByRole("button", { name: "Open" }).click()
  await expect(page.getByRole("dialog")).toBeVisible()
  await page.getByRole("button", { name: "Confirm" }).click()
})

// 修复 4：对多步骤断言使用 toPass()
test("good: retry entire assertion block", async ({ page }) => {
  await page.goto("/search")

  await expect(async () => {
    await page.getByLabel("Search").fill("playwright")
    await page.getByRole("button", { name: "Search" }).click()
    await expect(page.getByTestId("result-count")).toHaveText("10 results")
  }).toPass({
    timeout: 15_000,
    intervals: [1_000, 2_000, 5_000],
  })
})
```

### 修复：测试隔离问题

**使用时机**：测试单独运行时通过（`--grep "test name"`），但与其他测试一起运行时失败，或仅在并行模式下失败。

隔离问题源于共享状态：模块级变量、数据库行、localStorage、cookies 或文件系统产物。

**TypeScript**

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

// ---- 修复 1：每个测试使用唯一数据 ----

// 不好——所有并行测试使用相同的邮箱，导致唯一约束冲突
test("bad: hardcoded data", async ({ page }) => {
  await page.goto("/register")
  await page.getByLabel("Email").fill("test@example.com")
  await page.getByRole("button", { name: "Register" }).click()
  await expect(page.getByText("Welcome")).toBeVisible()
})

// 好——每次测试运行使用唯一邮箱
test("good: unique data per test", async ({ page }) => {
  const email = `test-${Date.now()}-${Math.random().toString(36).slice(2)}@example.com`

  await page.goto("/register")
  await page.getByLabel("Email").fill(email)
  await page.getByRole("button", { name: "Register" }).click()
  await expect(page.getByText("Welcome")).toBeVisible()
})

// ---- 修复 2：对共享的昂贵资源使用 Worker 作用域的夹具 ----

type WorkerFixtures = {
  workerAccount: { email: string; id: string }
}

export const test = base.extend<{}, WorkerFixtures>({
  workerAccount: [
    async ({ request }, use) => {
      const email = `worker-${Date.now()}-${Math.random().toString(36).slice(2)}@example.com`
      const response = await request.post("/api/users", {
        data: { email, password: "TestP@ss123!" },
      })
      const account = await response.json()

      await use({ email, id: account.id })

      // 该 Worker 中所有测试完成后清理
      await request.delete(`/api/users/${account.id}`)
    },
    { scope: "worker" },
  ],
})

// ---- 修复 3：在夹具拆卸中清理状态 ----

export const testWithCleanup = base.extend({
  cleanPage: async ({ page }, use) => {
    await use(page)

    // 拆卸：清除所有客户端状态
    await page.evaluate(() => {
      localStorage.clear()
      sessionStorage.clear()
    })
    await page.context().clearCookies()
  },
})

// ---- 修复 4：隔离不能并行运行的测试 ----

import { test } from "@playwright/test"

// 仅在测试确实依赖共享状态时使用串行模式
// （例如，多步骤向导，每个测试是一个步骤）
test.describe.serial("checkout wizard", () => {
  test("step 1: add items", async ({ page }) => {
    await page.goto("/shop")
    await page.getByRole("button", { name: "Add Widget" }).click()
    await expect(page.getByTestId("cart-count")).toHaveText("1")
  })

  test("step 2: enter shipping", async ({ page }) => {
    await page.goto("/checkout/shipping")
    await page.getByLabel("Address").fill("123 Test St")
    await page.getByRole("button", { name: "Continue" }).click()
  })
})
```

**JavaScript**

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

// 修复 1：每个测试使用唯一数据
test("good: unique data per test", async ({ page }) => {
  const email = `test-${Date.now()}-${Math.random().toString(36).slice(2)}@example.com`

  await page.goto("/register")
  await page.getByLabel("Email").fill(email)
  await page.getByRole("button", { name: "Register" }).click()
  await expect(page.getByText("Welcome")).toBeVisible()
})

// 修复 2：对共享的昂贵资源使用 Worker 作用域的夹具
const test = base.extend({
  workerAccount: [
    async ({ request }, use) => {
      const email = `worker-${Date.now()}-${Math.random().toString(36).slice(2)}@example.com`
      const response = await request.post("/api/users", {
        data: { email, password: "TestP@ss123!" },
      })
      const account = await response.json()

      await use({ email, id: account.id })

      await request.delete(`/api/users/${account.id}`)
    },
    { scope: "worker" },
  ],
})

module.exports = { test, expect }
```

### 修复：环境问题

**使用时机**：测试本地通过但在 CI 中失败，或在某些操作系统、视口或机器上失败。

环境不稳定性源于本地机器与 CI 之间在渲染、时序、可用资源或外部服务可用性方面的差异。

**TypeScript**

```typescript
// playwright.config.ts —— 与环境一致的配置
import { defineConfig, devices } from "@playwright/test"

export default defineConfig({
  // ---- 修复 1：禁用动画以获得确定性行为 ----
  use: {
    // 禁用 CSS 动画和过渡
    contextOptions: {
      reducedMotion: "reduce",
    },
  },

  // ---- 修复 2：跨环境使用一致的视口 ----
  projects: [
    {
      name: "chromium",
      use: {
        ...devices["Desktop Chrome"],
        // 显式指定视口防止本地与 CI 之间的布局差异
        viewport: { width: 1280, height: 720 },
      },
    },
  ],

  // ---- 修复 3：使用 webServer 在 CI 中启动应用 ----
  webServer: {
    command: "npm run start",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },

  // ---- 修复 4：为较慢的 CI 机器设置更高的超时 ----
  timeout: process.env.CI ? 60_000 : 30_000,
  expect: {
    timeout: process.env.CI ? 10_000 : 5_000,
  },
})
```

```typescript
// tests/fixtures/stub-externals.ts —— 桩接外部服务
import { test as base, expect } from "@playwright/test"

export const test = base.extend({
  // 自动夹具：在每个测试中拦截所有外部服务
  stubExternals: [
    async ({ page }, use) => {
      // 拦截环境间存在差异的第三方脚本
      await page.route(/google-analytics|segment|hotjar|intercom/, (route) => route.abort())

      // 用一致响应桩接不稳定的外部 API
      await page.route("**/api.external-service.com/**", (route) =>
        route.fulfill({
          status: 200,
          contentType: "application/json",
          body: JSON.stringify({ status: "ok", data: [] }),
        })
      )

      await use()
    },
    { auto: true },
  ],
})

export { expect }
```

**JavaScript**

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

module.exports = defineConfig({
  use: {
    contextOptions: {
      reducedMotion: "reduce",
    },
  },
  projects: [
    {
      name: "chromium",
      use: {
        ...devices["Desktop Chrome"],
        viewport: { width: 1280, height: 720 },
      },
    },
  ],
  webServer: {
    command: "npm run start",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },
  timeout: process.env.CI ? 60_000 : 30_000,
  expect: {
    timeout: process.env.CI ? 10_000 : 5_000,
  },
})
```

```javascript
// tests/fixtures/stub-externals.js
const { test: base, expect } = require("@playwright/test")

const test = base.extend({
  stubExternals: [
    async ({ page }, use) => {
      await page.route(/google-analytics|segment|hotjar|intercom/, (route) => route.abort())

      await page.route("**/api.external-service.com/**", (route) =>
        route.fulfill({
          status: 200,
          contentType: "application/json",
          body: JSON.stringify({ status: "ok", data: [] }),
        })
      )

      await use()
    },
    { auto: true },
  ],
})

module.exports = { test, expect }
```

### 检测策略

**使用时机**：怀疑测试不稳定但并非每次都会失败，或者希望验证修复是否确实消除了不稳定性。

**TypeScript**

```typescript
// ---- 策略 1：使用 --repeat-each 进行压力测试 ----
// 将测试运行 20 次。只要失败一次，就说明存在不稳定性缺陷。
// npx playwright test tests/checkout.spec.ts --repeat-each=20

// ---- 策略 2：通过重试配置捕获间歇性失败 ----
// playwright.config.ts
import { defineConfig } from "@playwright/test"

export default defineConfig({
  // 在 CI 中重试以在报告中暴露不稳定测试
  retries: process.env.CI ? 2 : 0,

  // 报告器显示哪些测试需要重试
  reporter: process.env.CI
    ? [
        ["html", { open: "never" }],
        ["json", { outputFile: "results.json" }],
      ]
    : [["html", { open: "on-failure" }]],
})

// ---- 策略 3：自定义报告器跟踪不稳定测试指标 ----
// flaky-reporter.ts
import type { Reporter, TestCase, TestResult } from "@playwright/test/reporter"

class FlakyReporter implements Reporter {
  private flakyTests: { name: string; file: string; retries: number }[] = []

  onTestEnd(test: TestCase, result: TestResult) {
    if (result.retry > 0 && result.status === "passed") {
      this.flakyTests.push({
        name: test.title,
        file: test.location.file,
        retries: result.retry,
      })
    }
  }

  onEnd() {
    if (this.flakyTests.length > 0) {
      console.log("\n--- FLAKY TESTS ---")
      for (const t of this.flakyTests) {
        console.log(`  ${t.file} > "${t.name}" (needed ${t.retries} retries)`)
      }
      console.log(`Total flaky: ${this.flakyTests.length}`)
    }
  }
}

export default FlakyReporter
```

```typescript
// playwright.config.ts —— 注册自定义不稳定测试报告器
import { defineConfig } from "@playwright/test"

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  reporter: [["html"], ["./flaky-reporter.ts"]],
})
```

**JavaScript**

```javascript
// flaky-reporter.js
class FlakyReporter {
  constructor() {
    this.flakyTests = []
  }

  onTestEnd(test, result) {
    if (result.retry > 0 && result.status === "passed") {
      this.flakyTests.push({
        name: test.title,
        file: test.location.file,
        retries: result.retry,
      })
    }
  }

  onEnd() {
    if (this.flakyTests.length > 0) {
      console.log("\n--- FLAKY TESTS ---")
      for (const t of this.flakyTests) {
        console.log(`  ${t.file} > "${t.name}" (needed ${t.retries} retries)`)
      }
      console.log(`Total flaky: ${this.flakyTests.length}`)
    }
  }
}

module.exports = FlakyReporter
```

### 隔离策略

**使用时机**：测试已知不稳定且无法立即修复。将其隔离，使其不阻塞 CI，但加以跟踪以免被遗忘。

**TypeScript**

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

// ---- 选项 1：test.fixme() —— 跳过测试并附带原因 ----
test.fixme("checkout with promo code applies discount", async ({ page }) => {
  // TODO(JIRA-1234)：因促销服务中的竞态条件而不稳定
  // 约 10% 的运行会失败。根本原因：/api/promo 在渲染完成后才响应
  await page.goto("/checkout")
  await page.getByLabel("Promo code").fill("SAVE20")
  await page.getByRole("button", { name: "Apply" }).click()
  await expect(page.getByTestId("discount")).toHaveText("-$20.00")
})

// ---- 选项 2：test.fail() —— 取反：测试仅在失败时通过 ----
// 当你明确知道测试会失败，并希望 CI 在它开始通过时提醒你时使用
test.fail("known broken: export to PDF", async ({ page }) => {
  // 当此测试开始通过时，.fail() 注释将使其失败，
  // 提醒你移除该注释
  await page.goto("/reports")
  await page.getByRole("button", { name: "Export PDF" }).click()
  await expect(page.getByText("PDF ready")).toBeVisible({ timeout: 10_000 })
})

// ---- 选项 3：按标签跳过 —— 使用 grep 过滤器隔离 ----
test("@flaky checkout race condition", async ({ page }) => {
  // 在 CI 中，排除带不稳定标签的测试：npx playwright test --grep-invert @flaky
  // 仅在夜间运行不稳定测试：npx playwright test --grep @flaky --retries=5
  await page.goto("/checkout")
  await page.getByRole("button", { name: "Place Order" }).click()
  await expect(page.getByText("Order confirmed")).toBeVisible()
})
```

**JavaScript**

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

// 选项 1：test.fixme() —— 跳过测试并附带原因
test.fixme("checkout with promo code applies discount", async ({ page }) => {
  // TODO(JIRA-1234)：因促销服务中的竞态条件而不稳定
  await page.goto("/checkout")
  await page.getByLabel("Promo code").fill("SAVE20")
  await page.getByRole("button", { name: "Apply" }).click()
  await expect(page.getByTestId("discount")).toHaveText("-$20.00")
})

// 选项 2：test.fail() —— 取反：测试仅在失败时通过
test.fail("known broken: export to PDF", async ({ page }) => {
  await page.goto("/reports")
  await page.getByRole("button", { name: "Export PDF" }).click()
  await expect(page.getByText("PDF ready")).toBeVisible({ timeout: 10_000 })
})

// 选项 3：按标签跳过
test("@flaky checkout race condition", async ({ page }) => {
  await page.goto("/checkout")
  await page.getByRole("button", { name: "Place Order" }).click()
  await expect(page.getByText("Order confirmed")).toBeVisible()
})
```

**隔离的 CI 配置：**

```yaml
# .github/workflows/tests.yml
jobs:
  e2e-tests:
    steps:
      - name: 运行稳定测试
        run: npx playwright test --grep-invert @flaky

  flaky-monitoring:
    # 夜间运行，不在每次 PR 时运行
    schedule:
      - cron: "0 3 * * *"
    steps:
      - name: 带重试运行不稳定测试
        run: npx playwright test --grep @flaky --retries=5 --reporter=json
      - name: 报告不稳定测试结果
        run: node scripts/report-flaky-metrics.js
```

### 预防清单

从一开始就应用这些规则，防止不稳定性进入你的测试套件。

**TypeScript**

```typescript
// playwright.config.ts —— 抗不稳定性配置
import { defineConfig, devices } from "@playwright/test"

export default defineConfig({
  // 规则 1：完全并行运行测试以尽早暴露隔离问题
  fullyParallel: true,

  // 规则 2：如果代码中遗留了 test.only()，使 CI 失败
  forbidOnly: !!process.env.CI,

  // 规则 3：在 CI 中使用重试来暴露（而非隐藏）不稳定测试
  retries: process.env.CI ? 2 : 0,

  // 规则 4：合理的超时——既不过高也不过低
  timeout: 30_000,
  expect: { timeout: 5_000 },

  use: {
    // 规则 5：始终在重试时捕获跟踪以便调试
    trace: "on-first-retry",

    // 规则 6：使用 baseURL——绝不在测试中硬编码完整 URL
    baseURL: process.env.BASE_URL || "http://localhost:3000",

    // 规则 7：禁用动画以获得确定性行为
    contextOptions: {
      reducedMotion: "reduce",
    },

    // 规则 8：显式指定视口——本地与 CI 一致
    viewport: { width: 1280, height: 720 },
  },

  // 规则 9：在 CI 中自动启动应用
  webServer: {
    command: "npm run start",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
})
```

```typescript
// tests/example-stable-test.spec.ts —— 在测试中应用所有规则
import { test, expect } from "@playwright/test"

test.describe("user profile", () => {
  test("updates display name", async ({ page }) => {
    // 规则 10：每个测试使用唯一数据
    const newName = `User-${Date.now()}`

    // 规则 11：使用 baseURL——仅使用相对路径
    await page.goto("/profile")

    // 规则 12：基于角色的定位器——对实现变更具有弹性
    await page.getByRole("textbox", { name: "Display name" }).fill(newName)
    await page.getByRole("button", { name: "Save" }).click()

    // 规则 13：自动重试断言——绝不手动等待
    await expect(page.getByRole("alert")).toHaveText("Profile updated")

    // 规则 14：对结果（而非中间状态）进行断言
    await expect(page.getByRole("textbox", { name: "Display name" })).toHaveValue(newName)
  })
})
```

**JavaScript**

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

module.exports = defineConfig({
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  timeout: 30_000,
  expect: { timeout: 5_000 },
  use: {
    trace: "on-first-retry",
    baseURL: process.env.BASE_URL || "http://localhost:3000",
    contextOptions: {
      reducedMotion: "reduce",
    },
    viewport: { width: 1280, height: 720 },
  },
  webServer: {
    command: "npm run start",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
})
```

```javascript
// tests/example-stable-test.spec.js
const { test, expect } = require("@playwright/test")

test.describe("user profile", () => {
  test("updates display name", async ({ page }) => {
    const newName = `User-${Date.now()}`

    await page.goto("/profile")
    await page.getByRole("textbox", { name: "Display name" }).fill(newName)
    await page.getByRole("button", { name: "Save" }).click()

    await expect(page.getByRole("alert")).toHaveText("Profile updated")
    await expect(page.getByRole("textbox", { name: "Display name" })).toHaveValue(newName)
  })
})
```

## 决策指南

```
我的测试不稳定。我该怎么办？
|
+-- 第 1 步：在本地复现
|   |
|   +-- npx playwright test <file> --repeat-each=20
|   +-- 失败？--> 时序问题。用自动重试断言修复。
|   +-- 不失败？--> 继续到第 2 步。
|
+-- 第 2 步：与其他测试隔离
|   |
|   +-- npx playwright test --grep "exact test name" --workers=1
|   +-- 单独通过？--> 隔离问题。用唯一数据 + 夹具修复。
|   +-- 单独失败？--> 继续到第 3 步。
|
+-- 第 3 步：对比环境
|   |
|   +-- 下载 CI 跟踪，与本地跟踪对比
|   +-- 不同？--> 环境问题。用显式视口、
|   |              reducedMotion、webServer 配置、桩接外部服务修复。
|   +-- 相同？--> 继续到第 4 步。
|
+-- 第 4 步：检查基础设施
|   |
|   +-- 错误提到浏览器崩溃、OOM、DNS、ECONNREFUSED？
|   +-- 是 --> 基础设施问题。用 Docker、重试配置、
|   |          测试运行前的健康检查修复。
|   +-- 否 --> 重新检查。启用 trace: 'on' 和重试以收集
|              更多数据。并排对比通过和失败的跟踪。
```

## 反模式

| 不要这样做 | 问题 | 应该这样做 |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 将超时增加到 120 秒来"修复"不稳定性 | 掩盖了真正的问题。失败时测试变得慢得难以忍受。拖慢整个 CI 流水线。 | 诊断根本原因。修复竞态条件，而不是超时。 |
| 使用 `page.waitForTimeout(N)` | 随意延迟在快机器上太慢，在慢机器上太快。不稳定性的头号原因。 | 使用 `expect(locator).toBeVisible()`、`page.waitForResponse()` 或 `expect.poll()`。 |
| 忽略不稳定测试（"再运行一次就能通过"） | 不稳定测试侵蚀对整个套件的信任。人们不再看失败报告。真正的缺陷被漏掉。 | 立即诊断。如果无法立即修复，使用 `test.fixme()` 加跟踪工单进行隔离。 |
| 添加 `--retries=3` 就声称修复了 | 重试不能修复不稳定性，它们只是隐藏了它。需要重试的测试就是有缺陷的测试。 | 使用重试来**检测**不稳定性（在报告中检查重试次数），而非掩盖它。 |
| 使用 `test.describe.serial()` 修复顺序依赖的测试 | 串行模式强制块中的所有测试顺序执行。它隐藏了隔离缺陷并拖慢了套件。 | 修复隔离问题。每个测试应独立于执行顺序通过。 |
| 模拟所有内容以防止环境差异 | 过度模拟降低了实际系统能正常工作的信心。测试通过但应用却坏了。 | 仅模拟外部/第三方服务。对你自己的 API 进行真实测试。 |
| 每次提交都在 CI 中运行 `--repeat-each=100` | 将 CI 时间放大 100 倍。浪费资源。 | 在本地或夜间任务中进行压力测试，而不是每次 PR 都做。 |

## 故障排查

| 症状 | 类别 | 修复 |
| --------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------ |
| 测试间歇性失败，提示"Timeout 5000ms" | 时序 | 将 `expect.timeout` 增加到 10 秒，或在断言前添加 `page.waitForResponse()` |
| 测试单独通过，在完整套件运行中失败 | 隔离 | 检查模块级 `let` 变量、共享数据库行或 localStorage 泄漏 |
| 测试本地通过，在 CI 中失败 | 环境 | 对比跟踪。检查视口、字体、`reducedMotion` 和外部服务可用性 |
| 测试失败，提示"Target closed"或"Browser closed" | 基础设施 | 检查 CI 内存限制。添加 `--workers=50%` 以减少并行负载。在 `beforeAll` 中添加健康检查 |
| 测试每次失败方式不同 | 时序 + 隔离 | 启用 `trace: 'on'` 并对比多个失败跟踪。不一致性本身就是线索 |
| 不稳定测试 99/100 次通过 | 时序（罕见竞态） | 本地使用 `--repeat-each=200`。针对特定竞态添加 `page.waitForResponse()` 或 `expect.poll()` |
| 可视化对比测试不稳定 | 环境 | 使用 `maxDiffPixelRatio` 阈值。使用 `@font-face` 设置显式字体。使用 Docker 实现一致渲染 |
| 测试仅在 WebKit 上不稳定 | 环境 | WebKit 时序行为不同。按项目添加 WebKit 特定的断言或增加超时 |

## 相关文档

- [core/assertions-and-waiting.md](assertions-and-waiting.md) —— 自动重试断言和显式等待
- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) —— 用于测试隔离的夹具拆卸
- [core/test-data-management.md](test-data-management.md) —— 每个测试使用唯一数据、工厂函数
- [core/configuration.md](configuration.md) —— 重试、超时和跟踪配置
- [core/debugging.md](debugging.md) —— 跟踪查看器、UI 模式和 Inspector，用于诊断失败
- [core/common-pitfalls.md](common-pitfalls.md) —— 导致不稳定性的常见错误