GitHub Actions中Testcontainers单元测试连接ArcadeDB失败排查

1. 端口映射与连接地址硬编码 #

如果你的Gremlin连接代码写死了固定端口（比如ArcadeDB默认的8182），会直接导致连接失败——Testcontainers在GitHub Actions环境中会把容器端口映射到主机的随机端口，而非原端口。

• 修复方式：通过Testcontainers API动态获取映射后的端口：

  Integer mappedPort = arcadeDbContainer.getMappedPort(8182);
  String gremlinEndpoint = "ws://localhost:" + mappedPort + "/gremlin";
  

2. localhost解析问题 #

GitHub Actions的Runner本身是容器环境，Testcontainers启动的子容器和Runner处于同一网络，但部分场景下localhost指向的是Runner容器而非Testcontainers子容器，导致连接不到ArcadeDB服务。

• 修复方式：改用容器IP构建连接地址：

  String containerIp = arcadeDbContainer.getContainerIpAddress();
  Integer mappedPort = arcadeDbContainer.getMappedPort(8182);
  String gremlinEndpoint = "ws://" + containerIp + ":" + mappedPort + "/gremlin";
  

3. 未等待服务完全就绪 #

容器日志显示启动完成不代表Gremlin服务已经可连接，Testcontainers默认的等待逻辑可能只检测容器启动，没验证服务就绪。

• 修复方式：添加自定义等待策略，直到Gremlin服务可访问：

  arcadeDbContainer.waitingFor(Wait.forHttp("/gremlin")
                          .forPort(8182)
                          .withMethod(HttpMethod.GET)
                          .withStatusCode(200));
  

  或简单监听端口：

  arcadeDbContainer.waitingFor(Wait.forListeningPort());
  

4. Gradle测试并行执行冲突 #

如果Gradle的check任务启用了并行测试，可能出现测试代码在容器完全就绪前就启动执行的情况。

• 修复方式：在build.gradle中限制测试并行数：

  test {
      maxParallelForks = 1
  }
  

5. Runner资源不足导致启动超时 #

免费的GitHub Actions Runner资源有限，ArcadeDB容器初始化可能较慢，测试代码因超时抛出连接异常。

• 修复方式：延长测试超时时间：

  test {
      timeout = Duration.ofMinutes(10)
  }
  

  若使用自托管Runner，可增加Runner的CPU/内存资源。

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