Spring Boot Integration Tests with Testcontainers (Locally and in GitHub Actions)

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-testcontainers</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-postgresql</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers-kafka</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.springframework.kafka</groupId>
  <artifactId>spring-kafka-test</artifactId>
  <scope>test</scope>
</dependency>

package com.example.orders;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.testcontainers.kafka.KafkaContainer;
import org.testcontainers.postgresql.PostgreSQLContainer;
import org.testcontainers.utility.DockerImageName;

@TestConfiguration(proxyBeanMethods = false)
public class ContainersConfiguration {

    @Bean
    @ServiceConnection
    PostgreSQLContainer postgres() {
        return new PostgreSQLContainer(DockerImageName.parse("postgres:18.1"));
    }

    @Bean
    @ServiceConnection
    KafkaContainer kafka() {
        return new KafkaContainer(DockerImageName.parse("apache/kafka:4.2.1"));
    }
}

@SpringBootTest
@Import(ContainersConfiguration.class)
class OrderRepositoryIT {
    // ... tests; JDBC and Kafka connection details come from the container beans
}

@Bean
DynamicPropertyRegistrar paymentsProperties(GenericContainer<?> wiremock) {
    return registry -> registry.add("clients.payments.base-url",
            () -> "http://%s:%d".formatted(wiremock.getHost(), wiremock.getMappedPort(8080)));
}

package com.example.orders;

import org.springframework.boot.SpringApplication;

public class TestOrdersApplication {

    public static void main(String[] args) {
        SpringApplication.from(OrdersApplication::main)
                .with(ContainersConfiguration.class)
                .run(args);
    }
}

    services:
      postgres:
        image: postgres:18.1
        env:
          POSTGRES_DB: orders
          POSTGRES_USER: orders
          POSTGRES_PASSWORD: orders-dev-only      # development-only
        ports:
          - 5432:5432
        options: >-
          --health-cmd "pg_isready -U orders -d orders"
          --health-interval 5s --health-timeout 3s --health-retries 20

# compose.yaml -- local development and integration tests. Development-only credentials.
name: orders

services:
  postgres:
    image: postgres:18.1
    environment:
      POSTGRES_DB: orders
      POSTGRES_USER: orders
      POSTGRES_PASSWORD: orders-dev-only            # development-only
    ports:
      - "127.0.0.1:5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U orders -d orders"]
      interval: 5s
      timeout: 3s
      retries: 20

  kafka:
    image: apache/kafka:4.2.1
    ports:
      - "127.0.0.1:9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: CONTROLLER://:29093,PLAINTEXT_HOST://:9092,PLAINTEXT://:19092
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT_HOST://localhost:9092,PLAINTEXT://kafka:19092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:29093
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_SHARE_COORDINATOR_STATE_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_SHARE_COORDINATOR_STATE_TOPIC_MIN_ISR: 1
      KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
    healthcheck:
      test: ["CMD-SHELL", "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092 > /dev/null"]
      interval: 10s
      timeout: 10s
      retries: 20

  wiremock:
    image: wiremock/wiremock:3.13.2
    command: ["--global-response-templating", "--disable-banner"]
    ports:
      - "127.0.0.1:8585:8080"
    volumes:
      - ./wiremock:/home/wiremock:ro
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/__admin/health"]
      interval: 5s
      timeout: 3s
      retries: 20
    labels:
      org.springframework.boot.ignore: "true"

{
  "request": { "method": "POST", "urlPath": "/payments/authorizations" },
  "response": {
    "status": 201,
    "headers": { "Content-Type": "application/json" },
    "jsonBody": { "authorizationId": "auth-{{randomValue length=8 type='ALPHANUMERIC'}}", "status": "AUTHORIZED" }
  }
}

package com.example.orders;

import java.io.File;
import java.nio.file.Files;
import java.nio.file.Path;
import java.time.Duration;

import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.DynamicPropertyRegistry;
import org.springframework.test.context.DynamicPropertySource;
import org.testcontainers.containers.ComposeContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@ActiveProfiles("it")
public abstract class AbstractIT {

