TestContainer로 통합 테스트 환경 구축하기

[개요]

통합 테스트 환경을 구축할 때, 데이터베이스와의 연동은 주요한 고려사항 중 하나이며, 테스트의 안정성과 신뢰성을 높이기 위해서는 실제 운영 환경과 유사한 데이터베이스 환경에서의 테스트가 필요합니다. 그러나 이러한 환경을 갖추기 위해선 여러 방법이 있고, 각각의 방법은 그 특성과 장단점이 있습니다. 이번 게시글에서는 TestContainer를 이용한 테스트 환경 구축에 대해 알아보겠습니다.

전체 코드는 깃허브에서 확인하실 수 있습니다.
 
 
 

[DB를 테스트 환경에 통합하는 방법]

Local에 실제 DB를 연결하기

Local 환경에 직접 DB를 실행하는 방법은 실제 환경과 유사하게 테스트를 할 수 있는 큰 장점이 있습니다. 그러나 여러 테스트를 동시에 진행하거나 데이터를 관리하는 측면에서 멱등성(idempotencty)을 유지하는 것이 어렵고, 특히 DDL과 관련된 테스트를 진행할 때마다 데이터베이스 초기화와 같은 추가 작업이 필요합니다.

in-memory DB 활용하기

in-momory DB, 예를 들면 H2를 활용하는 방법은 테스트의 속도가 매우 빠르다는 장점이 있습니다. ORM 도구를 통해 특정 DB의 의존성을 줄일 수 있지만, 실제 DB에서 사용하는 특화된 기능이나 DDL에 대한 제약사항이 존재합니다.

Embedded Library 활용하기

Embedded Library는 실제 DB의 코드를 경량화한 형태로 제공하는 라이브러리입니다. 이를 활용하면 in-momory DB에서 겪게 되는 특정 DB의 특화된 기능 테스트의 제약을 극복할 수 있습니다. 

그러나 모든 DB가 Embedded Library를 제공하지 않으며, 지원되는 버전이나 OS에 따라 제한이 있을 수 있으고, 각 DB마다 다른 라이브러리를 가지고 있기 때문에 매번 다르게 구현해야 하는 경우가 있습니다.

https://dealicious-inc.github.io/2022/01/10/test-containers.html

https://dealicious-inc.github.io/2022/01/10/test-containers.html

TestContainer 활용하기

TestContainer는 Docker 기반의 테스트 환경을 제공하는 도구로, Docker Compose와 유사하게 동작합니다. 또한 외부 설정 파일 없이도 Java 코드만으로 테스트 환경을 간편하게 구성할 수 있습니다. 이 방식은 실제 환경과 유사한 테스트를 제공하는 동시에, 컨테이너 간의 통신 문제나 초기화 관련된 문제를 쉽게 해결할 수 있다는 장점이 있습니다. 

 

 

[TestContainer란?]

TestContainer는 Java 플랫폼에 특화된 라이브러리로서, 도커 컨테이너를 간편하게 다루도록 설계되었습니다. 이 라이브러리의 주된 목적은 JUnit 테스트 중 도커 컨테이너를 효과적으로 활용하여 외부 의존성을 관리하는 것입니다.

통합 테스트나 end-to-end 테스트를 진행하면서 외부 의존성 요소가 필요한 상황은 매우 흔한데, 예를 들면 (데이터베이스, 메시징 시스템, 인메모리 저장소 등)이 이런 요소에 해당합니다. 이러한 서비스들을 매번 테스트 환경에 실제로 설치하고 구동하는 것은 시간적으로 많이 소모되며, 환경 복잡성을 높일 수 있습니다.

이 문제를 해결하기 위해 TestContainer는 도커 컨테이너를 활용하여 필요한 외부 의존성을 가상화된 환경에서 제공합니다. 즉, 테스트를 위해 실제 서비스를 실행하는 대신 해당 서비스의 도커 이미지를 빠르게 실행하고 테스트가 끝나면 손쉽게 종료할 수 있습니다.

 

 

[TestContainer를 이용한 테스트 환경 구축]

