Document methods of starting Testcontainer containers

In this commit I have documented three methods of starting containers from
Testcontainer library as part of the Spring Boot tests.

Signed-off-by: Vanio Begic <[email protected]>

Author: thecooldrop

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

@@ -5,14 +5,47 @@ The https://www.testcontainers.org/[Testcontainers] library provides a way to ma
 It integrates with JUnit, allowing you to write a test class that can start up a container before any of the tests run.
 Testcontainers is especially useful for writing integration tests that talk to a real backend service such as MySQL, MongoDB, Cassandra and others.
 
+In following sections we will describe some of the methods you can use to integrate Testcontainers with your tests.
+
+== Using via @Testcontainers JUnit5 extension
+
+The Testcontainers framework provides JUnit5 extensions, which can be used to manage containers in your tests.
+The extension is activated by applying the
+
 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.
+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 framework, as described in official documentation.
+
+== Using via Spring managed beans
+
+The containers provided by Testcontainers framework can be managed by Spring Boot as beans.
+This method is often 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:
+
+include-code::beandeclaration/BeanDeclarationConfig[]
+
+then we can start the container by importing the configuration class in the test class:
+
+include-code::beandeclaration/SpringTest[]
+
+
+== Using via importing container declaration classes
+
+A common pattern with Testcontainers framework 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:
+
+include-code::importcontainers/MyInterface[]
+
+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:
 
+include-code::importcontainers/MyConfiguration[]
 
 [[testing.testcontainers.service-connections]]
 == Service Connections

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/testcontainers/beandeclaration/BeanDeclarationConfig.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.testing.testcontainers.beandeclaration;
+
+import org.testcontainers.containers.MongoDBContainer;
+import org.testcontainers.utility.DockerImageName;
+
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+import org.springframework.context.annotation.Bean;
+
+@TestConfiguration(proxyBeanMethods = false)
+class BeanDeclarationConfig {
+
+	@ServiceConnection
+	@Bean
+	MongoDBContainer container() {
+		return new MongoDBContainer(DockerImageName.parse("mongo:latest"));
+	}
+}

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/testcontainers/beandeclaration/SpringTest.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.testing.testcontainers.beandeclaration;
+
+import org.junit.jupiter.api.Test;
+import org.testcontainers.containers.MongoDBContainer;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.context.annotation.Import;
+
+@SpringBootTest
+@Import(BeanDeclarationConfig.class)
+public class SpringTest {
+
+	@Autowired
+	private MongoDBContainer mongo;
+
+	@Test
+	void doTest() {
+		System.out.println("Mongo db is running: " + this.mongo.isRunning());
+	}
+}

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/testcontainers/importcontainers/MyConfiguration.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.testing.testcontainers.importcontainers;
+
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.boot.testcontainers.context.ImportTestcontainers;
+
+@TestConfiguration(proxyBeanMethods = false)
+@ImportTestcontainers(MyInterface.class)
+class MyConfiguration {
+}

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/testing/testcontainers/importcontainers/MyInterface.java

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2012-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.boot.docs.testing.testcontainers.importcontainers;
+
+import org.testcontainers.containers.MongoDBContainer;
+import org.testcontainers.containers.Neo4jContainer;
+import org.testcontainers.junit.jupiter.Container;
+
+import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
+
+interface MyInterface {
+
+	@Container
+	@ServiceConnection
+	MongoDBContainer mongoContainer = new MongoDBContainer("mongo:5.0");
+
+	@Container
+	@ServiceConnection
+	Neo4jContainer<?> neo4jContainer = new Neo4jContainer<>("neo4j:5");
+
+}

spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/testing/testcontainers/beandeclaration/BeanDeclarationConfig.kt

@@ -0,0 +1,17 @@
+package org.springframework.boot.docs.testing.testcontainers.beandeclaration
+
+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.MongoDBContainer
+import org.testcontainers.utility.DockerImageName
+
+
+@TestConfiguration(proxyBeanMethods = false)
+internal class BeanDeclarationConfig {
+	@ServiceConnection
+	@Bean
+	fun container(): MongoDBContainer {
+		return MongoDBContainer(DockerImageName.parse("mongo:latest"))
+	}
+}

spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/testing/testcontainers/beandeclaration/SpringTest.kt

@@ -0,0 +1,19 @@
+package org.springframework.boot.docs.testing.testcontainers.beandeclaration
+
+import org.junit.jupiter.api.Test
+import org.springframework.beans.factory.annotation.Autowired
+import org.springframework.boot.test.context.SpringBootTest
+import org.springframework.context.annotation.Import
+import org.testcontainers.containers.MongoDBContainer
+
+@SpringBootTest
+@Import(BeanDeclarationConfig::class)
+class SpringTest {
+	@Autowired
+	private val mongo: MongoDBContainer? = null
+
+	@Test
+	fun doTest() {
+		println("Mongo db is running: " + mongo!!.isRunning)
+	}
+}