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

本文适合正在使用或准备使用 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 流水线的焦虑逐渐消失，发版变成例行公事。