TestContainers in Spring Boot: A Quick Guide

Hôm nay mình xin phép chia sẻ một bài mà mình đã viết cho blog của công ty, chia sẻ về TestContainer trong Spring Boot.

Introduction

In the dynamic world of software development, ensuring that applications behave as expected in various environments is crucial. This challenge is particularly pronounced when dealing with database interactions, external services, or any components that your application relies on. Here, integration tests play a vital role. However, traditional integration testing approaches often struggle with environment consistency and setup overhead. Enter TestContainers, a powerful library that leverages Docker to provide lightweight, throwaway instances of common databases, Selenium web browsers, or anything that can run in a container. This article delves into using TestContainers within Spring Boot applications, offering a comprehensive guide on its advantages, drawbacks, setup procedures, usage examples, practical tips, and a summary to help you get started with ease.

Advantages and Disadvantages of TestContainers

Advantages

1. Environment Consistency: TestContainers ensure that developers, CI servers, and production environments run identical setups, mitigating the “it works on my machine” syndrome.
2. Ease of Use: With a simple API and extensive documentation, TestContainers make it straightforward to manage container lifecycles and integrate with popular testing frameworks like JUnit.
3. Flexibility: Whether you need a PostgreSQL database, a Kafka cluster, or a custom application stack, TestContainers can run any containerized service.
4. Isolation: Each test can run against a fresh instance, ensuring that tests do not interfere with each other and improving test reliability.

Disadvantages

1. Docker Dependency: TestContainers require Docker to be installed and running, which can be a barrier in environments where Docker is not available or practical.
2. Resource Intensive: Running multiple containers can consume significant system resources, which might slow down development machines or CI servers.
3. Learning Curve: While TestContainers simplify many aspects of integration testing, understanding containerization and Docker configurations can require additional learning.

Setting Up and Using TestContainers

Installation

To start using TestContainers in a Spring Boot project, add the following dependencies to your pom.xml or build.gradle:

Maven:

<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers</artifactId>
<version>1.16.2</version>
<scope>test</scope>
</dependency>

Gradle:

testImplementation 'org.testcontainers:testcontainers:1.16.2'

Ensure that Docker is installed and running on your machine as TestContainers will need to pull and manage Docker images.

Usage Example

Assume you have a Spring Boot application with JPA for managing users in a PostgreSQL database. We will write a test for the UserRepository using TestContainers to ensure that our data layer interacts correctly with the database.

Step 1: Define the Domain Model

First, define a simple User entity:

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;

@Entity
public class User {
 @Id
 @GeneratedValue(strategy = GenerationType.IDENTITY)
 private Long id;
 private String username;
 private String email;

 // Constructors, getters, and setters
 public User() {}

 public User(String username, String email) {
  this.username = username;
  this.email = email;
 }

 // Standard getters and setters
 public Long getId() {
  return id;
 }

 public void setId(Long id) {
  this.id = id;
 }

 public String getUsername() {
  return username;
 }

 public void setUsername(String username) {
  this.username = username;
 }

 public String getEmail() {
  return email;
 }

 public void setEmail(String email) {
  this.email = email;
 }
}

Step 2: Define the Repository

Create a UserRepository interface that extends JpaRepository:

import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, Long> {
 User findByUsername(String username);
}

Step 3: Configure TestContainers for Testing

Next, configure the PostgreSQL TestContainer to be used for testing:

import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
public class UserRepositoryTests {

@Container
public static PostgreSQLContainer<?> postgresqlContainer = new PostgreSQLContainer<>("postgres:13")
.withUsername("duke")
.withPassword("password")
.withDatabaseName("test");

@DynamicPropertySource
static void properties(DynamicPropertyRegistry registry) {
 registry.add("spring.datasource.url", postgresqlContainer::getJdbcUrl);
 registry.add("spring.datasource.username", postgresqlContainer::getUsername);
 registry.add("spring.datasource.password", postgresqlContainer::getPassword);
}

@Autowired
private UserRepository userRepository;

@Test
public void testFindByUsername() {
 // Setup test data
 User user = new User("duke", "duke@email.com");
 userRepository.save(user);

 // Test find by username
 User found = userRepository.findByUsername("duke");
 assert found.getUsername().equals(user.getUsername());
 }
}

Explanation:

1. @Container Annotation: This annotation is used to declare the PostgreSQL container. The container is configured with a specific Docker image, username, password, and database name.
2. @DynamicPropertySource: This is used to dynamically configure the datasource properties for Spring Boot, pointing it to use the database inside the container. This allows our test to interact with a real database environment.
3. Test Method: The testFindByUsername() method creates a new User, saves it to the database, and retrieves it by username to verify the correctness of the repository method.

This example shows a more realistic testing scenario using TestContainers with Spring Boot, ensuring that the integration between the application code and the database behaves as expected under real conditions.

Practical Tips

• Resource Management: Monitor your system’s resources and adjust Docker’s settings to allocate enough CPU and memory to the containers without starving your host machine.
• Logging and Debugging: Utilize the logging capabilities of TestContainers to troubleshoot issues during container startup or test execution.
• Reuse Containers: For faster test execution, consider reusing containers across multiple tests when appropriate, although this may compromise test isolation.

Conclusion

TestContainers offer a robust solution for integration testing by providing real-world dependencies that can be spun up and torn down as needed. They bridge the gap between unit testing and full-scale deployment, ensuring that your Spring Boot applications are validated against realistic backends and services. While they introduce dependencies on Docker and may require more system resources, the benefits of using TestContainers, such as environment consistency and test reliability, are substantial. By following this guide, you should be well-equipped to integrate TestContainers into your Spring Boot projects, enhancing your testing strategies and ultimately delivering more reliable software.

References:

1. https://testcontainers.com/guides/testing-spring-boot-rest-api-using-testcontainers/
2. https://testcontainers.com/getting-started/
3. https://blog.nashtechglobal.com/testcontainers-in-spring-boot-a-quick-guide/