From 1a0b9bdcd020012932b2247d33ff143e057f76ed Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Sun, 16 Apr 2023 21:20:22 -0700 Subject: [PATCH] Move Testcontainers documentation from howto to features Closes gh-35018 --- .../docs/asciidoc/anchor-rewrite.properties | 4 + .../src/docs/asciidoc/features/testing.adoc | 102 ++++++++++++++++++ .../src/docs/asciidoc/howto/testing.adoc | 101 ----------------- .../dynamicproperties/MyIntegrationTests.java | 2 +- .../MyIntegrationTests.java | 2 +- .../vanilla/MyIntegrationTests.java | 2 +- .../dynamicproperties/MyIntegrationTests.kt | 2 +- .../serviceconnections/MyIntegrationTests.kt | 2 +- .../vanilla/MyIntegrationTests.kt | 2 +- 9 files changed, 112 insertions(+), 107 deletions(-) rename spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/{howto => features}/testing/testcontainers/dynamicproperties/MyIntegrationTests.java (93%) rename spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/{howto => features}/testing/testcontainers/serviceconnections/MyIntegrationTests.java (92%) rename spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/{howto => features}/testing/testcontainers/vanilla/MyIntegrationTests.java (93%) rename spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/{howto => features}/testing/testcontainers/dynamicproperties/MyIntegrationTests.kt (93%) rename spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/{howto => features}/testing/testcontainers/serviceconnections/MyIntegrationTests.kt (92%) rename spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/{howto => features}/testing/testcontainers/vanilla/MyIntegrationTests.kt (93%) diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties index 44916e5ae4a..b5edc78263b 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/anchor-rewrite.properties @@ -1013,3 +1013,7 @@ data.nosql.elasticsearch.connecting-using-rest.webclient=data.nosql.elasticsearc getting-started.first-application.code.enable-auto-configuration=getting-started.first-application.code.spring-boot-application actuator.tracing=actuator.http-exchanges actuator.tracing.custom=actuator.http-exchanges.custom + +# Spring Boot 3.0 - 3.1 migrations +howto.testing.testcontainers=features.testing.testcontainers +howto.testing.testcontainers.dynamic-properties=features.testing.testcontainers.dynamic-properties diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/testing.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/testing.adoc index fe8e1559fb4..e23b8173d52 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/testing.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/features/testing.adoc @@ -902,6 +902,108 @@ See https://spockframework.org/spock/docs/2.2-M1/modules.html#_spring_module[the +[[features.testing.testcontainers]] +=== Testcontainers +The https://www.testcontainers.org/[Testcontainers] library provides a way to manage services running inside Docker containers. +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. + +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. + + + +[[features.testing.testcontainers.service-connections]] +==== Service Connections +A service connection is a connection to any remote service. +Spring Boot's auto-configuration can consume the details of a service connection and use them to establish a connection to a remote service. +When doing so, the connection details take precedence over any connection-related configuration properties. + +When using Testcontainers, connection details can be automatically created for a service running in a container by annotating the container field in the test class. + +include::code:MyIntegrationTests[] + +Thanks to `@ServiceConnection`, the above configuration allows Neo4j-related beans in the application to communicate with Neo4j running inside the Testcontainers-managed Docker container. +This is done by automatically defining a `Neo4jConnectionDetails` bean which is then used by the Neo4j auto-configuration, overriding any connection-related configuration properties. + +Service connection annotations are processed by `ContainerConnectionDetailsFactory` classes registered with `spring.factories`. +A `ContainerConnectionDetailsFactory` can create a `ConnectionDetails` bean based on a specific `Container` subclass, or the Docker image name. + +The following service connection factories are provided in the `spring-boot-testcontainers` jar: + +|=== +| Connection Details | Matched on + +| `CassandraConnectionDetails` +| Containers of type `CassandraContainer` + +| `CouchbaseConnectionDetails` +| Containers of type `CouchbaseContainer` + +| `ElasticsearchConnectionDetails` +| Containers of type `ElasticsearchContainer` + +| `FlywayConnectionDetails` +| Containers of type `JdbcDatabaseContainer` + +| `InfluxDbConnectionDetails` +| Containers of type `InfluxDBContainer` + +| `JdbcConnectionDetails` +| Containers of type `JdbcDatabaseContainer` + +| `KafkaConnectionDetails` +| Containers of type `KafkaContainer` + +| `LiquibaseConnectionDetails` +| Containers of type `JdbcDatabaseContainer` + +| `MongoConnectionDetails` +| Containers of type `MongoDBContainer` + +| `Neo4jConnectionDetails` +| Containers of type `Neo4jContainer` + +| `R2dbcConnectionDetails` +| Containers of type `MariaDBContainer`, `MSSQLServerContainer`, `MySQLContainer` or `PostgreSQLContainer` + +| `RabbitConnectionDetails` +| Containers of type `RabbitMQContainer` + +| `RedisConnectionDetails` +| Containers named "redis" +|=== + +[TIP] +==== +By default all applicable connection details beans will be created for a given `Container`. +For example, a `PostgreSQLContainer` will create both `JdbcConnectionDetails` and `R2dbcConnectionDetails`. + +If you want to create only a subset of the applicable types, you can use the `type` attribute of `@ServiceConnection`. +==== + +By default `Container.getDockerImageName()` is used to obtain the name used to find connection details. +If you are using a custom docker image, you can use the `name` attribute of `@ServiceConnection` to override it. + +For example, if you have a `GenericContainer` using a Docker image of `registry.mycompany.com/mirror/myredis`, you'd use `@ServiceConnection(name="redis")` to ensure `RedisConnectionDetails` are created. + + + +[[features.testing.testcontainers.dynamic-properties]] +==== Dynamic Properties +A slightly more verbose but also more flexible alternative to service connections is `@DynamicPropertySource`. +A static `@DynamicPropertySource` method allows adding dynamic property values to the Spring Environment. + +include::code:MyIntegrationTests[] + +The above configuration allows Neo4j-related beans in the application to communicate with Neo4j running inside the Testcontainers-managed Docker container. + + + [[features.testing.utilities]] === Test Utilities A few test utility classes that are generally useful when testing your application are packaged as part of `spring-boot`. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/testing.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/testing.adoc index af6fac0ce94..2c76b8689b8 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/testing.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/howto/testing.adoc @@ -18,107 +18,6 @@ For additional details on Spring Security's testing support, see Spring Security -[[howto.testing.testcontainers]] -=== Use Testcontainers for Integration Testing -The https://www.testcontainers.org/[Testcontainers] library provides a way to manage services running inside Docker containers. -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. - -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. - - - -[[howto.testing.testcontainers.service-connections]] -==== Service Connections -A service connection is a connection to any remote service. -Spring Boot's auto-configuration can consume the details of a service connection and use them to establish a connection to a remote service. -When doing so, the connection details take precedence over any connection-related configuration properties. - -When using Testcontainers, connection details can be automatically created for a service running in a container by annotating the container field in the test class. - -include::code:MyIntegrationTests[] - -Thanks to `@ServiceConnection`, the above configuration allows Neo4j-related beans in the application to communicate with Neo4j running inside the Testcontainers-managed Docker container. -This is done by automatically defining a `Neo4jConnectionDetails` bean which is then used by the Neo4j auto-configuration, overriding any connection-related configuration properties. - -Service connection annotations are processed by `ContainerConnectionDetailsFactory` classes registered with `spring.factories`. -A `ContainerConnectionDetailsFactory` can create a `ConnectionDetails` bean based on a specific `Container` subclass, or the Docker image name. - -The following service connection factories are provided in the `spring-boot-testcontainers` jar: - -|=== -| Connection Details | Matched on - -| `CassandraConnectionDetails` -| Containers of type `CassandraContainer` - -| `CouchbaseConnectionDetails` -| Containers of type `CouchbaseContainer` - -| `ElasticsearchConnectionDetails` -| Containers of type `ElasticsearchContainer` - -| `FlywayConnectionDetails` -| Containers of type `JdbcDatabaseContainer` - -| `InfluxDbConnectionDetails` -| Containers of type `InfluxDBContainer` - -| `JdbcConnectionDetails` -| Containers of type `JdbcDatabaseContainer` - -| `KafkaConnectionDetails` -| Containers of type `KafkaContainer` - -| `LiquibaseConnectionDetails` -| Containers of type `JdbcDatabaseContainer` - -| `MongoConnectionDetails` -| Containers of type `MongoDBContainer` - -| `Neo4jConnectionDetails` -| Containers of type `Neo4jContainer` - -| `R2dbcConnectionDetails` -| Containers of type `MariaDBContainer`, `MSSQLServerContainer`, `MySQLContainer` or `PostgreSQLContainer` - -| `RabbitConnectionDetails` -| Containers of type `RabbitMQContainer` - -| `RedisConnectionDetails` -| Containers named "redis" -|=== - -[TIP] -==== -By default all applicable connection details beans will be created for a given `Container`. -For example, a `PostgreSQLContainer` will create both `JdbcConnectionDetails` and `R2dbcConnectionDetails`. - -If you want to create only a subset of the applicable types, you can use the `type` attribute of `@ServiceConnection`. -==== - -By default `Container.getDockerImageName()` is used to obtain the name used to find connection details. -If you are using a custom docker image, you can use the `name` attribute of `@ServiceConnection` to override it. - -For example, if you have a `GenericContainer` using a Docker image of `registry.mycompany.com/mirror/myredis`, you'd use `@ServiceConnection(name="redis")` to ensure `RedisConnectionDetails` are created. - - - -[[howto.testing.testcontainers.dynamic-properties]] -==== Dynamic Properties -A slightly more verbose but also more flexible alternative to service connections is `@DynamicPropertySource`. -A static `@DynamicPropertySource` method allows adding dynamic property values to the Spring Environment. - -include::code:/MyIntegrationTests[] - -The above configuration allows Neo4j-related beans in the application to communicate with Neo4j running inside the Testcontainers-managed Docker container. - - [[howto.testing.slice-tests]] === Structure `@Configuration` classes for inclusion in slice tests diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/dynamicproperties/MyIntegrationTests.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/dynamicproperties/MyIntegrationTests.java similarity index 93% rename from spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/dynamicproperties/MyIntegrationTests.java rename to spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/dynamicproperties/MyIntegrationTests.java index 58f734d2046..79b8603f972 100644 --- a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/dynamicproperties/MyIntegrationTests.java +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/dynamicproperties/MyIntegrationTests.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.boot.docs.howto.testing.testcontainers.dynamicproperties; +package org.springframework.boot.docs.features.testing.testcontainers.dynamicproperties; import org.junit.jupiter.api.Test; import org.testcontainers.containers.Neo4jContainer; diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/serviceconnections/MyIntegrationTests.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyIntegrationTests.java similarity index 92% rename from spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/serviceconnections/MyIntegrationTests.java rename to spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyIntegrationTests.java index ed83e6ad09b..6d49311caf9 100644 --- a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/serviceconnections/MyIntegrationTests.java +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyIntegrationTests.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.boot.docs.howto.testing.testcontainers.serviceconnections; +package org.springframework.boot.docs.features.testing.testcontainers.serviceconnections; import org.junit.jupiter.api.Test; import org.testcontainers.containers.Neo4jContainer; diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/vanilla/MyIntegrationTests.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/vanilla/MyIntegrationTests.java similarity index 93% rename from spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/vanilla/MyIntegrationTests.java rename to spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/vanilla/MyIntegrationTests.java index ddb8ce7d387..df086d53d25 100644 --- a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/howto/testing/testcontainers/vanilla/MyIntegrationTests.java +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/features/testing/testcontainers/vanilla/MyIntegrationTests.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.boot.docs.howto.testing.testcontainers.vanilla; +package org.springframework.boot.docs.features.testing.testcontainers.vanilla; import org.junit.jupiter.api.Test; import org.testcontainers.containers.Neo4jContainer; diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/dynamicproperties/MyIntegrationTests.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/dynamicproperties/MyIntegrationTests.kt similarity index 93% rename from spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/dynamicproperties/MyIntegrationTests.kt rename to spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/dynamicproperties/MyIntegrationTests.kt index fa3c9c91100..bce7aa1b2e1 100644 --- a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/dynamicproperties/MyIntegrationTests.kt +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/dynamicproperties/MyIntegrationTests.kt @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.boot.docs.howto.testing.testcontainers.dynamicproperties +package org.springframework.boot.docs.features.testing.testcontainers.dynamicproperties import org.junit.jupiter.api.Test import org.springframework.boot.test.context.SpringBootTest diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/serviceconnections/MyIntegrationTests.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyIntegrationTests.kt similarity index 92% rename from spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/serviceconnections/MyIntegrationTests.kt rename to spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyIntegrationTests.kt index f79279a34c8..0ff93f611cc 100644 --- a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/serviceconnections/MyIntegrationTests.kt +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/serviceconnections/MyIntegrationTests.kt @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.boot.docs.howto.testing.testcontainers.serviceconnection +package org.springframework.boot.docs.features.testing.testcontainers.serviceconnections import org.junit.jupiter.api.Test import org.testcontainers.containers.Neo4jContainer diff --git a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/vanilla/MyIntegrationTests.kt b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/vanilla/MyIntegrationTests.kt similarity index 93% rename from spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/vanilla/MyIntegrationTests.kt rename to spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/vanilla/MyIntegrationTests.kt index 1aaea0d120f..90f55c8bddc 100644 --- a/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/howto/testing/testcontainers/vanilla/MyIntegrationTests.kt +++ b/spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/features/testing/testcontainers/vanilla/MyIntegrationTests.kt @@ -14,7 +14,7 @@ * limitations under the License. */ -package org.springframework.boot.docs.howto.testing.testcontainers.vanilla +package org.springframework.boot.docs.features.testing.testcontainers.vanilla import org.junit.jupiter.api.Test import org.springframework.boot.test.context.SpringBootTest