Playwright 稳定性的十个细节:等待、选择器与 flaky 治理
稳定性不是靠加 sleep 堆出来的,而是把不确定性一个个消掉。十个细节里最贵的是拿 networkidle 当同步点,它让用例在本地很快、在 CI 上随机超时。我现在的基线是 playwright@1.61.1、retries=0 下通过率 99% 以上,重试只作为兜底而不是遮羞布。
一、flaky 是分布问题,先量化再谈治理
一个用例跑 100 次失败 3 次,多数人的反应是“偶发,重跑一下”。3% 的失败率意味着每天跑 200 次会有 6 次红灯,团队很快就开始无视告警。我的做法是先量化:用 npx playwright test --repeat-each=20 --workers=4 把同一批用例重复跑,统计每个用例的失败率,把大于 1% 的全部拉进治理清单。
重试会掩盖真实失败率。配置 retries: 2 之后,一个 3% 失败率的用例最终失败概率降到万分之三,看起来绿了,但它每次都在消耗一倍的重试时间,而且真正的缺陷还埋在那里。所以我的 CI 分两个流水线:主干用 retries: 0 跑全量,量化真实通过率;合并请求用 retries: 1 保证不阻塞,但失败用例必须进清单。
判断标准也要改。不要问“这个用例稳不稳”,要问“它在 4 核 CI 机器、4 个 worker 并行、冷缓存的情况下稳不稳”。本地 16 核、单 worker、热缓存跑出来的绿色没有参考价值。
二、等待分三层,networkidle 一层都不属于
Playwright 的等待机制我分成三层。第一层是 actionability check,点击之前自动等元素可见、稳定(连续两帧位置不变)、能接收事件、未被禁用,这一层是内置的,不需要你写任何等待。第二层是断言轮询,expect(locator).toBeVisible() 默认 5 秒内反复检查,失败时报出最后一次的实际状态。第三层是业务信号,比如等某个接口返回 200、等列表行数从 0 变成 10。
networkidle 不属于任何一层。它的定义是 500 毫秒内没有网络请求,而现在的 SPA 普遍有轮询、埋点、WebSocket 心跳,永远不会有 500 毫秒的静默期。用它当同步点,结果就是在本地勉强能过、在 CI 上必超时。我把它从配置里彻底禁掉,代码评审看到就退回。
真正需要等接口的地方,用 page.waitForResponse 并且匹配具体的 URL 和状态码,不要匹配 /api/ 这种宽泛前缀。更稳的做法是先注册等待再触发动作,顺序反了就会漏掉快速返回的响应。
// 先挂等待,再点击,避免响应比监听更快
const respPromise = page.waitForResponse(
(r) => r.url().includes('/api/orders') && r.status() === 200,
{ timeout: 15_000 },
);
await page.getByRole('button', { name: '查询' }).click();
const resp = await respPromise;
expect(await resp.json()).toMatchObject({ total: expect.any(Number) });
三、选择器按优先级选,别从 CSS 开始写
选择器的优先级我固定为:role 大于 label 大于 testid 大于 CSS,xpath 和 nth(0) 基本不用。getByRole('button', { name: '提交' }) 同时验证了语义和文案,重构 DOM 结构不会挂,只有产品改文案才会挂,而改文案本来就该让人 review 到。
nth(0) 是最隐蔽的坑。列表顺序变了、加了一个隐藏的模板行、接口返回顺序不稳定,都会让 nth(0) 指到别的元素,而报错信息往往只说“元素不可见”,排查要花很久。确实需要按位置取,我改用 filter({ hasText }) 或者给容器加 data-testid。
data-testid 要写到组件里,不要靠运行时注入。我见过在 CI 里用脚本给所有按钮批量加属性的做法,本地和 CI 的 DOM 不一致,问题只会更难查。
四、隔离和并行:一个用例一个 context
Playwright 的默认模型是每个 test 一个 browser context,context 之间 cookie、localStorage、缓存全部隔离。这个隔离必须保住,不要为了省登录时间让所有用例共享一个 page。共享 page 带来的问题是:上一个用例的弹窗没关、滚动位置没复位、路由还停在上一个页面,失败信息全部指向下一个用例。
并行度不是越高越好。4 核机器上 workers: 4 是甜点,调到 8 之后上下文切换和内存压力会让单个用例耗时上升 30% 以上,整体反而更慢。我一般按 CPU 核数 设,CI 机器 4 核就 4 个 worker,本地开发可以开到 8。
登录态用 storageState 复用,但要注意并发写。如果测试会修改用户资料、下单、改密码,就不能共用一个账号,否则用例之间互相污染。这类场景我给每个 worker 分配独立账号,用 process.env.TEST_USER_${testInfo.parallelIndex} 取。
五、配置基线:超时、trace、视频三件事
超时我分三层设:全局 timeout: 30_000,单个 action actionTimeout: 15_000,断言 expect: { timeout: 5_000 }。全局超时是兜底,不该经常触发;断言 5 秒是给动画和接口留的余量,超过 5 秒还没出现,多半是逻辑问题而不是慢。
trace 只在第一次重试时开。全量开 trace 会让一次运行产生几个 GB 的文件,CI 磁盘顶不住;只在失败时开又经常错过现场。trace: 'on-first-retry' 是个折中,代价是首次失败没有 trace,但重试通常会复现。
视频用 retain-on-failure,截图用 only-on-failure。这两个加起来能让 80% 的失败在看完录像后直接定位,不需要本地复现。
| 症状 | 根因 | 修法 |
|---|---|---|
| 本地过、CI 超时 | 用 networkidle 等 SPA | 改成 waitForResponse 匹配具体接口 |
| 元素不可见,但截图里有 | 动画未结束就断言 | 用 expect 轮询,关掉入场动画 |
| 偶发点到错误的行 | nth(0) 依赖列表顺序 | 改 getByRole 加 filter |
| 用例互相污染 | 共享 page 或共享账号 | 每 test 独立 context,按 worker 分账号 |
| 重试后必过,首跑必挂 | 冷缓存、字体未加载 | 预热路由,等 fonts.ready |
| 报告里全是超时,没有堆栈 | 全局 timeout 太小 | 分层设超时,开 trace |
六、落地节奏
- 先跑一遍
--repeat-each=20,拿到真实的失败率分布,不要凭感觉挑用例。 - 全局搜索
networkidle、waitForTimeout、nth(,这三个是 flaky 的主要来源,逐个替换。 - 把
retries在主干设为 0,合并请求设为 1,两套流水线分开统计。 - 补齐
trace、video、screenshot的失败留存,先保证能查,再谈修。 - 每周review 一次 flaky 清单,超过 1% 的用例当缺陷修,不要长期挂着重试。
十个细节说到底是一句话:让每一步等待都有明确的信号来源。信号来自 DOM 状态、来自接口响应、来自业务数据,就是不来自“睡 2 秒应该够了”。
- 点赞
- 收藏
- 关注作者
评论(0)