GitLab Pipeline运行基于Selenium的TestCafe测试报超时错误

架构老林

2026-9-1

问题根因

这个net::ERR_CONNECTION_TIMED_OUT错误的核心原因是Selenium Grid节点拉起的Chrome浏览器无法反向连接TestCafe Runner的内置服务。
TestCafe对接Selenium Grid的通信逻辑不是Runner单向调用Grid接口：Grid在节点上启动Chrome实例后，Chrome需要主动回连TestCafe Runner暴露的HTTP服务，拉取测试脚本、上报执行状态。本地运行时Runner和浏览器处于同一可直达网络，所以不会出问题；GitLab Pipeline环境下这条回连通路被阻断，就会报连接超时，也就是你看到的Chrome能拉起但测试不启动的现象。

排查步骤

先确认TestCafe的对外监听地址：检查testcafe_runner.js中是否手动指定了hostname参数。默认配置下TestCafe会自动探测本机IP作为回连地址，在CI环境（容器/Shell执行器）中很容易拿到docker内网IP、回环地址这类Selenium节点无法路由的无效地址。
直接验证连通性：TestCafe启动时会在控制台打印监听地址，在任意Selenium Grid节点上直接curl这个地址（路径一般是/browser/connect），如果curl超时就是网络层不通。
检查访问控制规则：核对GitLab Runner所在机器的防火墙、云服务器安全组配置，确认没有拦截Selenium节点网段的入站请求。
核对CI配置一致性：你当前Job配置同时打了shell-executor标签和image字段，Shell执行器不会读取image配置，会直接使用宿主机的Node环境，要确认实际运行TestCafe的环境和Grid节点的网络连通状态，避免环境错配。

修复方案

手动指定TestCafe的可路由监听地址：在testcafe_runner.js的初始化逻辑中，把hostname参数设置为GitLab Runner机器上Selenium Grid节点可直接访问的内网IP/域名，禁止使用127.0.0.1、docker0网桥网段这类不可跨机路由的地址，同时固定监听端口方便配置防火墙规则，参考代码：

const createTestCafe = require('testcafe');
// 替换为GitLab Runner对Grid节点可访问的实际内网IP
const RUNNER_HOST = '192.168.1.xx';
// 固定端口，避免随机端口每次都要调整防火墙规则
const RUNNER_PORT = 1337;

createTestCafe(RUNNER_HOST, RUNNER_PORT, RUNNER_PORT + 1)
  .then(testcafe => {
    const runner = testcafe.createRunner();
    return runner
      .src('./testcases/**/*.js') // 替换为实际测试用例路径
      .browsers('selenium:chrome')
      .run({
        browserInitTimeout: 120000 // 浏览器启动超时调整为2分钟，适配高延迟网络场景
      });
  });

放开网络访问限制：在GitLab Runner所在机器的防火墙、安全组中，放开上面配置的TestCafe监听端口（示例中是1337、1338两个端口），允许所有Selenium Grid节点的IP段入站访问。
修正CI执行器配置：如果使用Docker执行器运行Job，把Job的tags改为对应Docker执行器的标签，提前确认Docker容器网络和Selenium Grid网络打通；如果使用Shell执行器，直接删除image字段，在Runner宿主机上提前安装匹配版本的Node.js和项目依赖，避免环境不一致问题。
升级兼容依赖版本：你当前使用的testcafe-browser-provider-selenium@1.2.0存在CI环境下IP自动探测错误的已知问题，升级到1.3.0及以上版本，同时把TestCafe升级到1.19.x及以上版本，减少自动解析地址的逻辑错误。

内容的提问来源于stack exchange，提问作者Maher