build.gradle

// TestContainer 기본 의존성
testImplementation "org.testcontainers:testcontainers:1.19.0"
// MySQL 의존성
testImplementation 'org.testcontainers:mysql:1.16.0'
// Redis 의존성
testImplementation "com.redis.testcontainers:testcontainers-redis-junit:1.6.4"
// Kafka 의존성
testImplementation("org.testcontainers:kafka:1.17.6")

IntegrationTest.java

@Disabled
@SpringBootTest
@Transactional
@ContextConfiguration(initializers = IntegrationTest.IntegrationTestInitializer.class)
public class IntegrationTest {
    // 각 컨테이너 인스턴스 정의
    private static final MySQLContainer<?> MYSQL_CONTAINER = new MySQLContainer<>(DockerImageName.parse("mysql:8.0.26"))
            .withDatabaseName("container")
            .withUsername("user")
            .withPassword("password");
    private static final RedisContainer REDIS_CONTAINER = new RedisContainer(RedisContainer.DEFAULT_IMAGE_NAME.withTag("6"));
    private static final KafkaContainer KAFKA_CONTAINER = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.5.0"));

    @BeforeAll
    public static void setupContainers() {
        // MySQL 컨테이너 시작
        MYSQL_CONTAINER.start();
        // Redis 컨테이너 시작
        REDIS_CONTAINER.start();
        // Kafka 컨테이너 시작
        KAFKA_CONTAINER.start();
    }

    static class IntegrationTestInitializer implements ApplicationContextInitializer<ConfigurableApplicationContext> {

        @Override
        public void initialize(@NotNull ConfigurableApplicationContext applicationContext) {
            Map<String, String> properties = new HashMap<>();

            // 각 서비스의 연결 정보 설정
            setKafkaProperties(properties);
            setDatabaseProperties(properties);
            setRedisProperties(properties);

            // 애플리케이션 컨텍스트에 속성값 적용
            TestPropertyValues.of(properties).applyTo(applicationContext);
        }

        // Kafka 연결 정보 설정
        private void setKafkaProperties(Map<String, String> properties) {
            properties.put("spring.kafka.bootstrap-servers", KAFKA_CONTAINER.getBootstrapServers());
        }

        // 데이터베이스 연결 정보 설정
        private void setDatabaseProperties(Map<String, String> properties) {
            properties.put("spring.datasource.url", MYSQL_CONTAINER.getJdbcUrl());
            properties.put("spring.datasource.username", MYSQL_CONTAINER.getUsername());
            properties.put("spring.datasource.password", MYSQL_CONTAINER.getPassword());
        }

        // Redis 연결 정보 설정
        private void setRedisProperties(Map<String, String> properties) {
            properties.put("spring.redis.host", REDIS_CONTAINER.getHost());
            properties.put("spring.redis.port", REDIS_CONTAINER.getFirstMappedPort().toString());
        }
    }
}

코드를 살펴보면 다음과 같습니다.

• '@Disabled': IntegrationTest 클래스는 직접 실행되지 않고, 다른 테스트 클래스에서 상속하여 사용됩니다. 따라서 테스트를 비활성화하는 어노테이션입니다.
• '@ContextConfiguration': 스프링 어플리케이션 컨텍스트를 설정하는 어노테이션입니다. IntegrationTestInitializer 클래스에서 정의한 초기화 작업을 수행합니다.
• 'IntegrationTestInitializer': ApplicationContesxtInitializer 인터페이스를 구현한 내부 클래스로, 스프링 애플리케이션 컨텍스트를 초기화합니다.

 

Docker Compose를 사용한 통합 테스트 설정

만약 Docker Compose를 사용하여 DB를 세팅하고 싶다면 다음과 같이 작성할 수 있습니다.

IntegrationTest.java

@Disabled
@SpringBootTest
@Transactional
@ContextConfiguration(initializers = IntegrationTest.IntegrationTestInitializer.class)
public class IntegrationTest {

