自动化测试 / 系统课时
排查 CI 环境故障
排查 CI 环境故障
CI 中的 Playwright 故障常常不是测试逻辑本身,而是运行器与本地环境不一致。排查时应先证明浏览器能启动,再检查环境变量与写权限,最后才处理超时和并发,避免用“加大超时”掩盖真正的资源或依赖问题。
学习目标
- 按固定顺序区分浏览器依赖、权限、环境变量、超时与资源竞争问题
- 用最小诊断脚本验证 CI 运行器是否具备执行 Playwright 的基本条件
- 通过单 worker 对照实验判断并发是否是失败诱因
先缩小故障边界
看到“本地通过、CI 失败”时,不要先改断言。更高效的顺序是:运行时版本与浏览器 → 必需环境变量 → 工作目录权限 → 单进程执行 → 超时与并发资源。这个顺序能把基础环境问题和测试逻辑问题分开。

最关键的原则是先找第一个确定失败的层级。例如浏览器进程根本启动不了时,继续分析 Locator 或断言没有意义;环境变量缺失时,重复执行只会得到相同错误。
用最小脚本验证运行器
下面的诊断脚本不访问业务站点,只检查三个基础条件:BASE_URL 是否注入、当前工作目录是否可写、Chromium 是否能够真正启动。保存为 ci-diagnose.mjs。
import fs from 'node:fs/promises';
import path from 'node:path';
import { chromium } from '@playwright/test';
if (!process.env.BASE_URL) {
throw new Error('BASE_URL is required');
}
console.log('env=ok');
const probe = path.join(process.cwd(), '.ci-write-probe');
await fs.writeFile(probe, 'ok');
await fs.unlink(probe);
console.log('workspace=writable');
const browser = await chromium.launch();
console.log(`browser=${await browser.version()}`);
await browser.close();运行诊断:
node ci-diagnose.mjs预期输出:
env=ok
workspace=writable
browser=<VALUE><VALUE> 会随运行器而变化。若脚本在启动浏览器时报 executable missing 或缺少系统库,应先补齐 Playwright 浏览器与系统依赖;若在写探针文件时报权限错误,应修正工作目录或运行用户权限;若直接提示 BASE_URL is required,说明 CI 没有正确注入变量。脚本只检查变量是否存在,不打印变量值,避免把 Secret 写进日志。
用单 worker 判断资源竞争
浏览器可以启动、变量和权限都正常后,再做并发对照。先把同一套测试临时降到一个 worker:
npx playwright test --workers=1预期输出:
<VALUE> passed (<TIME>)测试数量和耗时会因项目而异。若单 worker 稳定、恢复并发后随机失败,优先检查 CPU/内存不足、共享账号、共享测试数据、固定端口或同一文件被多个 worker 同时修改,而不是立即增加重试次数。
处理超时要看等待发生在哪一层
Playwright 的失败“看起来像超时”时,需要区分是测试总超时、动作等待、断言等待,还是业务系统本身响应慢。若日志总是在相近时间点失败,应查看错误堆栈中真正超时的 API,再决定是否调整等待方式。
优先使用 Locator 断言和 Playwright 自带等待机制,避免把固定 waitForTimeout 当成稳定性方案。固定睡眠只会延长正常路径,并不能保证慢环境一定准备完成。
如果仅 CI 慢,可先降低并发、确认依赖服务健康,再针对已证实的慢操作调整超时。只有在资源、网络和业务响应都合理后,超时参数才应该作为最后的容量调节手段。
修复后必须保留失败证据
修复完成后至少再跑一次原 CI 路径,而不是只在本地复现。测试报告、失败截图和 trace 应作为流水线产物保留,便于下一次直接比较。
当最小诊断脚本、单 worker 对照和原 CI 流程都通过时,才能认为故障已经闭环;否则“偶尔通过”仍属于未解决的环境不稳定问题。