如何利用 GitHub Actions 配合浏览器自动化工具执行长路径端到端测试

如何利用 GitHub Actions 配合浏览器自动化工具执行长路径端到端测试并不只看表面做法，关键还要理解相关条件、限制和后续影响。

GitHub Actions中E2E测试失败主因有五：headless配置与驱动缺失、job超时限制、渲染与网络时机差异、截图调试缺失、敏感信息硬编码；需分别配置浏览器启动参数、延长timeout、白名单路由、自动截图存档、使用secrets管理凭证。

GitHub Actions 中启动浏览器失败：headless 模式不兼容或缺失驱动

CI 环境默认没有图形界面，puppeteer 或 playwright 启动 Chromium 时若未显式配置 headless 参数或缺少系统依赖，会直接报错 Failed to launch browser。GitHub-hosted runners（如 ubuntu-latest）虽预装 Chromium，但版本可能滞后，且默认不启用 sandbox，容易 crash。

1. Playwright 用户必须在 workflow 中显式安装对应浏览器：playwright install chromium（推荐用 playwright/action 官方 action，自动处理依赖）
2. Puppeteer 用户需设置 headless: "new" 并禁用 sandbox：args: ["--no-sandbox", "--disable-setuid-sandbox"]
3. 避免硬编码路径——process.env.BROWSER_PATH 在 CI 中不可靠，应交由 Playwright/Puppeteer 自动解析二进制位置

长路径测试超时：action 默认 60 分钟不够用

端到端测试含登录、导航、表单提交、等待异步加载、截图比对等步骤，单次运行常超 10 分钟；而 GitHub Actions 默认 job 超时为 60 分钟，一旦测试用例数增加或网络波动，整个 workflow 就被强制终止，报错 Timeout has been exceeded。

1. 在 job 级别显式声明 timeout-minutes: 90（最大支持 360 分钟，但不建议设满）
2. 对耗时操作加断言超时而非依赖全局 timeout：await page.waitForSelector("#dashboard-loaded", { timeout: 30000 })
3. 避免在测试中调用 page.waitForTimeout(5000) 等固定等待——改用 waitForNavigation 或条件轮询更稳定

本地能跑、CI 报元素找不到：渲染时机与网络策略差异

常见现象是 Waiting for selector ".app-header" failed: timeout 30000ms exceeded。根本原因不是选择器写错，而是 CI 中页面资源加载慢（如第三方 CDN 延迟）、React/Vue 组件挂载延迟、或 GitHub runner 的 DNS 解析策略拦截了某些域名。

1. 在 beforeAll 钩子中统一配置网络拦截白名单：page.route("**/*", route => route.continue())，防止因某张监控图或埋点脚本阻塞主流程
2. 对 SPA 应用，优先等待路由就绪而非 DOM 出现：await page.waitForFunction(() => window.location.pathname === "/dashboard")
3. 截图调试必备：在失败时自动保存 HTML 和截图，用 await page.screenshot({ path: `failure-${Date.now()}.png` }) + await fs.writeFile(`debug.html`, await page.content())

敏感信息泄露风险：不要把 token 或密码写死在测试代码里

测试常需登录态，有人直接在 test 文件里写 await page.fill("#password", "test123")，或从 .env 读取明文密码——这些内容一旦提交，会被 GitHub Actions 日志完整打印，且无法撤回。

1. 所有凭证必须走 secrets：workflow 中用 ${{ secrets.TEST_USER_PASSWORD }}，再通过环境变量传入测试进程
2. 登录逻辑抽离为独立 step，成功后导出 cookie 或 token 到文件，后续步骤用 page.context().addCookies() 复用，避免重复登录
3. 禁止在日志中输出任何含 password、token、auth 字段的响应体——用 console.log("login success") 替代 console.log(response.body())

GitHub Actions 执行长路径 E2E 测试真正难的不是写脚本，而是让每一步失败都能快速定位是环境问题、网络问题，还是应用自身状态异常。尤其要注意 Playwright 的 trace viewer 生成和上传逻辑——它不默认开启，但打开后能还原整个交互链路，比翻日志高效得多。