Spring/spring-boot
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Polish 'Document methods of starting Testcontainer containers'

Browse Source 
See gh-44187
This commit is contained in:
Phillip Webb
2025-05-05 22:03:01 -07:00
parent 4a98b1787f
commit 8814d8a7dc
18 changed files with 216 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/testing/testcontainers.adoc
View File

@@ -8,85 +8,90 @@ Testcontainers is especially useful for writing integration tests that talk to a
In following sections we will describe some of the methods you can use to integrate Testcontainers with your tests.
[[testing.testcontainers.via-junit-extension]]
== Using via @Testcontainers JUnit5 extension
The Testcontainers provides JUnit5 extensions, which can be used to manage containers in your tests.
The extension is activated by applying the `@Testcontainers` annotation from Testcontainers to your test class.
Testcontainers can be used in a Spring Boot test as follows:
include-code::vanilla/MyIntegrationTests[]
This will start up a Docker container running Neo4j (if Docker is running locally) before any of the tests are run.
In most cases, you will need to configure the application to connect to the service running in the container.
In this case the lifecycle of the container instance is managed by Testcontainers, as described in official documentation.
[[testing.testcontainers.via-spring-beans]]
== Using via Spring managed beans
[[testing.testcontainers.spring-beans]]
== Using Spring Beans
The containers provided by Testcontainers can be managed by Spring Boot as beans.
This method of managing contains can be used in combination with javadoc:org.springframework.boot.testcontainers.service.connection.ServiceConnection[format=annotation].
To use Testcontainer contains as Spring beans we need to create a configuration class declaring the container as bean:
To declare a container as a bean, add a javadoc:org.springframework.context.annotation.Bean[format=annotation] method to your test configuration:
include-code::beandeclaration/BeanDeclarationConfig[]
include-code::MyTestConfiguration[]
then we can start the container by importing the configuration class in the test class:
You can then inject and use the container by importing the configuration class in the test class:
include-code::beandeclaration/SpringTest[]
include-code::MyIntegrationTests[]
TIP: This method of managing containers is often used in combination with xref:#testing.testcontainers.service-connections[service connection annotations].
[[testing.testcontainers.via-declaration-classes]]
== Using via importing container declaration classes
A common pattern with Testcontainers is to declare the Container instances as static fields in an interface.
For example the following interface `MyInterface` declares two containers, one named `mongo` of type MongoDB and another named `neo` of type Neo4j:
[[testing.testcontainers.junit-extension]]
== Using the JUnit Extension
include-code::importcontainers/MyInterface[]
Testcontainers provides a JUnit extension which can be used to manage containers in your tests.
The extension is activated by applying the javadoc:org.testcontainers.junit.jupiter.Testcontainers[format=annotation] annotation from Testcontainers to your test class.
When you have containers declared in this way, then you can have these containers managed by Spring Boot as beans.
All that is needed to do that is adding javadoc:org.springframework.boot.testcontainers.context.ImportTestcontainers[format=annotation] to your configuration class as in:
You can then use the javadoc:org.testcontainers.junit.jupiter.Container[format=annotation] annotation on static container fields.
include-code::importcontainers/MyConfiguration[]
The javadoc:org.testcontainers.junit.jupiter.Testcontainers[format=annotation] annotation can be used on vanilla JUnit tests, or in combination with javadoc:org.springframework.boot.test.context.SpringBootTest[format=annotation]:
TIP: Using interfaces for declaring contains helps with reuse.
When containers are declared in an interface, this can be reused in your javadoc:org.springframework.context.annotation.Configuration[format=annotation] classes and in test classes.
include-code::MyIntegrationTests[]
The example above will start up a Neo4j container before any of the tests are run.
The lifecycle of the container instance is managed by Testcontainers, as described in {url-testcontainers-docs}/test_framework_integration/junit_5/#extension[their official documentation].
NOTE: In most cases, you will additionally need to configure the application to connect to the service running in the container.
[[test.testcontainers.container-lifecycle]]
== Lifecycle of managed containers
If you have used the annotations and extensions provided by Testcontainers, then the lifecycle of container instances is managed by the Testcontainers.
Please refer to the {url-testcontainres-java-doc}[Testcontainers official documentation] for the information about lifecycle of the containers, when managed by the Testcontainers.
[[testing.testcontainers.importing-configuration-interfaces]]
== Importing Container Configuration Interfaces
A common pattern with Testcontainers is to declare the container instances as static fields in an interface.
For example, the following interface declares two containers, one named `mongo` of type javadoc:org.testcontainers.containers.MongoDBContainer[] and another named `neo4j` of type javadoc:org.testcontainers.containers.Neo4jContainer.Neo4jContainer[]:
include-code::MyContainers[]
When you have containers declared in this way, you can reuse their configuration in multiple tests by having the test classes implement the interface.
It's also possible to use the same interface configuration in your Spring Boot tests.
To do so, add javadoc:org.springframework.boot.testcontainers.context.ImportTestcontainers[format=annotation] to your test configuration class:
include-code::MyTestConfiguration[]
[[testing.testcontainers.lifecycle]]
== Lifecycle of Managed Containers
If you have used the annotations and extensions provided by Testcontainers, then the lifecycle of container instances is managed entirely by Testcontainers.
Please refer to the {url-testcontainers-docs}[offical Testcontainers documentation] for the information.
When the containers are managed by Spring as beans, then their lifecycle is managed by Spring:
* Container beans are created and started before all other beans.
* Container beans are stopped after the destruction of all other beans.
When the containers are managed by Spring as beans, then the lifecycle is clearly defined by Spring.
The container beans are created and started before the beans of other types are created.
This process ensures that any beans, which rely on functionality provided by the containers, can use those functionalities.
It also ensures that they are cleaned up whilst the container is still available.
The test containers can be started multiple times.
Like any other beans the test containers are created and started once per application context managed by the TestContext Framework.
For details about how TestContext framework manages the underlying application contexts and beans therein, please refer to the {url-spring-framework-docs}[official Spring documentation].
TIP: When your application beans rely on functionality of containers, prefer configuring the containers as Spring beans to ensure the correct lifecycle behavior.
The container beans are stopped after the destruction of beans of other types.
This ensures that any beans depending on the functionalities provided by the containers are cleaned up first.
TIP: When your application beans rely on functionality of containers, prefer configuring the containers as Spring beans.
When containers are managed as Spring beans, then Spring framework ensures that upon start the container beans are started before any beans relying on them.
On shutdown the application beans depending on container functionalities are cleaned up first, and only then are the containers shut down.
NOTE: Having containers managed by Testcontainers instead of as Spring beans provides no guarantee of order in which beans and containers will shutdown.
NOTE: Having containers managed by Testcontainers instead of as Spring beans provides no guarantee of the order in which beans and containers will shutdown.
It can happen that containers are shutdown before the beans relying on container functionality are cleaned up.
This can lead to exceptions being thrown by client beans due to loss of connection for example.
This can lead to exceptions being thrown by client beans, for example, due to loss of connection.
The containers are stopped as part of the application shutdown process, managed by the TestContext framework.
Container beans are created and started once per application context managed by Spring's TestContext Framework.
For details about how TestContext Framework manages the underlying application contexts and beans therein, please refer to the {url-spring-framework-docs}[Spring Framework documentation].
Container beans are stopped as part of the TestContext Framework's standard application context shutdown process.
When the application context gets shutdown, the containers are shutdown as well.
This usually happens after all tests using that specific cached application context have finished executing, but may happen earlier depending on the caching behavior configured in TestContext Framework.
This usually happens after all tests using that specific cached application context have finished executing.
It may also happen earlier, depending on the caching behavior configured in TestContext Framework.
It is important to note that a single test container instance can be, and often is, retained across execution of tests from multiple test classes.
NOTE: A single test container instance can, and often is, retained across execution of tests from multiple test classes.