Stop Lying to Your Tests

Integration Test -> PostgreSQL Container (Testcontainers) -> Real Flyway Migrations -> Real Schema

Testcontainers starts a real PostgreSQL instance inside Docker for each test suite. Your Flyway migrations run exactly as they would in production. Hibernate validates the resulting schema. If any migration has a flaw, the test suite fails before a single test method executes.

This is not just better testing. It is a feedback loop that catches infrastructure regressions within seconds of committing code.

The Abstract Base Class Pattern

The architecture decision I consistently make in Spring Boot services is to centralize the Testcontainers setup in a single abstract base class that all integration tests extend.

AbstractContainerIT  (base)
|
|- OrderContextIT      @Order(1) - smoke: context loads, health endpoint
|- MerchantApiIT       @Order(2) - merchant CRUD, pagination
|- TransactionFlowIT   @Order(3) - auth + capture + settlement
`- SettlementBatchIT   @Order(4) - batch close, ordering-dependent

One container. One Spring context. Shared across all test classes in the JVM.

The base class declares the container as public static final, meaning the PostgreSQL container starts once and is reused.

public static final PostgreSQLContainer<?> postgresContainer =
    new PostgreSQLContainer<>("postgres:17")
        .withDatabaseName("service_test")
        .withUsername("testuser")
        .withPassword("testpass")
        .withReuse(true);

.withReuse(true) goes one step further - on a developer's local machine, Testcontainers will reuse the already-running container from a previous test run.

@DynamicPropertySource - The Right Hook for Dynamic Configuration

A critical implementation decision is where you start the container and how you wire its dynamic properties - JDBC URL, username, password - into the Spring Environment.

The correct approach is @DynamicPropertySource:

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

Starting the container here guarantees the container is running before Spring assembles its Environment.

Test Profile Isolation

Integration tests must not depend on the main application configuration to be runnable.

Example test configuration:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: ~
          jwk-set-uri: http://auth-server:8080/oauth2/jwks

The test context still configures OAuth2 correctly, but the context no longer depends on a live external service.

Dependency Hygiene - What You Include Shapes Your Schema

Dependencies shape your runtime behavior and your schema.

Example: spring-modulith-starter-jpa automatically registers entities such as:

event_publication
event_publication_archive

If Hibernate validation is enabled and the schema does not contain those tables, startup fails.

Architectural rule:

Include a dependency when you need its capability - not before.

Spring Boot 4 - Test Starters Are Now Decomposed

Spring Boot 4 decomposed testing starters.

Example dependency:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-webmvc-test</artifactId>
  <scope>test</scope>
</dependency>

@AutoConfigureMockMvc moved packages accordingly.

@SpringBootTest vs RANDOM_PORT

For REST API integration tests, prefer:

@SpringBootTest
MockMvc

Instead of:

@SpringBootTest(webEnvironment = RANDOM_PORT)

Because Spring context caching performs better.

The First Integration Test: Smoke and Actuator

The first test should verify two things:

1. The Spring context loads
2. /actuator/health returns HTTP 200

This ensures:

• migrations run
• schema validates
• HTTP stack works

What AI Changes - and What It Does Not

AI can generate integration test scaffolding quickly.

What it cannot decide:

• database fidelity
• container lifecycle
• dependency hygiene
• test architecture

Those remain engineering decisions.

Summary

Final Thoughts

AI accelerates implementation.

It does not replace architectural clarity.

Integration testing with real infrastructure is not ceremony - it is the foundation that gives teams confidence that what they build behaves correctly under real conditions.

Build that foundation correctly once. Everything on top of it benefits permanently.

If this was useful, share it with a teammate who is wrestling with flaky integration tests or the H2-versus-real-database debate.