GitLab Runner: 使用 Testcontainers 執行測試

此文件屬於建立 Docker 映像檔指南的一部分。請在此處查看完整指南：使用 Stackhero runner 及 Docker-in-Docker，從您的 GitLab CI/CD pipeline 高效地建構及推送 Docker 映像檔。

👋 歡迎瀏覽 Stackhero 文件！

Stackhero 提供簡單易用的 GitLab Runner cloud 方案，讓您高效且輕鬆地執行 GitLab CI/CD 任務。您可以享有以下優勢：

• 無限 CI/CD 分鐘數：隨時隨地運行 pipeline，無需按分鐘計費，亦無額外收費。
• 多個並行任務：可同時運行多個 job，加快開發流程。
• 支援 Docker executor 及 Docker-in-Docker：輕鬆於 CI/CD 流程中建構及推送 container image。
• 完美兼容 GitLab.com 及 自建 GitLab 實例。
• 專屬私人基礎設施，配備高速 NVMe/SSD 儲存，確保建構效能穩定且可預測。
• 服務覆蓋 🇪🇺 歐洲 及 🇺🇸 美國 地區，靈活配合您的團隊需求。

節省時間：您只需數分鐘即可連接首個 GitLab Runner，立即開始運行 pipeline！

Testcontainers 是一個測試函式庫，支援 Java、Go、Node.js、Python、.NET 等語言，能在測試期間以臨時 Docker container 啟動真實服務。您的整合測試不需模擬資料庫或 message broker，而是直接連接到真正的 PostgreSQL、MySQL、Redis 或 Kafka 實例，測試前建立、測試後自動移除。這在 Java 及 Spring 專案中特別受歡迎。

Testcontainers 需要 Docker daemon，因此可直接採用上述 Docker-in-Docker 設定，無需額外變數：

test:
  stage: test
  # 請使用測試所需的 image（此處為 JDK），不一定要用 docker image：
  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 來尋找 daemon，並重用 docker 這個 hostname 來連接它啟動的 container 所開放的 port。這兩者都能正常運作，因為 docker alias 會在您的 job 網絡上解析。

請務必在 Testcontainers 的 job 中保留 DOCKER_HOST。若未設定，Testcontainers 會退回 runner 掛載的 Docker socket，然後嘗試用 host IP 連接您的測試 container，但 job 並無法連線。常見症狀包括 Ryuk helper container 出現 Wait strategy failed. Container is removed 或 Timed out waiting for log output matching '.*Started.*'。