testcontainers-spring-boot starts stateful services before your test beans

The problem is medium sized tests that need real stateful services

The README frames the target audience precisely: developers who build services with Spring Boot, possibly with Spring Cloud, and who run "medium sized" tests during the build process. The link beside that phrase points at a Google article about test sizes, which is the reference the project uses for the word itself.

The pain being addressed is the stateful dependency. A test that talks to Kafka, Couchbase, Redis or a database needs something that behaves like that service, and the alternatives are a mock, an in-process substitute, or a real container. The project chooses the container route and removes the wiring work, because as the README puts it, adding a module to the classpath gives you a stateful service that is auto-started and available for connection without additional code.

The scope is wide. The repository carries a directory per service, including `embedded-kafka/`, `embedded-couchbase/`, `embedded-redis/`, `embedded-mongodb/`, `embedded-postgresql/`, `embedded-mysql/`, `embedded-mariadb/`, `embedded-oracle-xe/`, `embedded-mssqlserver/`, `embedded-db2/`, `embedded-elasticsearch/`, `embedded-opensearch/`, `embedded-rabbitmq/`, `embedded-nats/`, `embedded-pulsar/`, `embedded-vault/`, `embedded-keycloak/`, `embedded-consul/`, `embedded-neo4j/`, `embedded-aerospike/`, `embedded-azurite/`, `embedded-artifactory/`, `embedded-localstack/`, `embedded-grafana/`, `embedded-prometheus/`, `embedded-influxdb/`, `embedded-clickhouse/`, `embedded-cockroachdb/`, `embedded-solr/`, `embedded-temporal/`, `embedded-spicedb/`, `embedded-wiremock/`, `embedded-mockserver/`, `embedded-git/`, `embedded-mailhog/`, `embedded-toxiproxy/`, `embedded-selenium/`, `embedded-native-kafka/`, `embedded-vertica/`, `embedded-victoriametrics/`, `embedded-k3s/`, `embedded-keydb/`, `embedded-memsql/`, and `embedded-google-pubsub/`, `embedded-google-storage/`.

Docker and Testcontainers do the actual bootstrapping, and the license is MIT.

The Spring Cloud bootstrap phase is the actual mechanism

The interesting design decision is where the container starts. The README says the services are bootstrapped during the Spring Cloud bootstrap phase, and that Spring Cloud in production code is optional, but "you will need it in tests". That phrase is the key constraint of the whole library.

The bootstrap phase is the early context in which a Spring Cloud application reads configuration before the main application context is created. Because the containers are started there, the properties they generate, such as `embedded.kafka.brokerList`, exist by the time your own beans are created. That is why a test class needs no `@Container` field, no `@DynamicPropertySource` method, and no manual property plumbing.

The trade-off is direct. To get that early start you must have Spring Cloud on the test classpath, which for projects that do not use it in production means adding a dependency that exists only for tests. The README gives a specific note about versions here: the project migrated to Spring Boot 2.4 in version 2.0.0, and from Spring Boot 2.4 onward you need `spring-cloud-starter-bootstrap`, while earlier Spring Boot users need `spring-cloud-starter` instead.

The auto-configuration then publishes connection details under an `embedded.` prefix per service, and your application configuration refers to those properties instead of hardcoded hosts and ports. Connection details that change per run, such as a mapped container port, are exactly the part that manual wiring tends to get wrong.

Adding embedded-kafka to a test classpath

The setup path in the README starts with installing Docker on your machine and making sure Spring Boot and Spring Cloud are on the test classpath. If Spring Cloud is not otherwise used, the project shows how to keep it test scoped only.

The `spring-cloud-starter-bootstrap` dependency is the piece that makes the bootstrap phase available.

      <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-bootstrap</artifactId>
            <!-- https://mvnrepository.com/artifact/org.springframework.cloud/spring-cloud-starter-bootstrap -->
            <version>[pick version]</version>
        </dependency>

Then you add one module per service you need. The Kafka module is the example given, and it is test scoped.

        <dependency>
            <groupId>com.playtika.testcontainers</groupId>
            <artifactId>embedded-kafka</artifactId>
            <!-- https://mvnrepository.com/artifact/com.playtika.testcontainers/ -->
            <version>[pick version]</version>
            <scope>test</scope>
        </dependency>

With the module present, the container starts during bootstrap and the properties appear. The README shows consumption in `src/test/resources/application.properties`, where the Kafka bootstrap servers point at the property the module published.

spring.kafka.bootstrap-servers=${embedded.kafka.brokerList}

Topic creation is configured the same way, in `src/test/resources/bootstrap.properties`, using the `embedded.kafka` prefix for the Kafka module.

embedded.kafka.topicsToCreate=some_topic

The pattern generalises across modules. Each service exposes its own `embedded.<service>` property set, and the properties file is where you map those into the configuration keys your application code reads. The README does not document a full list of the exposed property names, so the reliable source for a given service is the module's own documentation or its properties class rather than the top-level README.

The version matrix constrains which Spring Boot line you can use

The README publishes an explicit compatibility table, which is the single most useful piece of information for an adopter. For Spring Boot 2.5.X, 2.6.X and 2.7.X the matching version of this project is 2.X.X. For Spring Boot 3.0.X and 3.1.X it is 3.0.X. For Spring Boot 3.2.X, 3.3.X, 3.4.X and 3.5.X it is 3.1.X. For Spring Boot 4.0.X it is 4.0.X.

