避开 Playwright 常见坑，让你的 UI 测试跑得又快又稳

hogwarts · 2025 年11 月 16 日 12:45

本文适合正在使用或准备使用 Playwright 做自动化测试的朋友，帮助你避开踩坑，提高测试效率。

近年来，Playwright 作为一款跨浏览器、跨平台的端到端自动化测试框架，越来越多的测试团队选择它替代 Selenium 或 Puppeteer。
它提供了强大的 API 和智能等待机制，但在实际项目中，很多团队仍会遇到各种坑。今天，我们结合行业实践经验，总结 Playwright 最容易踩的坑及解决方案，让你的测试更快、更稳定。

1. 按风险级别组织测试

坑点：按功能模块组织测试会导致发版流水线臃肿，低风险 UI 也占用时间。
解决方案：
- 高风险场景（登录、下单、支付）快速精准覆盖并严格断言。
- 低风险 UI 细节放到夜间全量回归。
- 实践：维护 @smoke 和 @full 标签，冒烟测试每次提交跑，全量回归在夜间或发版前跑。

2. 使用稳定的定位策略

坑点：复杂 CSS 或文本选择器容易导致测试不稳定。
解决方案：
- 优先使用 data-testid，作为代码与测试的契约。
- 在 PR 检查中要求核心 UI 元素必须加测试 ID。

3. 充分利用 Playwright 自动等待

坑点：手写 waitForTimeout 或固定等待时间会导致测试不稳定。
解决方案：
- 使用 Playwright 内置自动等待和 web-first 断言。
- 必要时绑定到明确信号：网络请求、元素出现或 URL 变化，而非毫秒数。

4. 用 fixtures 管理认证和环境状态

坑点：每个测试重新登录导致测试慢且脆弱。
解决方案：
- 使用 storageState 保存登录态，每个测试启动时即登录状态。
- 测试更快、更稳定、可读性更高。

5. 通过 API 准备测试数据

坑点：UI 操作慢且容易失败。
解决方案：
- 优先用后端接口准备测试数据，然后在 UI 验证结果。
- 若无测试专用接口，可创建受控 /api/test/* 命名空间，仅在 CI 环境开启。

6. 控制网络请求，Mock 不可控依赖

坑点：第三方接口不稳定导致测试挂。
解决方案：
- 使用 HAR 文件或 stub 关键接口保证稳定性。
- 保留一套真实环境 Canary 测试监控外部接口变化。

7. 视觉回归测试要有的放矢

坑点：动态区域可能导致大量无用 diff。
解决方案：
- 对动态区域设置 mask 或阈值。
- 从小范围开始（收据、PDF 或核心仪表盘），逐步扩大覆盖面。

8. Trace 和视频只在必要时开启

坑点：全程录制 Trace / 视频浪费时间和存储。
解决方案：
- 仅在测试失败或重试时开启 Trace。
- 保证快速通过，同时失败时有完整信息。

9. 合理设置并发数

坑点：盲目增加并发可能引发资源竞争，反而不快。
解决方案：
- 先 Profile 测试套件，找出瓶颈。
- 只在总耗时确实降低时才增加 worker 数量。

10. 按用户场景组织，别死磕 Page Object

坑点：Page Object 容易臃肿，难维护。
解决方案：
- 采用“剧本式” helper 函数，用稳定定位器组合业务操作。
- 测试代码读起来像讲故事，更直观易懂。

11. 让不稳定性可见

坑点：掩盖不稳定测试会影响主流程的可信度。
解决方案：
- 用注解标记不稳定测试。
- 跟踪每个 spec 文件的不稳定率，超过 1% 就该修复。

12. 优化测试报告

坑点：报告难读、难定位问题。
解决方案：
- 标准化产物命名，突出关键信息：失败步骤、截图、Trace、网络请求。
- 配置 CI，把 HTML 报告和 Trace 暴露为构建产物。
- 定位问题只需两次点击，不搞寻宝游戏。

实战案例

在实际项目中，有团队在使用 Playwright 做 UI 测试时遇到以下问题：

问题：600 多个 UI 测试，跑完 42 分钟，每 5 次 run 就挂 1 次。

通过采纳以下优化措施，取得了显著效果：

核心 UI 元素加 data-testid
API 接口准备测试数据，减少 UI 操作依赖
重试时开启 Trace，方便排查失败
区分 smoke 和 full 测试，合理调度流水线
Worker 数量从 12 降到 6（降低数据库压力）
结果：
- PR 上 12 分钟跑完
- 不稳定率 <0.3%
- 发版再也不用提心吊胆

这一案例展示了合理设计测试策略、优化定位器、使用 API 数据和 Trace 的组合实践，可以显著提升 Playwright 测试的稳定性和效率。

实践流程示意图

写在最后

Playwright 不只是一个测试工具，它是一套 方法论：

风险级别组织测试
稳定选择器 + 自动等待
API 预置数据，Mock 不稳定接口
精准控制 Trace、并发和报告

一次采纳几个习惯，你会发现 CI 流水线的焦虑逐渐消失，发版变成例行公事。

想获取更多 Playwright / 自动化测试实战技巧、案例优化经验，扫码进群，每周更新干货内容，让你的测试更快、更稳、更高效。