GitLab Runner: 使用 Testcontainers 运行测试

本文件是构建 Docker 镜像指南的一部分。您可以在这里查看完整指南：使用 Stackhero runner 和 Docker-in-Docker，从您的 GitLab CI/CD 流水线高效构建并推送 Docker 镜像。

👋 欢迎来到 Stackhero 文档！

Stackhero 提供简单易用的 GitLab Runner cloud 解决方案，让您高效、无忧地运行 GitLab CI/CD 任务。您可以获得：

• 无限制 CI/CD 构建时长：随时运行您的流水线，无需按分钟计费，也没有额外费用。
• 多任务并发执行：支持同时运行多个任务，加快开发进度。
• 支持 Docker executor 及 Docker-in-Docker：轻松在 CI/CD 流程中构建和推送容器镜像。
• 与 GitLab.com 及 自建 GitLab 实例无缝兼容。
• 专属私有基础设施，配备高速 NVMe/SSD 存储，确保构建性能稳定可预期。
• 服务覆盖 🇪🇺 欧洲 和 🇺🇸 美国 区域，满足您团队的需求。

节省时间：您只需几分钟即可连接第一个 GitLab Runner，立即开始运行流水线！

Testcontainers 是一个测试库，支持 Java、Go、Node.js、Python、.NET 等多种语言，可以在测试运行期间以临时 Docker 容器的方式启动真实服务。与其模拟数据库或消息中间件，不如让集成测试直接连接真正的 PostgreSQL、MySQL、Redis 或 Kafka 实例，测试前创建，测试后自动清理。该库在 Java 和 Spring 项目中尤为流行。

Testcontainers 需要 Docker 守护进程，因此其运行方式与上文 Docker-in-Docker 配置完全一致，无需额外变量：

test:
  stage: test
  # 这里请使用测试所需的镜像（如 JDK），不一定要用 docker 镜像：
  image: gradle:jdk21
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  script:
    - gradle test

Testcontainers 通过读取 DOCKER_HOST 找到守护进程，并复用 docker 主机名访问其启动容器所暴露的端口。两者都能独立工作，因为 docker 别名会在作业网络中自动解析。

在 Testcontainers 作业中请保留 DOCKER_HOST。如果未设置，Testcontainers 会回退到 runner 挂载的 Docker socket，然后尝试通过主机 IP 访问测试容器，但作业无法连接到该地址。常见症状包括 Ryuk 辅助容器报错 Wait strategy failed. Container is removed 或 Timed out waiting for log output matching '.*Started.*'。