Playwright 九大最佳实践与常见陷阱

本文依据官方文档整理，未执行运行验证或性能基准。代码片段展示局部用法，业务函数、数据和环境需按项目补齐；版本与配置以所引文档为准。

直接回答：提升 Playwright 测试的可靠性与效率，关键在于九条实践：先定覆盖目标、用稳定选择器、保持用例聚焦隔离、从用户视角断言、起好标题、覆盖相关浏览器、自动化并监控测试、善用官方工具链、不要测试第三方集成。

1. 先定覆盖目标

E2E 测试慢且贵，不可能覆盖一切。先列出"挂了就等于事故"的核心链路——注册登录、下单支付、核心报表——把测试预算集中在这里。边缘交互交给单元与组件测试，避免金字塔倒置。

2. 用稳定的选择器

// 好：语义化、不怕样式调整
page.getByRole("button", { name: "提交订单" });
page.getByTestId("checkout-submit");

// 坏：DOM 结构一变就碎
page.locator("div > div:nth-child(3) > button.btn-primary");

优先级：role/label 等语义定位 > data-testid > CSS/XPath。语义选择器还能倒逼可访问性改善，一举两得。

3. 用例聚焦且隔离

每条测试只验证一件事，并且自带数据、互不依赖：

• 每条用例用独立的测试账号/数据，跑完即清；
• 拒绝"用例 B 依赖用例 A 创建的数据"——并行执行时必炸；
• 善用 beforeEach 和 API 级别的数据准备，别什么都走 UI。

4. 从用户视角写断言

// 好：断言用户能看到的结果
await expect(page.getByText("订单提交成功")).toBeVisible();

// 坏：断言实现细节
expect(await page.evaluate(() => window.store.order.status)).toBe("done");

用户不关心内部状态，关心页面呈现。断言越贴近真实体验，回归发现的价值越高。

5. 标题即文档

test("未登录用户访问结算页应跳转登录页", async ({ page }) => { ... });

半年后测试失败时，一个说人话的标题能让接手者秒懂意图；test("checkout works") 缺少业务语义。标题是失败报告中最重要的定位线索之一，把它当文档写。

6. 覆盖相关浏览器矩阵

Playwright 一套 API 跑 Chromium、Firefox、WebKit。在 playwright.config.ts 的 projects 里配置真实用户使用的浏览器组合；移动端占比高的业务别忘加移动视口配置。CI 上可以主浏览器全量、其余浏览器跑核心集，平衡速度与覆盖。

7. 自动化并持续监控

测试只在本地跑等于没写：挂进 CI 做合并门禁；关键链路测试还可以定时在生产环境执行（合成监测思路），用真实环境验证"注册→登录→核心操作"是否始终可用，有助于发现特定路径问题，但不能保证先于所有用户。生产用专用最小权限测试账号、沙箱依赖与可清理数据，避免绕过验证码或MFA。

8. 善用官方工具链

• UI 模式（--ui）：时间旅行调试，逐帧回看测试执行；
• Trace Viewer：失败用例的完整现场——截图、DOM 快照、网络请求；
• Codegen：npx playwright codegen 录制操作生成脚本草稿；
• 自动等待与重试断言：expect(locator).toBeVisible() 内置轮询，消灭手写 sleep。

9. 区分隔离测试与第三方契约验证

支付网关、验证码、OAuth 提供商的可用性不归你管。在测试中 Mock 或走沙箱模式；直接打真实第三方会让测试又慢又脆，还可能产生真实费用。隔离测试验证自己的响应处理；真实第三方契约另用经授权的沙箱测试验证，Mock 通过不代表生产集成一定可用。

常见问题（FAQ）

Q：测试总是偶发失败（flaky）怎么办？
A：常见原因包括不当等待和共享状态：把手写 sleep 换成自动等待断言；检查是否依赖了测试间共享状态；CI 上开启重试只是止血，根治还是要消除不确定性来源。

Q：data-testid 会不会污染生产代码？
A：影响微乎其微，且换来测试稳定性大幅提升。如果在意，构建时可通过插件剥离。

Q：E2E 测试多少条算合理？
A：没有标准数，经验值是"核心链路全覆盖 + 每条链路主路径与关键分支"，不要按固定数量规划。关键指标是：失败时能否快速定位、全量跑完是否在可接受时间内（一般不超过 20 分钟）。

官方参考

• 官方文档 1
• 官方文档 2

资料核对日期：2026-09-29。

延伸阅读

• Node.js 内置测试运行器入门指南
• Playwright 端到端测试实战指南