wehub-skill-sync
1366 lines
45 KiB
Markdown
1366 lines
45 KiB
Markdown
# Common Pitfalls
|
||
|
||
> **使用场景**：学习 Playwright、审查测试中的常见错误，或让新团队成员上手测试套件时参考。
|
||
|
||
按在真实代码库中出现频率排序的 20 个最常见 Playwright 错误。每个陷阱包含症状、根因以及完整的修复方案。
|
||
|
||
---
|
||
|
||
## 陷阱 1：使用 `page.waitForTimeout()` 代替断言
|
||
|
||
**症状**：测试缓慢且不稳定。在快速机器上能通过，但在慢速 CI 运行环境中会失败。
|
||
|
||
**原因**：开发者将 Selenium 或 Cypress 中的习惯带了过来，那些工具需要显式等待。在 Playwright 中，自动重试断言会自动处理时序问题。
|
||
|
||
**修复**：将每一个 `waitForTimeout` 替换为 web 优先断言或对特定条件的显式等待。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法
|
||
test("bad: arbitrary wait", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
await page.getByRole("button", { name: "Load" }).click()
|
||
await page.waitForTimeout(3000)
|
||
await expect(page.getByTestId("chart")).toBeVisible()
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: auto-retrying assertion", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
await page.getByRole("button", { name: "Load" }).click()
|
||
await expect(page.getByTestId("chart")).toBeVisible()
|
||
})
|
||
|
||
// 正确做法——当需要等待特定网络事件时
|
||
test("good: wait for response", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
const responsePromise = page.waitForResponse("**/api/chart-data")
|
||
await page.getByRole("button", { name: "Load" }).click()
|
||
await responsePromise
|
||
await expect(page.getByTestId("chart")).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: arbitrary wait", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
await page.getByRole("button", { name: "Load" }).click()
|
||
await page.waitForTimeout(3000)
|
||
await expect(page.getByTestId("chart")).toBeVisible()
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: auto-retrying assertion", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
await page.getByRole("button", { name: "Load" }).click()
|
||
await expect(page.getByTestId("chart")).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**`waitForTimeout` 唯一可接受的用途**：调试时无法使用 `page.pause()`，或在性能测试中模拟用户真实的"思考时间"。绝不应出现在生产测试代码中。
|
||
|
||
---
|
||
|
||
## 陷阱 2：未对异步操作使用 `await`
|
||
|
||
**症状**：测试结果不可预测。断言在操作完成之前就执行了。错误信息中引用了已分离的 frame 或已关闭的页面。
|
||
|
||
**原因**：每个 Playwright API 调用都是异步的。只要漏掉一个 `await`，下一行代码就会在前一个操作完成之前执行。
|
||
|
||
**修复**：始终对每个 Playwright 调用使用 `await`。启用 `@typescript-eslint/no-floating-promises` ESLint 规则。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——click 缺少 await，断言在导航完成前执行
|
||
test("bad: missing await", async ({ page }) => {
|
||
await page.goto("/login")
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Password").fill("password")
|
||
page.getByRole("button", { name: "Sign in" }).click() // 缺少 AWAIT
|
||
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: all actions awaited", async ({ page }) => {
|
||
await page.goto("/login")
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Password").fill("password")
|
||
await page.getByRole("button", { name: "Sign in" }).click()
|
||
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: missing await", async ({ page }) => {
|
||
await page.goto("/login")
|
||
page.getByRole("button", { name: "Submit" }).click() // 缺少 AWAIT
|
||
await expect(page.getByText("Success")).toBeVisible()
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: all actions awaited", async ({ page }) => {
|
||
await page.goto("/login")
|
||
await page.getByRole("button", { name: "Submit" }).click()
|
||
await expect(page.getByText("Success")).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**预防措施**：添加以下 ESLint 配置，在编译时捕获悬浮的 Promise：
|
||
|
||
```json
|
||
{
|
||
"rules": {
|
||
"@typescript-eslint/no-floating-promises": "error"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 3：使用 CSS 选择器而非基于角色的定位器
|
||
|
||
**症状**：只要 CSS 类名、DOM 结构或组件库发生变化，测试就会失败。测试难以阅读，因为选择器看起来像 `.btn-primary > span:nth-child(2)`。
|
||
|
||
**原因**：开发者使用从 jQuery 或 DevTools 中学到的方式。CSS 选择器是频繁变化的实现细节。
|
||
|
||
**修复**：使用 Playwright 内置的定位器，它们针对无障碍角色、标签、文本和测试 ID 进行定位。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——脆弱的 CSS 选择器
|
||
test("bad: CSS selectors", async ({ page }) => {
|
||
await page.goto("/settings")
|
||
await page.locator(".form-group:nth-child(3) input.form-control").fill("new value")
|
||
await page.locator("button.btn.btn-primary.submit-btn").click()
|
||
await expect(page.locator(".alert.alert-success")).toBeVisible()
|
||
})
|
||
|
||
// 正确做法——基于角色的定位器
|
||
test("good: accessible locators", async ({ page }) => {
|
||
await page.goto("/settings")
|
||
await page.getByLabel("Display name").fill("new value")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
await expect(page.getByRole("alert")).toHaveText("Settings saved")
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: CSS selectors", async ({ page }) => {
|
||
await page.locator(".form-group:nth-child(3) input").fill("new value")
|
||
await page.locator("button.btn-primary").click()
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: accessible locators", async ({ page }) => {
|
||
await page.getByLabel("Display name").fill("new value")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
})
|
||
```
|
||
|
||
**定位器优先级**（从最稳健到最脆弱）：
|
||
|
||
1. `getByRole()` —— 无障碍角色 + 名称
|
||
2. `getByLabel()` —— 通过标签文本定位表单字段
|
||
3. `getByPlaceholder()` —— 通过占位符定位输入框
|
||
4. `getByText()` —— 可见文本内容
|
||
5. `getByTestId()` —— 稳定的 `data-testid` 属性
|
||
6. CSS/XPath 选择器 —— 仅作为最后手段
|
||
|
||
---
|
||
|
||
## 陷阱 4：断言 `isVisible()` 的返回值而非使用 `expect().toBeVisible()`
|
||
|
||
**症状**：元素不可见时测试仍然通过。断言在静默中出错。在时序压力下不稳定。
|
||
|
||
**原因**：`isVisible()` 在某个时间点返回一个布尔值——不会重试。如果元素尚未出现，它返回 `false`，而 `expect(false).toBe(true)` 会立即失败，不做任何等待。
|
||
|
||
**修复**：始终使用 `expect(locator).toBeVisible()`，它会自动重试直到元素出现或超时。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——只解析一次，不重试
|
||
test("bad: isVisible check", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
const visible = await page.getByTestId("widget").isVisible()
|
||
expect(visible).toBe(true) // 如果 widget 尚未渲染，会立即失败
|
||
})
|
||
|
||
// 正确做法——最多自动重试 5 秒
|
||
test("good: toBeVisible assertion", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
await expect(page.getByTestId("widget")).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: isVisible check", async ({ page }) => {
|
||
const visible = await page.getByTestId("widget").isVisible()
|
||
expect(visible).toBe(true)
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: toBeVisible assertion", async ({ page }) => {
|
||
await expect(page.getByTestId("widget")).toBeVisible()
|
||
})
|
||
```
|
||
|
||
这适用于所有"只解析一次"的方法：`isVisible()`、`isEnabled()`、`isChecked()`、`textContent()`、`getAttribute()`、`inputValue()`。始终使用对应的 `expect(locator)` web 优先断言。
|
||
|
||
---
|
||
|
||
## 陷阱 5：在并行测试之间共享可变状态
|
||
|
||
**症状**：测试单独运行能通过，但在完整测试套件中失败。存在顺序相关的失败。"重复键"错误。
|
||
|
||
**原因**：模块级变量、共享的数据库行或 `beforeAll` 创建的状态被一个测试修改后，被另一个并行运行的测试读到。
|
||
|
||
**修复**：使用测试作用域的 fixture 配合唯一数据。切勿在模块级变量中存储可变状态。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test as base, expect } from "@playwright/test"
|
||
|
||
// 错误做法——模块级可变状态在并行测试间共享
|
||
let userId: string
|
||
|
||
test.beforeAll(async ({ request }) => {
|
||
const res = await request.post("/api/users", {
|
||
data: { email: "shared@test.com" },
|
||
})
|
||
userId = (await res.json()).id // 每个并行 worker 都会覆盖这个值
|
||
})
|
||
|
||
test("bad: uses shared state", async ({ page }) => {
|
||
await page.goto(`/users/${userId}`) // userId 可能来自另一个 worker
|
||
})
|
||
|
||
// 正确做法——测试作用域的 fixture，每个测试使用唯一数据
|
||
export const test = base.extend<{ testUser: { id: string; email: string } }>({
|
||
testUser: async ({ request }, use) => {
|
||
const email = `user-${Date.now()}-${Math.random().toString(36).slice(2)}@test.com`
|
||
const res = await request.post("/api/users", { data: { email } })
|
||
const user = await res.json()
|
||
|
||
await use({ id: user.id, email })
|
||
|
||
await request.delete(`/api/users/${user.id}`)
|
||
},
|
||
})
|
||
|
||
test("good: isolated data per test", async ({ page, testUser }) => {
|
||
await page.goto(`/users/${testUser.id}`)
|
||
await expect(page.getByText(testUser.email)).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test: base, expect } = require("@playwright/test")
|
||
|
||
// 正确做法
|
||
const test = base.extend({
|
||
testUser: async ({ request }, use) => {
|
||
const email = `user-${Date.now()}-${Math.random().toString(36).slice(2)}@test.com`
|
||
const res = await request.post("/api/users", { data: { email } })
|
||
const user = await res.json()
|
||
|
||
await use({ id: user.id, email })
|
||
|
||
await request.delete(`/api/users/${user.id}`)
|
||
},
|
||
})
|
||
|
||
test("good: isolated data per test", async ({ page, testUser }) => {
|
||
await page.goto(`/users/${testUser.id}`)
|
||
await expect(page.getByText(testUser.email)).toBeVisible()
|
||
})
|
||
|
||
module.exports = { test }
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 6：未使用 `baseURL`（硬编码完整 URL）
|
||
|
||
**症状**：切换环境（本地、预发布、生产）时测试失败。URL 字符串在各处重复。
|
||
|
||
**原因**：开发者从 `page.goto('http://localhost:3000/login')` 开始，之后从未重构。
|
||
|
||
**修复**：在 `playwright.config` 中设置 `baseURL`，并在所有测试中使用相对路径。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
// playwright.config.ts
|
||
import { defineConfig } from "@playwright/test"
|
||
|
||
export default defineConfig({
|
||
use: {
|
||
baseURL: process.env.BASE_URL || "http://localhost:3000",
|
||
},
|
||
})
|
||
```
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法
|
||
test("bad: hardcoded URL", async ({ page }) => {
|
||
await page.goto("http://localhost:3000/login")
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: relative URL", async ({ page }) => {
|
||
await page.goto("/login")
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
// playwright.config.js
|
||
const { defineConfig } = require("@playwright/test")
|
||
|
||
module.exports = defineConfig({
|
||
use: {
|
||
baseURL: process.env.BASE_URL || "http://localhost:3000",
|
||
},
|
||
})
|
||
```
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: hardcoded URL", async ({ page }) => {
|
||
await page.goto("http://localhost:3000/login")
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: relative URL", async ({ page }) => {
|
||
await page.goto("/login")
|
||
})
|
||
```
|
||
|
||
通过设置环境变量在不同的环境中运行：`BASE_URL=https://staging.example.com npx playwright test`
|
||
|
||
---
|
||
|
||
## 陷阱 7：使用 `page.$()` 而非 `page.locator()`
|
||
|
||
**症状**：元素句柄为 `null`。出现过期元素错误。没有自动等待。
|
||
|
||
**原因**：`page.$()` 和 `page.$$()` 是来自 Puppeteer 的 ElementHandle API。它们只解析一次，返回的句柄可能会过期。定位器是 Playwright 的替代方案——它们是惰性的，每次操作时重新求值。
|
||
|
||
**修复**：始终使用 `page.locator()`、`page.getByRole()` 或其他定位器方法。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——ElementHandle API，只解析一次，可能过期
|
||
test("bad: page.$ usage", async ({ page }) => {
|
||
await page.goto("/products")
|
||
const button = await page.$(".add-to-cart") // 未找到则为 null，DOM 变化则过期
|
||
if (button) {
|
||
await button.click()
|
||
}
|
||
const count = await page.$$(".cart-item")
|
||
expect(count.length).toBe(1) // 无自动重试
|
||
})
|
||
|
||
// 正确做法——定位器 API，惰性求值，自动等待
|
||
test("good: locator usage", async ({ page }) => {
|
||
await page.goto("/products")
|
||
await page.getByRole("button", { name: "Add to cart" }).first().click()
|
||
await expect(page.getByTestId("cart-item")).toHaveCount(1) // 自动重试
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: page.$ usage", async ({ page }) => {
|
||
const button = await page.$(".add-to-cart")
|
||
if (button) await button.click()
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: locator usage", async ({ page }) => {
|
||
await page.getByRole("button", { name: "Add to cart" }).first().click()
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 8：未处理表单提交后的导航
|
||
|
||
**症状**：测试失败，提示"目标页面、上下文或浏览器已关闭"，或断言因页面在断言运行前已导航离开而失败。
|
||
|
||
**原因**：点击提交按钮会触发完整的页面导航。断言针对的是正在被卸载的旧页面。
|
||
|
||
**修复**：在断言新页面之前，等待导航完成。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——断言在导航完成前执行
|
||
test("bad: no navigation handling", async ({ page }) => {
|
||
await page.goto("/login")
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Password").fill("password")
|
||
await page.getByRole("button", { name: "Sign in" }).click()
|
||
// 页面正在导航——这可能会失败，提示"执行上下文已被销毁"
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
|
||
// 正确做法——等待 URL 变化，然后断言
|
||
test("good: waitForURL after navigation", async ({ page }) => {
|
||
await page.goto("/login")
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Password").fill("password")
|
||
await page.getByRole("button", { name: "Sign in" }).click()
|
||
await page.waitForURL("/dashboard")
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
|
||
// 正确做法——替代方案：使用 expect().toHaveURL()，它会自动重试
|
||
test("good: toHaveURL assertion", async ({ page }) => {
|
||
await page.goto("/login")
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Password").fill("password")
|
||
await page.getByRole("button", { name: "Sign in" }).click()
|
||
await expect(page).toHaveURL(/.*dashboard/)
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 正确做法
|
||
test("good: waitForURL after navigation", async ({ page }) => {
|
||
await page.goto("/login")
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Password").fill("password")
|
||
await page.getByRole("button", { name: "Sign in" }).click()
|
||
await page.waitForURL("/dashboard")
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 9：在 CI 中未配置 `webServer` 就测试 `localhost`
|
||
|
||
**症状**：测试在 CI 中失败，报 `ECONNREFUSED` 连接 `localhost:3000`。本地能通过，因为开发服务器已经在运行。
|
||
|
||
**原因**：CI 运行环境以干净环境启动。除非你显式启动，否则没有开发服务器在运行。
|
||
|
||
**修复**：使用 `webServer` 配置选项自动启动你的应用。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
// playwright.config.ts
|
||
import { defineConfig } from "@playwright/test"
|
||
|
||
export default defineConfig({
|
||
use: {
|
||
baseURL: "http://localhost:3000",
|
||
},
|
||
|
||
webServer: {
|
||
command: "npm run start",
|
||
url: "http://localhost:3000",
|
||
// 本地复用已有服务器（更快），CI 中全新启动
|
||
reuseExistingServer: !process.env.CI,
|
||
// 给服务器启动时间
|
||
timeout: 120_000,
|
||
// 捕获服务器输出以调试启动失败
|
||
stdout: "pipe",
|
||
stderr: "pipe",
|
||
},
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
// playwright.config.js
|
||
const { defineConfig } = require("@playwright/test")
|
||
|
||
module.exports = defineConfig({
|
||
use: {
|
||
baseURL: "http://localhost:3000",
|
||
},
|
||
webServer: {
|
||
command: "npm run start",
|
||
url: "http://localhost:3000",
|
||
reuseExistingServer: !process.env.CI,
|
||
timeout: 120_000,
|
||
stdout: "pipe",
|
||
stderr: "pipe",
|
||
},
|
||
})
|
||
```
|
||
|
||
对于多个服务器（前端 + 后端），传入数组：
|
||
|
||
```typescript
|
||
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 },
|
||
],
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 10：使用 `innerHTML` 做文本断言而非 `toHaveText()`
|
||
|
||
**症状**：HTML 结构变化时测试失败。断言脆弱且难以阅读。
|
||
|
||
**原因**：开发者使用 `innerHTML()` 或 `textContent()` 获取文本，然后在解析后的字符串上做断言。这只解析一次，没有重试。
|
||
|
||
**修复**：使用 `expect(locator).toHaveText()` 或 `expect(locator).toContainText()` 进行自动重试的文本断言。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——只解析一次，包含 HTML 标签，无重试
|
||
test("bad: innerHTML assertion", async ({ page }) => {
|
||
await page.goto("/product/123")
|
||
const html = await page.getByTestId("price").innerHTML()
|
||
expect(html).toContain("$49.99") // 脆弱：依赖于 HTML 结构
|
||
})
|
||
|
||
// 错误做法——textContent 只解析一次，无重试
|
||
test("bad: textContent assertion", async ({ page }) => {
|
||
await page.goto("/product/123")
|
||
const text = await page.getByTestId("price").textContent()
|
||
expect(text).toBe("$49.99") // 如果文本尚未加载完成，无重试
|
||
})
|
||
|
||
// 正确做法——自动重试，不依赖 HTML
|
||
test("good: toHaveText assertion", async ({ page }) => {
|
||
await page.goto("/product/123")
|
||
await expect(page.getByTestId("price")).toHaveText("$49.99")
|
||
})
|
||
|
||
// 正确做法——部分匹配，用于灵活断言
|
||
test("good: toContainText assertion", async ({ page }) => {
|
||
await page.goto("/product/123")
|
||
await expect(page.getByTestId("price")).toContainText("$49")
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: textContent assertion", async ({ page }) => {
|
||
const text = await page.getByTestId("price").textContent()
|
||
expect(text).toBe("$49.99")
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: toHaveText assertion", async ({ page }) => {
|
||
await expect(page.getByTestId("price")).toHaveText("$49.99")
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 11：过度 Mock（Mock 自己的 API）
|
||
|
||
**症状**：所有测试都通过，但应用在生产环境中是坏的。Mock 响应与真实 API 产生偏差。产生虚假信心。
|
||
|
||
**原因**：开发者为了速度和稳定性 mock 了每一个 API 调用，包括自己的后端。随着真实 API 的演进，mock 变得过时。
|
||
|
||
**修复**：只 mock 外部第三方服务。真实测试自己的 API。使用 `webServer` 在测试期间运行后端。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——mock 自己的 API 会降低信心
|
||
test("bad: mocks own API", async ({ page }) => {
|
||
await page.route("**/api/users/me", (route) =>
|
||
route.fulfill({
|
||
status: 200,
|
||
body: JSON.stringify({ name: "Test User", role: "admin" }),
|
||
})
|
||
)
|
||
await page.goto("/dashboard")
|
||
await expect(page.getByText("Test User")).toBeVisible() // 即使 API 有问题也通过
|
||
})
|
||
|
||
// 正确做法——只 mock 外部服务，真实测试自己的 API
|
||
test("good: real API, mocked externals", async ({ page }) => {
|
||
// 拦截第三方分析和广告
|
||
await page.route(/google-analytics|intercom|segment/, (route) => route.abort())
|
||
|
||
// 模拟不稳定的外部支付提供商
|
||
await page.route("**/api.stripe.com/**", (route) =>
|
||
route.fulfill({
|
||
status: 200,
|
||
body: JSON.stringify({ status: "succeeded" }),
|
||
})
|
||
)
|
||
|
||
// 针对真实的应用 API 进行测试
|
||
await page.goto("/dashboard")
|
||
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 正确做法——只 mock 外部服务
|
||
test("good: real API, mocked externals", async ({ page }) => {
|
||
await page.route(/google-analytics|intercom|segment/, (route) => route.abort())
|
||
|
||
await page.route("**/api.stripe.com/**", (route) =>
|
||
route.fulfill({
|
||
status: 200,
|
||
body: JSON.stringify({ status: "succeeded" }),
|
||
})
|
||
)
|
||
|
||
await page.goto("/dashboard")
|
||
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**何时可以接受 mock 自己的 API**：测试特定的错误状态（500、503、网络超时）或难以用真实后端复现的边缘情况。
|
||
|
||
---
|
||
|
||
## 陷阱 12：未使用 `test.describe` 进行分组
|
||
|
||
**症状**：测试文件是一组无关测试的扁平列表。共享配置（`test.use()`、`test.beforeEach()`）无法限定作用域。HTML 报告难以导航。
|
||
|
||
**原因**：开发者将测试写成扁平列表，从未将相关测试分组在一起。
|
||
|
||
**修复**：使用 `test.describe` 对相关测试进行分组。用于限定共享设置、配置覆盖和逻辑组织的范围。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——扁平列表，无分组，无共享上下文
|
||
test("admin can view users", async ({ page }) => {
|
||
/* ... */
|
||
})
|
||
test("admin can delete user", async ({ page }) => {
|
||
/* ... */
|
||
})
|
||
test("viewer cannot delete user", async ({ page }) => {
|
||
/* ... */
|
||
})
|
||
test("viewer can view users", async ({ page }) => {
|
||
/* ... */
|
||
})
|
||
|
||
// 正确做法——按角色分组，限定配置范围
|
||
test.describe("admin users", () => {
|
||
test.use({ storageState: ".auth/admin.json" })
|
||
|
||
test.beforeEach(async ({ page }) => {
|
||
await page.goto("/admin/users")
|
||
})
|
||
|
||
test("can view user list", async ({ page }) => {
|
||
await expect(page.getByRole("table")).toBeVisible()
|
||
})
|
||
|
||
test("can delete a user", async ({ page }) => {
|
||
await page.getByRole("row").first().getByRole("button", { name: "Delete" }).click()
|
||
await expect(page.getByRole("dialog")).toBeVisible()
|
||
})
|
||
})
|
||
|
||
test.describe("viewer users", () => {
|
||
test.use({ storageState: ".auth/viewer.json" })
|
||
|
||
test("can view user list", async ({ page }) => {
|
||
await page.goto("/admin/users")
|
||
await expect(page.getByRole("table")).toBeVisible()
|
||
})
|
||
|
||
test("cannot see delete button", async ({ page }) => {
|
||
await page.goto("/admin/users")
|
||
await expect(page.getByRole("button", { name: "Delete" })).not.toBeVisible()
|
||
})
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
test.describe("admin users", () => {
|
||
test.use({ storageState: ".auth/admin.json" })
|
||
|
||
test.beforeEach(async ({ page }) => {
|
||
await page.goto("/admin/users")
|
||
})
|
||
|
||
test("can view user list", async ({ page }) => {
|
||
await expect(page.getByRole("table")).toBeVisible()
|
||
})
|
||
|
||
test("can delete a user", async ({ page }) => {
|
||
await page.getByRole("row").first().getByRole("button", { name: "Delete" }).click()
|
||
await expect(page.getByRole("dialog")).toBeVisible()
|
||
})
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 13：使用 `beforeAll` 进行逐测试设置
|
||
|
||
**症状**：本应相互独立的测试共享了 `beforeAll` 中的状态。一个测试修改状态后，后续测试失败。
|
||
|
||
**原因**：开发者认为 `beforeAll` "更高效"，因为它只运行一次。但 `beforeAll` 创建的是 worker 作用域的状态，文件中所有测试共享。
|
||
|
||
**修复**：对逐测试设置使用 `beforeEach`，或对需要清理的设置使用测试作用域的 fixture。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——beforeAll 为所有测试创建一个用户；测试会修改共享状态
|
||
test.beforeAll(async ({ request }) => {
|
||
// 此用户在此文件的所有测试间共享
|
||
await request.post("/api/users", { data: { email: "shared@test.com", name: "Original" } })
|
||
})
|
||
|
||
test("updates user name", async ({ page }) => {
|
||
await page.goto("/users/shared@test.com")
|
||
await page.getByLabel("Name").fill("Updated")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
// 现在共享用户的 name 变为 "Updated"——其他测试会看到这个值
|
||
})
|
||
|
||
test("checks user name is Original", async ({ page }) => {
|
||
await page.goto("/users/shared@test.com")
|
||
// 失败——前一个测试改了名称
|
||
await expect(page.getByLabel("Name")).toHaveValue("Original")
|
||
})
|
||
|
||
// 正确做法——每个测试创建自己的用户
|
||
test.describe("user profile", () => {
|
||
test("updates user name", async ({ page, request }) => {
|
||
const email = `user-${Date.now()}@test.com`
|
||
await request.post("/api/users", { data: { email, name: "Original" } })
|
||
|
||
await page.goto(`/users/${email}`)
|
||
await page.getByLabel("Name").fill("Updated")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
await expect(page.getByLabel("Name")).toHaveValue("Updated")
|
||
})
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 正确做法——每个测试独立创建数据
|
||
test("updates user name", async ({ page, request }) => {
|
||
const email = `user-${Date.now()}@test.com`
|
||
await request.post("/api/users", { data: { email, name: "Original" } })
|
||
|
||
await page.goto(`/users/${email}`)
|
||
await page.getByLabel("Name").fill("Updated")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
await expect(page.getByLabel("Name")).toHaveValue("Updated")
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 14：在测试间共享的变量中存储测试数据
|
||
|
||
**症状**：测试 B 依赖于测试 A 创建的数据。重新排序或并行运行测试会破坏测试套件。
|
||
|
||
**原因**：开发者在模块级别声明 `let` 变量，在一个测试中赋值，并期望另一个测试能读取它们。
|
||
|
||
**修复**：每个测试必须创建自己的数据。使用 fixture 实现共享的设置逻辑。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——测试 B 依赖于测试 A 创建 product
|
||
let productId: string
|
||
|
||
test("test A: creates product", async ({ request }) => {
|
||
const res = await request.post("/api/products", { data: { name: "Widget" } })
|
||
productId = (await res.json()).id
|
||
})
|
||
|
||
test("test B: edits product", async ({ page }) => {
|
||
await page.goto(`/products/${productId}/edit`) // 如果测试 A 未先运行，则为 undefined
|
||
})
|
||
|
||
// 正确做法——每个测试自包含
|
||
test("creates and edits product", async ({ page, request }) => {
|
||
const res = await request.post("/api/products", { data: { name: `Widget-${Date.now()}` } })
|
||
const { id } = await res.json()
|
||
|
||
await page.goto(`/products/${id}/edit`)
|
||
await page.getByLabel("Name").fill("Updated Widget")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
await expect(page.getByText("Updated Widget")).toBeVisible()
|
||
|
||
// 清理
|
||
await request.delete(`/api/products/${id}`)
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 正确做法——自包含测试
|
||
test("creates and edits product", async ({ page, request }) => {
|
||
const res = await request.post("/api/products", { data: { name: `Widget-${Date.now()}` } })
|
||
const { id } = await res.json()
|
||
|
||
await page.goto(`/products/${id}/edit`)
|
||
await page.getByLabel("Name").fill("Updated Widget")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
await expect(page.getByText("Updated Widget")).toBeVisible()
|
||
|
||
await request.delete(`/api/products/${id}`)
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 15：`test.describe` 块嵌套过深
|
||
|
||
**症状**：测试结构超过 3 层深度。难以阅读。外层块中的 `beforeEach` 钩子在测试级别不可见。HTML 报告杂乱。
|
||
|
||
**原因**：开发者像组织代码一样组织测试——深层次嵌套结构。但测试应该是扁平且易于浏览的。
|
||
|
||
**修复**：嵌套限制最多 2 层。使用独立的文件代替深层嵌套。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——4 层深度，难以追踪
|
||
test.describe("admin", () => {
|
||
test.describe("settings", () => {
|
||
test.describe("security", () => {
|
||
test.describe("two-factor auth", () => {
|
||
test("enables TOTP", async ({ page }) => {
|
||
// 这个测试之前运行了哪些 beforeEach 钩子？难以得知。
|
||
})
|
||
})
|
||
})
|
||
})
|
||
})
|
||
|
||
// 正确做法——最多 2 层，清晰扁平
|
||
test.describe("admin security settings", () => {
|
||
test.beforeEach(async ({ page }) => {
|
||
await page.goto("/admin/settings/security")
|
||
})
|
||
|
||
test("enables two-factor auth via TOTP", async ({ page }) => {
|
||
await page.getByRole("button", { name: "Enable 2FA" }).click()
|
||
await expect(page.getByText("Scan QR code")).toBeVisible()
|
||
})
|
||
|
||
test("disables two-factor auth", async ({ page }) => {
|
||
await page.getByRole("button", { name: "Disable 2FA" }).click()
|
||
await expect(page.getByRole("dialog")).toBeVisible()
|
||
})
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 正确做法——扁平结构，最多 2 层
|
||
test.describe("admin security settings", () => {
|
||
test.beforeEach(async ({ page }) => {
|
||
await page.goto("/admin/settings/security")
|
||
})
|
||
|
||
test("enables two-factor auth via TOTP", async ({ page }) => {
|
||
await page.getByRole("button", { name: "Enable 2FA" }).click()
|
||
await expect(page.getByText("Scan QR code")).toBeVisible()
|
||
})
|
||
})
|
||
```
|
||
|
||
如果需要组织大量测试，拆分为独立文件：`security-2fa.spec.ts`、`security-passwords.spec.ts`、`security-sessions.spec.ts`。
|
||
|
||
---
|
||
|
||
## 陷阱 16：本地与 CI 未配置不同的重试策略
|
||
|
||
**症状**：开发者在本地使用重试（掩盖了开发过程中的缺陷），或在 CI 中没有重试（因非自身原因的间歇性问题而失败）。
|
||
|
||
**原因**：设置了一个统一的 `retries` 值，未考虑环境差异。
|
||
|
||
**修复**：本地零重试（快速失败），CI 中 1-2 次重试（捕获基础设施的微小故障）。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
// playwright.config.ts
|
||
import { defineConfig } from "@playwright/test"
|
||
|
||
export default defineConfig({
|
||
// 正确做法——不同环境使用不同的重试策略
|
||
retries: process.env.CI ? 2 : 0,
|
||
|
||
use: {
|
||
// 仅在重试时捕获 trace——节省 CI 时间和存储
|
||
trace: "on-first-retry",
|
||
},
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
// playwright.config.js
|
||
const { defineConfig } = require("@playwright/test")
|
||
|
||
module.exports = defineConfig({
|
||
retries: process.env.CI ? 2 : 0,
|
||
use: {
|
||
trace: "on-first-retry",
|
||
},
|
||
})
|
||
```
|
||
|
||
**重要**：一个始终需要重试才能通过的测试，并不是"通过"——它是不稳定的。追踪重试次数并修复根本原因。
|
||
|
||
---
|
||
|
||
## 陷阱 17：每次 CI 运行都跑所有浏览器
|
||
|
||
**症状**：CI 耗时是不必要的 3 倍。大多数缺陷被单个浏览器引擎就能捕获。
|
||
|
||
**原因**：开发者在配置中同时启用了 Chromium + Firefox + WebKit，之后从未重新考虑。
|
||
|
||
**修复**：每个 PR 只运行 Chromium。在夜间或预发布任务中运行所有浏览器。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
// playwright.config.ts
|
||
import { defineConfig, devices } from "@playwright/test"
|
||
|
||
const allBrowsers = [
|
||
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
|
||
{ name: "firefox", use: { ...devices["Desktop Firefox"] } },
|
||
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
|
||
]
|
||
|
||
const chromeOnly = [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }]
|
||
|
||
export default defineConfig({
|
||
// PR 运行：仅 Chromium。夜间运行：所有浏览器。
|
||
projects: process.env.ALL_BROWSERS ? allBrowsers : chromeOnly,
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
// playwright.config.js
|
||
const { defineConfig, devices } = require("@playwright/test")
|
||
|
||
const allBrowsers = [
|
||
{ name: "chromium", use: { ...devices["Desktop Chrome"] } },
|
||
{ name: "firefox", use: { ...devices["Desktop Firefox"] } },
|
||
{ name: "webkit", use: { ...devices["Desktop Safari"] } },
|
||
]
|
||
|
||
const chromeOnly = [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }]
|
||
|
||
module.exports = defineConfig({
|
||
projects: process.env.ALL_BROWSERS ? allBrowsers : chromeOnly,
|
||
})
|
||
```
|
||
|
||
```yaml
|
||
# .github/workflows/tests.yml
|
||
jobs:
|
||
pr-tests:
|
||
# 快速：仅 Chromium
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- run: npx playwright test
|
||
|
||
nightly-full:
|
||
# 全面：所有浏览器
|
||
schedule:
|
||
- cron: "0 3 * * *"
|
||
steps:
|
||
- run: ALL_BROWSERS=1 npx playwright test
|
||
```
|
||
|
||
---
|
||
|
||
## 陷阱 18：使用 `page.evaluate()` 做定位器能做的事
|
||
|
||
**症状**：测试冗长且脆弱。直接 DOM 操作绕过了 Playwright 的自动等待和可操作性检查。
|
||
|
||
**原因**：具有原生 JS 或 Puppeteer 背景的开发者习惯用 `evaluate()` 处理一切，因为感觉熟悉。
|
||
|
||
**修复**：对所有 DOM 交互使用定位器方法。将 `page.evaluate()` 留给定位器确实无法完成的任务（读取计算样式、调用应用特定的 JS API、设置测试钩子）。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——使用 evaluate 做定位器更擅长的事
|
||
test("bad: evaluate for DOM interaction", async ({ page }) => {
|
||
await page.goto("/settings")
|
||
|
||
// 获取文本
|
||
const text = await page.evaluate(
|
||
() => document.querySelector('[data-testid="username"]')?.textContent
|
||
)
|
||
expect(text).toBe("John")
|
||
|
||
// 点击
|
||
await page.evaluate(() => {
|
||
;(document.querySelector("button.save-btn") as HTMLButtonElement)?.click()
|
||
})
|
||
|
||
// 检查可见性
|
||
const visible = await page.evaluate(() => {
|
||
const el = document.querySelector(".success-message")
|
||
return el ? window.getComputedStyle(el).display !== "none" : false
|
||
})
|
||
expect(visible).toBe(true)
|
||
})
|
||
|
||
// 正确做法——具有自动等待和重试的定位器
|
||
test("good: locator methods", async ({ page }) => {
|
||
await page.goto("/settings")
|
||
|
||
await expect(page.getByTestId("username")).toHaveText("John")
|
||
await page.getByRole("button", { name: "Save" }).click()
|
||
await expect(page.getByText("Settings saved")).toBeVisible()
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 错误做法
|
||
test("bad: evaluate for DOM interaction", async ({ page }) => {
|
||
const text = await page.evaluate(
|
||
() => document.querySelector('[data-testid="username"]')?.textContent
|
||
)
|
||
expect(text).toBe("John")
|
||
})
|
||
|
||
// 正确做法
|
||
test("good: locator methods", async ({ page }) => {
|
||
await expect(page.getByTestId("username")).toHaveText("John")
|
||
})
|
||
```
|
||
|
||
**何时 `evaluate()` 是合适的**：读取 `window.__APP_STATE__`、调用应用暴露的测试专用设置函数、操作 `localStorage`/`sessionStorage`，或读取没有定位器等价方法的计算样式。
|
||
|
||
---
|
||
|
||
## 陷阱 19：未对复杂流程使用 `test.step()`
|
||
|
||
**症状**：长测试难以调试。失败时，trace 显示 50+ 个操作，没有逻辑分组。HTML 报告没有提供任何结构。
|
||
|
||
**原因**：开发者将测试写成线性的操作序列，没有标注阶段。
|
||
|
||
**修复**：将逻辑阶段包裹在 `test.step()` 中。步骤会出现在 trace、报告和错误信息中。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——30 行操作，没有结构
|
||
test("bad: flat checkout flow", async ({ page }) => {
|
||
await page.goto("/products")
|
||
await page.getByRole("button", { name: "Add Widget" }).click()
|
||
await page.getByRole("link", { name: "Cart" }).click()
|
||
await page.getByRole("button", { name: "Checkout" }).click()
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Address").fill("123 Test St")
|
||
await page.getByRole("button", { name: "Continue" }).click()
|
||
await page.getByLabel("Card number").fill("4242424242424242")
|
||
await page.getByRole("button", { name: "Pay" }).click()
|
||
await expect(page.getByText("Order confirmed")).toBeVisible()
|
||
})
|
||
|
||
// 正确做法——逻辑步骤，在 trace 和报告中清晰可见
|
||
test("good: structured checkout flow", async ({ page }) => {
|
||
await test.step("add item to cart", async () => {
|
||
await page.goto("/products")
|
||
await page.getByRole("button", { name: "Add Widget" }).click()
|
||
await expect(page.getByTestId("cart-count")).toHaveText("1")
|
||
})
|
||
|
||
await test.step("proceed to checkout", async () => {
|
||
await page.getByRole("link", { name: "Cart" }).click()
|
||
await page.getByRole("button", { name: "Checkout" }).click()
|
||
await expect(page).toHaveURL(/.*checkout/)
|
||
})
|
||
|
||
await test.step("fill shipping details", async () => {
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Address").fill("123 Test St")
|
||
await page.getByRole("button", { name: "Continue" }).click()
|
||
})
|
||
|
||
await test.step("complete payment", async () => {
|
||
await page.getByLabel("Card number").fill("4242424242424242")
|
||
await page.getByRole("button", { name: "Pay" }).click()
|
||
await expect(page.getByText("Order confirmed")).toBeVisible()
|
||
})
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
test("good: structured checkout flow", async ({ page }) => {
|
||
await test.step("add item to cart", async () => {
|
||
await page.goto("/products")
|
||
await page.getByRole("button", { name: "Add Widget" }).click()
|
||
await expect(page.getByTestId("cart-count")).toHaveText("1")
|
||
})
|
||
|
||
await test.step("proceed to checkout", async () => {
|
||
await page.getByRole("link", { name: "Cart" }).click()
|
||
await page.getByRole("button", { name: "Checkout" }).click()
|
||
})
|
||
|
||
await test.step("fill shipping details", async () => {
|
||
await page.getByLabel("Email").fill("user@test.com")
|
||
await page.getByLabel("Address").fill("123 Test St")
|
||
await page.getByRole("button", { name: "Continue" }).click()
|
||
})
|
||
|
||
await test.step("complete payment", async () => {
|
||
await page.getByLabel("Card number").fill("4242424242424242")
|
||
await page.getByRole("button", { name: "Pay" }).click()
|
||
await expect(page.getByText("Order confirmed")).toBeVisible()
|
||
})
|
||
})
|
||
```
|
||
|
||
当某一步失败时，错误信息会包含步骤名称：`Error in step "complete payment": ...`。这比只有行号要有用得多。
|
||
|
||
---
|
||
|
||
## 陷阱 20：捕获断言错误（在 `expect` 外围使用 try/catch）
|
||
|
||
**症状**：本应失败的测试却通过了。断言错误被静默吞掉。真正的缺陷未被发现。
|
||
|
||
**原因**：开发者将断言包裹在 try/catch 中，用于处理"可选"元素或实现条件逻辑。这违背了断言的目的。
|
||
|
||
**修复**：对非关键检查使用 `expect.soft()`，对不存在元素使用 `.not` 断言，或重构测试以避免条件逻辑。
|
||
|
||
**TypeScript**
|
||
|
||
```typescript
|
||
import { test, expect } from "@playwright/test"
|
||
|
||
// 错误做法——吞掉了真正的失败
|
||
test("bad: try/catch around assertion", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
|
||
try {
|
||
await expect(page.getByRole("alert")).toBeVisible({ timeout: 2_000 })
|
||
// 如果 alert 存在则关闭它
|
||
await page.getByRole("button", { name: "Dismiss" }).click()
|
||
} catch {
|
||
// Alert 没有出现——没关系
|
||
}
|
||
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
|
||
// 正确做法——通过计数判断元素是否存在，无需 try/catch
|
||
test("good: conditional without try/catch", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
|
||
// 如果存在 alert 横幅，则关闭它
|
||
const alertCount = await page.getByRole("alert").count()
|
||
if (alertCount > 0) {
|
||
await page.getByRole("button", { name: "Dismiss" }).click()
|
||
await expect(page.getByRole("alert")).not.toBeVisible()
|
||
}
|
||
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
|
||
// 正确做法——对非关键检查使用软断言
|
||
test("good: soft assertions for nice-to-have checks", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
|
||
// 这些是参考信息——即使失败，测试也会继续
|
||
await expect.soft(page.getByTestId("revenue")).toContainText("$")
|
||
await expect.soft(page.getByTestId("users")).toContainText("active")
|
||
|
||
// 这才是真正的断言——如果失败，测试会失败
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
|
||
// 正确做法——断言元素不存在（无需 try/catch）
|
||
test("good: assert absence directly", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
|
||
// 这会自动重试直到错误消失（或超时）
|
||
await expect(page.getByRole("alert")).not.toBeVisible()
|
||
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
```
|
||
|
||
**JavaScript**
|
||
|
||
```javascript
|
||
const { test, expect } = require("@playwright/test")
|
||
|
||
// 正确做法——无需 try/catch 的条件判断
|
||
test("good: conditional without try/catch", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
|
||
const alertCount = await page.getByRole("alert").count()
|
||
if (alertCount > 0) {
|
||
await page.getByRole("button", { name: "Dismiss" }).click()
|
||
await expect(page.getByRole("alert")).not.toBeVisible()
|
||
}
|
||
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
|
||
// 正确做法——对非关键检查使用软断言
|
||
test("good: soft assertions for nice-to-have checks", async ({ page }) => {
|
||
await page.goto("/dashboard")
|
||
|
||
await expect.soft(page.getByTestId("revenue")).toContainText("$")
|
||
await expect.soft(page.getByTestId("users")).toContainText("active")
|
||
|
||
await expect(page.getByRole("heading")).toHaveText("Dashboard")
|
||
})
|
||
```
|
||
|
||
**规则**：如果你发现自己在 `expect()` 外围写 `try/catch`，说明测试设计有问题。重新考虑断言方式。
|
||
|
||
---
|
||
|
||
## 快速查阅表
|
||
|
||
| # | 陷阱 | 一句话修复 |
|
||
| --- | ------------------------------------- | ------------------------------------------------------------------------ |
|
||
| 1 | `waitForTimeout()` | 替换为 `expect(locator).toBeVisible()` |
|
||
| 2 | 缺少 `await` | 添加 `await` + 启用 `no-floating-promises` ESLint 规则 |
|
||
| 3 | CSS 选择器 | 使用 `getByRole()`、`getByLabel()`、`getByTestId()` |
|
||
| 4 | `isVisible()` 检查 | 使用 `expect(locator).toBeVisible()` |
|
||
| 5 | 共享可变状态 | 使用测试作用域的 fixture 配合唯一数据 |
|
||
| 6 | 硬编码 URL | 在配置中设置 `baseURL`，使用相对路径 |
|
||
| 7 | `page.$()` / `page.$$()` | 使用 `page.locator()` 或 `page.getByRole()` |
|
||
| 8 | 未处理导航 | 表单提交后添加 `page.waitForURL()` |
|
||
| 9 | CI 中未配置 `webServer` | 添加 `webServer` 配置，设置 `reuseExistingServer: !process.env.CI` |
|
||
| 10 | `innerHTML` / `textContent` | 使用 `expect(locator).toHaveText()` |
|
||
| 11 | 过度 mock 自己的 API | 只 mock 外部服务 |
|
||
| 12 | 未使用 `test.describe` | 对相关测试分组，限定 `beforeEach` 和 `test.use()` 的作用域 |
|
||
| 13 | 使用 `beforeAll` 做逐测试设置 | 使用 `beforeEach` 或测试作用域的 fixture |
|
||
| 14 | 模块级测试数据变量 | 在每个测试内部或通过 fixture 创建数据 |
|
||
| 15 | `describe` 嵌套过深（3 层以上） | 最多 2 层；拆分为独立文件 |
|
||
| 16 | 所有环境使用相同重试次数 | `retries: process.env.CI ? 2 : 0` |
|
||
| 17 | 每次 PR 都跑所有浏览器 | PR 中只跑 Chromium，全矩阵在夜间运行 |
|
||
| 18 | 过度使用 `page.evaluate()` | 使用定位器方法；将 `evaluate` 留给 JS API |
|
||
| 19 | 未使用 `test.step()` | 将逻辑阶段包裹在命名步骤中 |
|
||
| 20 | 在 `expect` 外围使用 `try/catch` | 使用 `expect.soft()`、`.not` 或 `locator.count()` |
|
||
|
||
## 相关文档
|
||
|
||
- [core/locators.md](locators.md) —— 定位器策略层级（陷阱 3、7、18）
|
||
- [core/assertions-and-waiting.md](assertions-and-waiting.md) —— web 优先断言（陷阱 1、4、10、20）
|
||
- [core/fixtures-and-hooks.md](fixtures-and-hooks.md) —— fixture 与钩子（陷阱 5、13、14）
|
||
- [core/configuration.md](configuration.md) —— baseURL、webServer、重试（陷阱 6、9、16、17）
|
||
- [core/test-organization.md](test-organization.md) —— describe 块、嵌套、标签（陷阱 12、15）
|
||
- [core/flaky-tests.md](flaky-tests.md) —— 诊断与修复不稳定测试（陷阱 1、2、5）
|
||
- [core/debugging.md](debugging.md) —— trace、UI 模式、page.pause()（陷阱 16、19）
|