That table is the upgrade cost. Moving to a new Spring Boot generation means moving to a new major line of this project, and the table gives no patch-level guidance, so the fine mapping is left to the release notes. The library version in your `pom.xml` is not a free choice; it is determined by the Spring Boot version you are on.

The recent release history fits the table. Version 4.0.3 was published on 2026-07-01, 4.0.4 on 2026-08-06 and 4.1.0 on 2026-10-11, so patch releases inside the 4.0 line are followed by a minor bump. The repository is not archived and the last push was on 2026-10-19, on the `develop` default branch, which means development happens on `develop` while tagged releases are cut from it.

Nothing here suggests stagnation, but the cadence of major versions is set by the Spring Boot release calendar rather than by this project, and that is the thing to plan around when a Spring Boot upgrade lands on your team.

Parallel startup and forced shutdown are the two knobs that matter

The README documents common configuration options in `src/test/resources/application.properties`, and two of them change how your suite behaves rather than what it contains.

The first is `embedded.containers.parallelStartup`, which defaults to false. By default embedded containers start one after another, so the total startup time is the sum of every container's own startup time. Enabling it starts them concurrently instead, so the total time is closer to the slowest single container. For a suite that starts six services, that difference is the difference between a slow build and a tolerable one.

embedded.containers.parallelStartup=true #default is false

There is one documented exception. The option is supported by every module except `embedded-toxiproxy`, because its container is a direct dependency of every other module's Toxiproxy proxy bean, so it always starts eagerly ahead of the rest. If you are measuring startup time with Toxiproxy in the mix, that container is not part of the parallel set.

The second is `embedded.containers.forceShutdown`, which also defaults to false.

embedded.containers.forceShutdown=true #default is false

Without it, containers are shut down with a delay, and the README points at the moby-ryuk project in the testcontainers organisation for the resource cleanup mechanism behind that delay. With it, the containers stop as soon as the Spring application shuts down, which is what you want on a shared CI machine where a lingering container holds a port or a volume.

One caveat the README raises near the end applies to any custom bean: if your own beans read `embedded.*` connection properties through `@Value`, they must depend on an auto-configured infrastructure bean such as `DataSource` or `RabbitTemplate`, because those already carry the wiring that makes the properties meaningful.

Official Testcontainers and @ServiceConnection take the other route

The README draws this comparison itself, and it is the fairest way to decide. It points at testcontainers-java and at Spring Boot's own Testcontainers support, which it says has existed since 3.1 and includes `@ServiceConnection`, describing them as the lower-level path where you declare containers in the test and wire the connection details yourself, through `@DynamicPropertySource` or a service connection.

This project sits on top of Testcontainers rather than replacing it. The mechanism is the same underneath, since Docker and Testcontainers do the bootstrapping in both cases. What changes is who owns the lifecycle. With an `embedded-*` module on the test classpath, the service starts during the Spring Cloud bootstrap phase and the properties appear without test code. With `@ServiceConnection`, the test class owns the container, which means the container's lifetime is tied to the test, and the property wiring is explicit.

The README's own guidance is to use this project when you want auto-configuration, and official Testcontainers with `@ServiceConnection` when you want to own the container lifecycle in the test class. That is the deciding question for a new adopter.

The cost of the automatic route is that the container starts before the test, so it is not scoped to a single test method, and it requires the Spring Cloud bootstrap mechanism to be present. The cost of the manual route is more code in each test that needs a service.

Where this approach stops working

There are several cases where the automatic route is the wrong choice, and the README is honest about most of them.

If your build cannot add Spring Cloud as a test dependency, this project does not apply. The bootstrap phase is not optional in the mechanism, so the `spring-cloud-starter-bootstrap` dependency is a hard requirement in tests, and the project is explicit that you need it even when production code does not use Spring Cloud.

If you have no Docker available, or a build environment that cannot start containers, nothing in this library helps. The README's first step is installing Docker, and every module is a container.

If a test needs a container scoped to one test method, or a container whose lifecycle must be verified, the automatic start is at odds with the requirement. Related to this, a per-test container count has a real cost, because a container that starts before the test class and stays up until the application shuts down occupies resources for the whole class, and the delay-based shutdown the README describes means that a busy CI machine can accumulate containers across parallel test classes.

Finally, the breadth of the module list is a double-edged fact. Fifty plus service modules is coverage, but each one is a wrapper around an image whose version, configuration surface and startup behavior come from the upstream image, and the README does not document which image tags or versions each module pins. That is the first thing to check in a specific module before depending on it.

Editorial conclusion

Take testcontainers-spring-boot when your Spring Boot tests need several stateful services and you would rather read connection properties than manage container lifecycles, and when Spring Cloud is acceptable as a test-scoped dependency. Keep official Testcontainers with @ServiceConnection when the test class should own the container, or when you cannot add spring-cloud-starter-bootstrap to the build. Verify first that your Spring Boot line appears in the compatibility table, that the service you need has an embedded module, and that your Docker environment starts those images at the speed your test suite can absorb.

Frequently asked questions

Official sources

1. License: MIT
2. PlaytikaOSS/testcontainers-spring-boot on GitHub
3. Project website
4. README
5. Releases