@ServiceConnection

@ServiceConnection(name = "redis")

A container started by Testcontainers listens on a random host port with a generated password. Before @ServiceConnection, every test had to copy those values into spring.datasource.url and friends with @DynamicPropertySource. Now you annotate the container, and Spring Boot creates a connection details bean (such as JdbcConnectionDetails) from it. Auto-configuration prefers connection details over properties, so the DataSource, Flyway and JPA all point at the container.

It needs spring-boot-testcontainers on the test classpath. In Spring Boot 4 that comes with Testcontainers 2, where module classes live in their own packages: org.testcontainers.postgresql.PostgreSQLContainer, which is no longer a generic type.

Two places to put it

On a static container field in a test class with @Testcontainers and @Container. JUnit starts the container before the class and stops it afterwards. Simple, and fine for one class.

On a @Bean method in a @TestConfiguration that tests @Import. The container is then a bean: Spring starts it before anything that needs it and stops it when the context closes. This is the better choice for a suite, because of context caching. When a field-managed container, for example one declared in a shared base class, stops at the end of class A, a cached context reused by class B still points at the dead port, and B fails with connection refused. A container bean lives exactly as long as the context that uses it.

How the service is recognised

For typed containers such as PostgreSQLContainer, the container class tells Boot which connection details to create. For a GenericContainer, Boot uses the image name, so redis:7-alpine is recognised as Redis. When you pull through a private mirror with a different image name, set @ServiceConnection(name = "redis"). The type attribute restricts which connection details are created when a container could serve more than one.

Common mistakes

• A non-static container field: a fresh database for every test method, and much slower runs.
• Leaving a test spring.datasource.url in place and expecting it to win. Connection details take precedence.
• Expecting Hibernate to create the tables. It only does that by default for embedded databases; against a container the schema comes from your Flyway or Liquibase migrations, or from spring.jpa.hibernate.ddl-auto set for the test.
• Using latest image tags. Pin the same major version you run in production, so a new upstream release cannot change test results without a deliberate upgrade.

The same configuration can start your application locally: a main method in src/test/java that calls SpringApplication.from(...).with(...) runs the real app against fresh containers, with nothing to install.

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

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.data.jpa.repository.JpaRepository;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import org.testcontainers.postgresql.PostgreSQLContainer;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;

@Entity
class Booking {

    @Id
    @GeneratedValue
    Long id;

    String guest;

    protected Booking() {}

    Booking(String guest) {
        this.guest = guest;
    }
}

interface BookingRepository extends JpaRepository<Booking, Long> {}

// PostgreSQL is not an embedded database, so Hibernate does not create tables
// by default. Flyway migrations would; this example has none, so create-drop.
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.NONE,
        properties = "spring.jpa.hibernate.ddl-auto=create-drop")
@Testcontainers
class BookingPersistenceTest {

    // Started once for the class; Boot reads its URL, user and password.
    // No spring.datasource.* properties and no @DynamicPropertySource needed.
    @Container
    @ServiceConnection
    static PostgreSQLContainer postgres = new PostgreSQLContainer("postgres:17-alpine");

    @Autowired
    BookingRepository bookings;

    @Test
    void savesToRealPostgres() {
        bookings.save(new Booking("Ada Lovelace"));
        assertThat(bookings.count()).isEqualTo(1);
    }
}

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.postgresql.PostgreSQLContainer;

// Containers as beans: Spring starts them before the beans that need them
// and stops them when the cached context is closed.
@TestConfiguration(proxyBeanMethods = false)
public class ContainersConfig {

    @Bean
    @ServiceConnection
    PostgreSQLContainer postgres() {
        return new PostgreSQLContainer("postgres:17-alpine");
    }

    // A GenericContainer is matched by image name; naming the service keeps it
    // working when the image comes from a mirror with a different name.
    @Bean
    @ServiceConnection(name = "redis")
    GenericContainer<?> redis() {
        return new GenericContainer<>("redis:7-alpine").withExposedPorts(6379);
    }
}

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.testcontainers.postgresql.PostgreSQLContainer;

// Normally in src/main/java.
@SpringBootApplication
class ShopApplication {
    public static void main(String[] args) {
        SpringApplication.run(ShopApplication.class, args);
    }
}

@TestConfiguration(proxyBeanMethods = false)
class DevContainers {

    @Bean
    @ServiceConnection
    PostgreSQLContainer postgres() {
        return new PostgreSQLContainer("postgres:17-alpine");
    }
}

// In src/test/java: run this main method to start the app against a container.
public class TestShopApplication {
    public static void main(String[] args) {
        SpringApplication.from(ShopApplication::main)
                .with(DevContainers.class)
                .run(args);
    }
}

<!-- Versions come from the Spring Boot parent. -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-testcontainers</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-junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>