TestContainer 사용 시 CI 실패 이슈(DockerClientProviderStrategy)

 

 

로컬에서는 잘 돌아가는 테스트가 CI에서만 터지기 시작했다.

 

✔️ 테스트 환경

- 실행 환경: github 가상 머신, ubuntu-latest 이미지 사용

- 실패하는 테스트: TestContainer를 이용한 테스트

TestContainer는 테스트를 위해 docker 컨테이너를 사용하고, 우리 테스트에서는 MySQL 컨테이너를 사용한다.

@TestConfiguration
public class TestContainerConfig {

    @Bean
    @ServiceConnection
    public MySQLContainer<?> mySQLContainer() {
        return new MySQLContainer<>("mysql:8.0.42")
                .withUsername("root")
                .withPassword("rootpwd")
                .withDatabaseName("test_db");
    }
}

✔️ 발생 에러

Caused by: java.lang.IllegalStateException at DockerClientProviderStrategy.java

 

 

DockerClientProviderStrategy는 TestContainer에서 사용할 Docker 환경을 구축하기 위해 사용하는 클래스다. 여기서 예외가 발생했기에 도커 환경을 구축하는데에 문제가 생긴 상황으로 유추할 수 있다.

✔️ 문제 원인 파악하기

이전에는 성공했던 CI도 다시 돌려보니 실패했고, 코드 변경때문이 아니라 테스트를 위해 의존하는 외부 환경에 변경사항이 있어서 실패했다는 것을 알 수 있었다.

https://github.com/actions/runner-images/issues/13474

 

찾아보니 docker 엔진 관련 업데이트 사항이 있었다. 프로젝트에서 사용하던 Github Actions의 ubuntu-latest(24.04) 이미지에 26년 2월 9일부터 Docker 엔진 29.1.* 버전을 사용한다고 나와있었다.

 

그리고 Docker 29.1.* 버전에서는 Docker API의 최소 버전이 1.44로 설정된다.

 

 

DockerClientProviderStrategy에서 Docker API 버전을 감지하지 못한 경우 1.32로 설정하는 것을 확인할 수 있다. 따라서 Github Actions에서 사용하는 Docker 엔진이 제공하는 Docker API 최소 버전은 1.44인데, 테스트코드에서는 Docker API 1.32 버전을 사용하기에, 버전 호환성 문제로 CI가 실패했던 것이다.

 

문제 원인을 아래와 같이 정리할 수 있다.

 

1. Testcontainers가 Docker 29 데몬에 연결

2. DockerClientProviderStrategy에서 API 버전 자동 감지 시도

3. 감지 실패

4. Fallback으로 1.32 사용

5. Docker 29는 최소 1.44 요구

6. 버전 불일치로 CI 실패

✔️ 문제 해결하기

1) CI 스크립트에서 Docker API 버전 고정

- name: Force Docker API Version
  run: echo 'api.version=1.44' > ~/.docker-java.properties

 

첫 번째 해결 방법은 CI 스크립트에서 Docker api 버전을 고정시키는 것이다. 이렇게 할 경우 TestContainer는 Docker API 1.44 버전을 사용하게 된다.

 

2) TestContainer 버전 업그레이드

 

두 번째 해결 방법은, TestContainer 버전을 올리는 것이다. 우리가 사용하는 SpringBoot 3.5.3 버전은 TestContainer 1.21.2 버전을 사용하고 있었다.

 

https://github.com/testcontainers/testcontainers-java/pull/11216

 

위 이슈에 의하면 TestContainer 2.0.2 버전부터는 Docker API 디폴트 버전이 1.44로 설정된다. 따라서 TestContainer를 2.0.2 이상으로 업그레이드하면, Docker 29에 호환되는 api 버전을 디폴트로 사용할 수 있다.

testImplementation "org.springframework.boot:spring-boot-testcontainers"
testImplementation "org.testcontainers:testcontainers-junit-jupiter:2.0.2"
testImplementation "org.testcontainers:testcontainers:2.0.2"
testImplementation "org.testcontainers:testcontainers-mysql:2.0.2"

✔️ 마무리

프로젝트는 dev, prod 환경과 app, admin 모듈에 대한 워크플로우가 별도로 존재하기 때문에, 총 4곳에 해당 스크립트를 수정하는 방법 대신 TestContainer 버전을 높이는 방법을 선택했다.

 

처음에 CI 실패 로그를 긁어서 클로드에게 물어봤는데, 처음부터 명확한 해결방법을 얻을 수 없었다. 그래서 Docker, TestContainer 레포를 확인해보니 같은 이슈를 겪는 사용자들이 문제 원인과 해결 방법을 올려놓은 것을 확인할 수 있었다.