    // Docker Compose와 Kafka 컨테이너 인스턴스 정의
    private static final DockerComposeContainer<?> DOCKER_COMPOSE =
            new DockerComposeContainer<>(new File("src/test/resources/docker-compose.yml"))
                    .withExposedService("mysql", 3306, Wait.forLogMessage(".*ready for connections.*", 1))
                    .withExposedService("redis", 6379, Wait.forLogMessage(".*Ready to accept connections.*", 1));

    private static final KafkaContainer KAFKA_CONTAINER =
            new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:7.5.0"));

    @BeforeAll
    public static void setupContainers() {
        DOCKER_COMPOSE.start();
        KAFKA_CONTAINER.start();
    }

    static class IntegrationTestInitializer implements ApplicationContextInitializer<ConfigurableApplicationContext> {

        @Override
        public void initialize(@NotNull ConfigurableApplicationContext applicationContext) {
            Map<String, String> properties = new HashMap<>();

            setKafkaProperties(properties);
            setDatabaseProperties(properties);
            setRedisProperties(properties);

            TestPropertyValues.of(properties).applyTo(applicationContext);
        }

        private void setKafkaProperties(Map<String, String> properties) {
            properties.put("spring.kafka.bootstrap-servers", KAFKA_CONTAINER.getBootstrapServers());
        }

        private void setDatabaseProperties(Map<String, String> properties) {
            String rdbmsHost = DOCKER_COMPOSE.getServiceHost("mysql", 3306);
            int rdbmsPort = DOCKER_COMPOSE.getServicePort("mysql", 3306);
            properties.put("spring.datasource.url", "jdbc:mysql://" + rdbmsHost + ":" + rdbmsPort + "/container");
            properties.put("spring.datasource.username", "root");
            properties.put("spring.datasource.password", "password");
        }

        private void setRedisProperties(Map<String, String> properties) {
            String redisHost = DOCKER_COMPOSE.getServiceHost("redis", 6379);
            Integer redisPort = DOCKER_COMPOSE.getServicePort("redis", 6379);
            properties.put("spring.redis.host", redisHost);
            properties.put("spring.redis.port", redisPort.toString());
        }
    }
}

테스트 환경에서는 여러 서비스의 컨테이너를 동시에 실행할 때 Docker Compose를 사용하는 것이 효율적입니다. 그러나 컨테이너 간의 초기화 시간이 다르기 때문에 모든 컨테이너가 정상적으로 시작될 때까지 대기하는 것이 중요합니다. 이를 위해 'Wait'구문을 활용합니다.

private static final DockerComposeContainer<?> DOCKER_COMPOSE =
    new DockerComposeContainer<>(new File("src/test/resources/docker-compose.yml"))
        .withExposedService("mysql", 3306, Wait.forLogMessage(".*ready for connections.*", 1))
        .withExposedService("redis", 6379, Wait.forLogMessage(".*Ready to accept connections.*", 1));

Docker-compose.yml

version: "3.8"

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: container
      MYSQL_ROOT_PASSWORD: password
    ports:
      - 3306 # Tip: 테스트 환경에서는 호스트 포트 매핑(예: 3306:3306)을 생략하면 포트 충돌을 피할 수 있습니다.
  redis:
    image: redis:6
    ports:
      - 6379 # Tip: 테스트 환경에서는 호스트 포트 매핑(예: 6379:6379)을 생략하면 포트 충돌을 피할 수 있습니다.

또한 테스트용 docker-compose 설정에서는 호스트와 컨테이너의 포트 매핑을 생략하여 포트 충돌의 위험을 최소화하는 것이 좋습니다.
 
 

 

테스트

아래는 IntefrationTest 클래스를 상속받아 MySQL, Redis, Kafka 연동을 테스트 한 코드입니다.

 

class DatabaseTest extends IntegrationTest {
    @Autowired
    private UserRepository userRepository;

    @Autowired
    private EntityManager entityManager;

    @Test
    void saveAndRetrieveUserTest() {
        // given
        User user = new User(null, "dkswnkk");
        userRepository.save(user);

        // when
        entityManager.flush();
        entityManager.clear();
        var retrievedUser = userRepository.findById(1L);

        // then
        Assertions.assertEquals("dkswnkk", retrievedUser.get().getName());
    }
}

 

