How to Use Testcontainers at Development Time in Spring Boot
Use Testcontainers at development time in Spring Boot: ServiceConnection, a test entry point, reusing containers and sharing definitions with tests.

Testcontainers started life as a way to run real databases in integration tests. Since Spring Boot 3.1 it can also start the containers your application needs while you develop, from the IDE, with no Compose file and no manual setup. You describe the containers once, as beans, and both the dev-time launcher and the tests use the same description. This post builds that arrangement on Spring Boot 4 with PostgreSQL and Redis, shows how to keep data between restarts, how to share the definitions with tests, and what goes wrong when Docker is not available. It uses JDK 25 and Testcontainers 2.
Dependencies
<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>spring-boot-testcontainers provides the integration: @ServiceConnection and the support for starting containers as beans. The module artifact names changed between Testcontainers 1.x and 2.x (modules gained a testcontainers- prefix in 2.x), so match the artifact to the major version your BOM manages, or the class will be missing. The initializer at start.spring.io generates the right pair when you tick Testcontainers.
You need a container runtime on the machine: Docker Desktop, Colima, Rancher Desktop or Podman with the Docker socket enabled. The differences among them are in Docker versus Podman. When none is found, the application fails at startup, see could not find a valid Docker environment.
Container definitions as beans
@TestConfiguration(proxyBeanMethods = false)
class TestcontainersConfiguration {
@Bean
@ServiceConnection
PostgreSQLContainer<?> postgres() {
return new PostgreSQLContainer<>("postgres:17");
}
@Bean
@ServiceConnection(name = "redis")
GenericContainer<?> redis() {
return new GenericContainer<>("redis:7").withExposedPorts(6379);
}
}@ServiceConnection tells Boot to read the container's address and credentials and create the connection details for the matching technology. For PostgreSQL, Boot sets up the DataSource without a single spring.datasource.* property. For a generic container you name the technology so Boot knows which details to build. Pin the image tag to the version you run in production, not latest, so that a development database cannot drift ahead of it.
Declaring the containers as beans means Spring starts them before the beans that need them and stops them at shutdown, in the right order.
Start the app with them
Add a main class in the test sources that launches the real application with the configuration added:
public class TestShopApplication {
public static void main(String[] args) {
SpringApplication.from(ShopApplication::main)
.with(TestcontainersConfiguration.class)
.run(args);
}
}Run TestShopApplication from the IDE, or from the command line:
./mvnw spring-boot:test-runThe application starts as it would in production, with containers launched first. The first run pulls the images, which takes a minute; later runs start in seconds. Because the class lives in the test sources, it never ships in the production jar, and test-scoped dependencies such as Testcontainers are on its classpath. Combine it with spring-boot-devtools for automatic restarts on code changes; the container beans survive a devtools restart only if you annotate them @RestartScope.
Keep data between runs
By default each run starts empty containers and discards them on exit. That is right for tests and annoying for development, where you want the data you created yesterday. Mark the containers reusable:
@Bean
@ServiceConnection
@RestartScope
PostgreSQLContainer<?> postgres() {
return new PostgreSQLContainer<>("postgres:17").withReuse(true);
}withReuse(true) only takes effect when the machine opts in, by adding testcontainers.reuse.enable=true to ~/.testcontainers.properties. Without that opt-in, the flag is ignored, which stops a CI server from leaking containers. A reused container is not stopped when the JVM exits, so stop it yourself with docker stop when you want a clean database. Reuse keeps schema and data, which also means a changed migration can meet an old state, so drop the container when migrations are reshuffled.
Reuse the definitions in tests
The same configuration class serves the integration tests:
@SpringBootTest
@Import(TestcontainersConfiguration.class)
class OrderRepositoryIT {
@Autowired OrderRepository orders;
@Test
void saves_and_finds() { /* runs against a real PostgreSQL */ }
}This is the main benefit: development and tests use one definition of the infrastructure, so a version bump is a one-line change that both pick up. Boot starts the containers once per context, and the Spring test cache reuses the context across classes with the same configuration; see context caching. Prefer slices where you can, as in test slices, since a full @SpringBootTest with two containers is the slow end of the suite, a problem covered in slow SpringBootTest.
Dev-time seeding
A development database is more useful with data in it. Run an init script when the container starts with withInitScript("seed.sql") on the PostgreSQL container, or run a CommandLineRunner bean in the test configuration that inserts sample rows. Keep seed data out of production code; the test configuration is the right home. With migrations by Flyway or Liquibase, the schema arrives through the application as usual, and only the sample data needs seeding.
Compose or Testcontainers
Boot also supports Docker Compose (spring-boot-docker-compose), which reads a compose.yaml and starts the services when the application starts. Compose is better when the same file describes the whole local stack for people who do not use an IDE, or when you want to start the dependencies by hand. Testcontainers is better when the definitions should be shared with the tests and expressed in Java, with typed APIs for waiting and configuration. Both are covered in Docker Compose support. Pick one per project; running both doubles the containers.
Version drift and what to log
Log the image tags at startup, either with a small ApplicationRunner in the test configuration or by reading them from the container beans. When a bug appears only for one developer, the first question is which database version they are on, and a log line answers it. Keep the tags in one constants class in the test sources, so the development launcher, the integration tests and any other tooling name the same versions. Update them together with the production upgrade, in the same pull request.
Troubleshooting
If startup hangs, the image is probably still pulling; watch docker ps. If the application connects to the wrong port, the container's mapped port is random by design, and @ServiceConnection reads it, so do not hard-code ports in properties. If a stale container from an earlier run keeps being reused and misbehaves, remove it with docker rm -f. On a corporate network, set the registry mirror in ~/.testcontainers.properties with hub.image.name.prefix. And if tests pass locally but fail on CI, check that the CI runner exposes a Docker socket.
When this does not apply
Dev-time containers suit services that are easy to run locally. For a dependency that cannot be containerised, such as a managed cloud service, use a stub or a shared development instance. The reference pages are the Boot Testcontainers documentation and the Testcontainers site.


