Database Integration Testing with Spring TestContainers

This guide shows you how to write integration tests against a PostgreSQL database using Spring TestContainers. It includes step-by-step instructions, best practices, and complete examples for Spring Boot applications.

While this guide focuses on PostgreSQL, the same approach applies to MySQL and other supported databases.

Why Use Spring TestContainers?

Spring TestContainers makes it easy to run database containers during tests. You get:

Simple annotations like @EnablePostgreSQL
Automatic Spring configuration with container info
Clean test isolation with fresh DB per run
Real-world testing against production-like DBs
Seamless JUnit 5 integration

Getting Started

1. Add Dependencies

Add the required dependencies to your build config:

Maven


<dependencies>
    <dependency>
        <groupId>io.flowinquiry</groupId>
        <artifactId>spring-testcontainers-postgresql</artifactId>
        <version><!-- Replace with the latest version --></version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <version>42.6.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

🔍 Find the latest version: Search on Maven Central

2. Writing Integration Tests

Basic PostgreSQL Test


import io.flowinquiry.testcontainers.jdbc.EnablePostgreSQL;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
 
@SpringBootTest
@EnablePostgreSQL
class BasicPostgreSQLTest {
 
    @Test
    void shouldConnectToDatabase() {
        // Test code using containerized PostgreSQL
    }
}

Using a Specific PostgreSQL Version


@EnablePostgreSQL(version = "15")
class CustomPostgresVersionTest {
    // Your test methods
}

Complete Example


import static org.junit.jupiter.api.Assertions.*;
 
import io.flowinquiry.testcontainers.jdbc.EnablePostgreSQL;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;
 
@SpringBootTest
@EnablePostgreSQL
@ActiveProfiles("test")
class PostgreSQLIntegrationTest {
 
    @Autowired
    private StoreRepository storeRepository;
 
    @Test
    void testStorePersistence() {
        storeRepository.deleteAll();
 
        Store store = new Store("Test Store", "Demo store");
        Store saved = storeRepository.save(store);
 
        assertNotNull(saved.getId());
        assertEquals("Test Store", saved.getName());
 
        var result = storeRepository.findByName("Test Store");
        assertEquals(1, result.size());
    }
}

How It Works

Detection: The @EnablePostgreSQL annotation tells Spring TestContainers to start a PostgreSQL container.
Startup: A PostgreSQL Docker container is launched automatically.
Auto-config: Spring picks up the container’s JDBC URL, username, and password and wires them into your application context.
Test Run: Your integration test runs against the live containerized database.
Teardown: The container stops after the test completes.

Spring TestContainers builds on the Testcontainers Java library but offers a simpler, annotation-driven interface tailored for Spring Boot.

In addition to built-in support for PostgreSQL and MySQL, you can easily extend this to other databases like Microsoft SQL Server or MariaDB by creating a custom module. Follow the guide at Writing a New Container Extension for Spring TestContainers to get started.