public class KafkaConsumerApplicationTests extends IntegrationTest {

    @Autowired
    private KafkaProducerService kafkaProducerService;

    // 실제 KafkaConsumerService 대신 mock 객체를 생성합니다.
    // mock 객체는 실제 로직을 실행하지 않으며, 호출 여부나 인자 값 등을 확인하는 데 사용됩니다.
    @MockBean
    private KafkaConsumerService kafkaConsumerService;

    // 카프카 메시지 전송 및 수신 테스트
    @Test
    public void kafkaSendAndConsumeTest() {
        String topic = "test-topic";
        String expectValue = "expect-value";

        kafkaProducerService.send(topic, expectValue);

        // ArgumentCaptor: mock 객체에 전달된 인자를 캡처해 후에 그 값을 검증하기 위해 사용합니다.
        var stringCaptor = ArgumentCaptor.forClass(String.class);

        // kafkaConsumerService.process 메소드가 특정 시간 내에 한 번 호출되었는지 확인합니다.
        // 또한, 그 때 어떤 인자로 호출되었는지 stringCaptor를 통해 캡처합니다.
        Mockito.verify(kafkaConsumerService, Mockito.timeout(5000).times(1))
                .process(stringCaptor.capture());

        // 캡처된 인자와 기대값이 일치하는지 검증합니다.
        Assertions.assertEquals(expectValue, stringCaptor.getValue());
    }
}

 

public class RedisTest extends IntegrationTest {
    @Autowired
    private RedisService redisService;

    @Test
    @DisplayName("Redis Get / Set 테스트")
    public void redisGetSetTest() {
        // given
        String key = "name";
        String expectedValue = "dkswnkk";

        // when
        redisService.set(key, expectedValue);

        // then
        String actualValue = redisService.get(key);
        Assertions.assertEquals(expectedValue, actualValue);
    }
}

 

@Configuration
public class KafkaConsumerApplication {
    @Autowired
    private KafkaConsumerService kafkaConsumerService;

    // 카프카 토픽 설정
    @Bean
    public NewTopic topic() {
        return TopicBuilder.name("test-topic").build();
    }

    // 카프카 리스너: 메시지를 받으면 처리 서비스를 호출
    @KafkaListener(id = "test-id", topics = "test-topic")
    public void listen(String message) {
        kafkaConsumerService.process(message);
    }
}

 

@Service
public class KafkaConsumerService {
    // 메시지 처리: 현재는 콘솔에 출력
    public void process(String message) {
        System.out.println("processing ... " + message);
    }
}

 

@Service
public class KafkaProducerService {
    @Autowired
    private KafkaTemplate<String, String> kafkaTemplate;

    // 주어진 토픽으로 메시지 전송
    public void send(String topic, String message) {
        kafkaTemplate.send(topic, message);
    }
}

 

@Service
public class RedisService {
    @Autowired
    private RedisTemplate<String, String> redisTemplate;

    public String get(String key) {
        return redisTemplate.opsForValue().get(key);
    }

    public void set(String key, String value) {
        redisTemplate.opsForValue().set(key, value);
    }
}

테스트 수행 결과

 
 

결론

테스트 환경에서 DB와 같은 외부 의존성을 관리하는 것은 복잡할 수 있습니다. TestContainer를 활용하면 이러한 복잡성을 크게 줄이고, 격리된 환경에서 테스트를 수행할 수 있습니다. 특히, CI/CD 파이프라인과 같이 자동화된 환경에서는 TestContainer를 활용하여 더욱 안정적인 테스트를 구현할 수 있습니다.

 

 

참고

• 컬리 기술블로그
• 딜리셔스 기술블로그
• 뤼이드 기술블로그

 

테스트 관련 같이 보면 좋은 글

• AssertJ 핵심 기능 알아보기
• Junit5 자세히 알아보기
• LocalStack을 활용한 AWS S3 테스트 환경 구축하기
• ArchUnit으로 아키텍처 검사하기