    /** The same compose.yaml a developer runs locally: one definition, no drift. Started once per JVM. */
    protected static final ComposeContainer ENVIRONMENT = new ComposeContainer(
                    DockerImageName.parse("docker:29.8.1-cli"), composeFile())
            .withCopyFilesInContainer("wiremock")   // only compose.yaml and the bind-mounted mappings, not the whole root
            .withExposedService("postgres", 5432, Wait.forHealthcheck())
            .withExposedService("kafka", 9092, Wait.forHealthcheck())
            .withExposedService("wiremock", 8080, Wait.forHealthcheck())
            .withStartupTimeout(Duration.ofMinutes(3));

    static {
        ENVIRONMENT.start();   // Ryuk removes the stack when the JVM exits
    }

    @DynamicPropertySource
    static void environmentProperties(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", () -> "jdbc:postgresql://%s:%d/orders".formatted(
                ENVIRONMENT.getServiceHost("postgres", 5432), ENVIRONMENT.getServicePort("postgres", 5432)));
        registry.add("spring.datasource.username", () -> "orders");
        registry.add("spring.datasource.password", AbstractIT::composeDatabasePassword);
        registry.add("spring.kafka.bootstrap-servers", () -> "%s:%d".formatted(
                ENVIRONMENT.getServiceHost("kafka", 9092), ENVIRONMENT.getServicePort("kafka", 9092)));
        registry.add("clients.payments.base-url", () -> "http://%s:%d".formatted(
                ENVIRONMENT.getServiceHost("wiremock", 8080), ENVIRONMENT.getServicePort("wiremock", 8080)));
    }

    /** The development-only value from compose.yaml, kept in one place. */
    private static String composeDatabasePassword() {
        return "orders-dev-only";
    }

    /** Failsafe runs in the module directory; walk up to the directory that holds compose.yaml. */
    private static File composeFile() {
        for (Path dir = Path.of(System.getProperty("user.dir")).toAbsolutePath(); dir != null; dir = dir.getParent()) {
            Path candidate = dir.resolve("compose.yaml");
            if (Files.isRegularFile(candidate)) {
                return candidate.toFile();
            }
        }
        throw new IllegalStateException("compose.yaml not found above " + System.getProperty("user.dir"));
    }
}

spring:
  docker:
    compose:
      skip:
        in-tests: true

package com.example.orders;

import static org.assertj.core.api.Assertions.assertThat;

import java.time.Duration;

import org.apache.kafka.clients.consumer.ConsumerRecord;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.kafka.test.utils.KafkaTestUtils;
import org.springframework.web.client.RestClient;

class OrderIT extends AbstractIT {

    @LocalServerPort
    int port;

    @Value("${spring.kafka.bootstrap-servers}")
    String bootstrapServers;

    @Autowired
    JdbcClient jdbc;

    @Test
    void placingAnOrderAuthorizesPaymentStoresItAndPublishesAnEvent() {
        var response = RestClient.create("http://localhost:" + port)
                .post().uri("/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .body("""
                      {"customerId": "c-%s", "amount": 42.50}
                      """.formatted(System.nanoTime()))          // unique key: the stack is shared
                .retrieve()
                .toEntity(String.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);

        String orderId = response.getHeaders().getLocation().getPath().replace("/orders/", "");
        String status = jdbc.sql("select status from orders where id = ?")
                .param(orderId)
                .query(String.class)
                .single();
        assertThat(status).isEqualTo("PAYMENT_AUTHORIZED");        // WireMock answered AUTHORIZED

        ConsumerRecord<?, ?> event = KafkaTestUtils.getOneRecord(
                bootstrapServers, "order-it-" + orderId, "orders.placed", 0, false, true, Duration.ofSeconds(30));
        assertThat(event.key()).hasToString(orderId);
    }
}

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <forkCount>1</forkCount>          <!-- one JVM: the Compose harness publishes fixed host ports -->
  </configuration>
</plugin>