Playwright无头测试在GitLab中显示空白页，本地运行正常求助

核心现象回顾 #

本地通过Docker Compose启动服务后，Playwright+jest-runner的E2E测试正常，但GitLab CI执行时失败，具体表现：

• domcontentloaded事件触发后无commit事件
• 测试截图为空白页面
• UI容器已正常提供静态文件，无明显连接错误
• Playwright日志显示page.goto成功，且触发了domcontentloaded和networkidle事件

针对性修复方案 #

1. 解决GitLab CI资源不足导致的渲染阻塞 #

GitLab Runner默认资源配额（CPU/内存）远低于本地机器，无头浏览器可能因资源不足无法完成页面渲染：

• 延长Playwright页面加载超时并调整等待策略：

  // playwright.config.js
  module.exports = {
    use: {
      timeout: 60000, // 超时延长至60秒
      waitUntil: 'load' // 改用'load'事件，确保页面所有资源加载完成
    }
  };
  

• 在GitLab CI配置中给Runner分配更多资源：

  # .gitlab-ci.yml
  variables:
    DOCKER_MEMORY: "4g"
  

2. 适配无头浏览器的渲染差异 #

本地可能用有头模式运行，GitLab CI默认无头模式，部分前端逻辑在无头环境下存在兼容问题：

• 临时开启有头模式调试（仅排查问题用）：

  // 测试用例中修改浏览器上下文配置
  await browser.newContext({ headless: false });
  

• 检查前端代码中依赖window、document等浏览器API的逻辑，比如动画、Canvas渲染或第三方库，添加无头环境的兼容处理（比如判断navigator.userAgent是否包含HeadlessChrome）。

3. 修正Docker网络访问路径 #

虽然UI容器能提供文件，但Playwright可能在Docker网络外访问服务导致隐性问题：

• 测试代码中直接使用Docker内部服务地址（比如http://ui:3000而非localhost:3000），确保Playwright在Docker Compose的统一网络内访问UI服务。
• 检查Docker Compose的网络配置，确认所有服务（UI、后端、测试）在同一自定义网络下。

4. 增加页面渲染的显式等待 #

即使networkidle触发，页面可能仍在异步渲染内容，需显式等待核心元素：

// page.goto后添加元素等待逻辑
await page.goto('你的UI地址');
await page.waitForSelector('#app-container', { timeout: 30000 }); // 等待页面根容器出现

额外调试手段 #

• 开启Playwright详细日志和追踪：

  // playwright.config.js
  module.exports = {
    use: {
      trace: 'on-first-retry', // 记录失败用例的完整追踪信息
      logger: {
        isEnabled: () => true,
        log: (name, severity, msg) => console.log(`[${name}] ${severity}: ${msg}`)
      }
    }
  };
  

• 在GitLab CI步骤中输出完整的docker-compose logs，排查UI服务的前端控制台报错（比如JS加载失败、接口请求超时）。

内容的提问来源于stack exchange，提问作者A.Ravi Theja