From af426e383f540930f5b6129e3afb61140d8dc00a Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Fri, 24 Aug 2018 18:05:05 +0200 Subject: [PATCH] Review slice documentation to clarify the scope and alternative options Closes gh-13810 --- .../main/asciidoc/spring-boot-features.adoc | 117 +++++++++++------- 1 file changed, 73 insertions(+), 44 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index a00302c04ee..785d11e6341 100644 --- a/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -6411,9 +6411,10 @@ providing a `@...Test` annotation that loads the `ApplicationContext` and one or more `@AutoConfigure...` annotations that can be used to customize auto-configuration settings. -NOTE: Each slice loads a very restricted set of auto-configuration classes. If you need -to exclude one of them, most `@...Test` annotations provide an `excludeAutoConfiguration` -attribute. Alternatively, you can use `@ImportAutoConfiguration#exclude`. +NOTE: Each slice restricts component scan to appropriate components and loads a very +restricted set of auto-configuration classes. If you need to exclude one of them, +most `@...Test` annotations provide an `excludeAutoConfiguration` attribute. +Alternatively, you can use `@ImportAutoConfiguration#exclude`. TIP: It is also possible to use the `@AutoConfigure...` annotations with the standard `@SpringBootTest` annotation. You can use this combination if you are not interested in @@ -6431,10 +6432,13 @@ mapper, which can be one of the following libraries: * `Gson` * `Jsonb` +TIP: A list of the auto-configuration that is enabled by `@JsonTest` can be +<>. + If you need to configure elements of the auto-configuration, you can use the `@AutoConfigureJsonTesters` annotation. -Spring Boot includes AssertJ-based helpers that work with the JSONassert and JsonPath +Spring Boot includes AssertJ-based helpers that work with the JSONAssert and JsonPath libraries to check that JSON appears as expected. The `JacksonTester`, `GsonTester`, `JsonbTester`, and `BasicJsonTester` classes can be used for Jackson, Gson, Jsonb, and Strings respectively. Any helper fields on the test class can be `@Autowired` when using @@ -6485,9 +6489,6 @@ NOTE: JSON helper classes can also be used directly in standard unit tests. To d call the `initFields` method of the helper in your `@Before` method if you do not use `@JsonTest`. -A list of the auto-configuration that is enabled by `@JsonTest` can be -<>. - [[boot-features-testing-spring-boot-applications-testing-autoconfigured-mvc-tests]] @@ -6498,6 +6499,9 @@ scanned beans to `@Controller`, `@ControllerAdvice`, `@JsonComponent`, `Converte `GenericConverter`, `Filter`, `WebMvcConfigurer`, and `HandlerMethodArgumentResolver`. Regular `@Component` beans are not scanned when using this annotation. +TIP: A list of the auto-configuration settings that are enabled by `@WebMvcTest` can be +<>. + TIP: If you need to register extra components, such as the Jackson `Module`, you can import additional configuration classes by using `@Import` on your test. @@ -6591,14 +6595,12 @@ that the driver exits after each test and that a new instance is injected. If yo not want this behavior, you can add `@Scope("singleton")` to your `WebDriver` `@Bean` definition. -A list of the auto-configuration settings that are enabled by `@WebMvcTest` can be -<>. - TIP: Sometimes writing Spring MVC tests is not enough; Spring Boot can help you run <>. + [[boot-features-testing-spring-boot-applications-testing-autoconfigured-webflux-tests]] ==== Auto-configured Spring WebFlux Tests To test that {spring-reference}/web-reactive.html[Spring WebFlux] controllers are @@ -6608,6 +6610,9 @@ auto-configures the Spring WebFlux infrastructure and limits scanned beans to `WebFluxConfigurer`. Regular `@Component` beans are not scanned when the `@WebFluxTest` annotation is used. +TIP: A list of the auto-configuration that is enabled by `@WebFluxTest` can be +<>. + TIP: If you need to register extra components, such as Jackson `Module`, you can import additional configuration classes using `@Import` on your test. @@ -6660,9 +6665,6 @@ example shows a class that uses both `@WebFluxTest` and a `WebTestClient`: TIP: This setup is only supported by WebFlux applications as using `WebTestClient` in a mocked web application only works with WebFlux at the moment. -A list of the auto-configuration that is enabled by `@WebFluxTest` can be -<>. - NOTE: `@WebFluxTest` cannot detect routes registered via the functional web framework. For testing `RouterFunction` beans in the context, consider importing your `RouterFunction` yourself via `@Import` or using `@SpringBootTest`. @@ -6672,6 +6674,7 @@ TIP: Sometimes writing Spring WebFlux tests is not enough; Spring Boot can help full end-to-end tests with an actual server>>. + [[boot-features-testing-spring-boot-applications-testing-autoconfigured-jpa-test]] ==== Auto-configured Data JPA Tests You can use the `@DataJpaTest` annotation to test JPA applications. By default, it @@ -6679,6 +6682,9 @@ configures an in-memory embedded database, scans for `@Entity` classes, and conf Spring Data JPA repositories. Regular `@Component` beans are not loaded into the `ApplicationContext`. +TIP: A list of the auto-configuration settings that are enabled by `@DataJpaTest` can be +<>. + By default, data JPA tests are transactional and roll back at the end of each test. See the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in the Spring Framework Reference Documentation for more details. If that is not what you @@ -6756,16 +6762,16 @@ following example: } ---- -A list of the auto-configuration settings that are enabled by `@DataJpaTest` can be -<>. - [[boot-features-testing-spring-boot-applications-testing-autoconfigured-jdbc-test]] ==== Auto-configured JDBC Tests -`@JdbcTest` is similar to `@DataJpaTest` but is for pure JDBC-related tests. By default, -it also configures an in-memory embedded database and a `JdbcTemplate`. Regular -`@Component` beans are not loaded into the `ApplicationContext`. +`@JdbcTest` is similar to `@DataJpaTest` but is for tests that only require a +`DataSource`. By default, it configures an in-memory embedded database and a +`JdbcTemplate`. Regular `@Component` beans are not loaded into the `ApplicationContext`. + +TIP: A list of the auto-configuration that is enabled by `@JdbcTest` can be +<>. By default, JDBC tests are transactional and roll back at the end of each test. See the {spring-reference}testing.html#testcontext-tx-enabling-transactions[relevant section] in @@ -6794,9 +6800,6 @@ If you prefer your test to run against a real database, you can use the `@AutoConfigureTestDatabase` annotation in the same way as for `DataJpaTest`. (See "<>".) -A list of the auto-configuration that is enabled by `@JdbcTest` can be -<>. - [[boot-features-testing-spring-boot-applications-testing-autoconfigured-jooq-test]] @@ -6805,7 +6808,11 @@ You can use `@JooqTest` in a similar fashion as `@JdbcTest` but for jOOQ-related As jOOQ relies heavily on a Java-based schema that corresponds with the database schema, the existing `DataSource` is used. If you want to replace it with an in-memory database, you can use `@AutoConfigureTestDatabase` to override those settings. (For more about using -jOOQ with Spring Boot, see "<>", earlier in this chapter.) +jOOQ with Spring Boot, see "<>", earlier in this chapter.) Regular +`@Component` beans are not loaded into the `ApplicationContext`. + +TIP: A list of the auto-configuration that is enabled by `@JooqTest` can be +<>. `@JooqTest` configures a `DSLContext`. Regular `@Component` beans are not loaded into the `ApplicationContext`. The following example shows the `@JooqTest` annotation in use: @@ -6833,8 +6840,6 @@ test class as <>. -A list of the auto-configuration that is enabled by `@JooqTest` can be -<>. @@ -6846,6 +6851,9 @@ in-memory embedded MongoDB (if available), configures a `MongoTemplate`, scans f `@Component` beans are not loaded into the `ApplicationContext`. (For more about using MongoDB with Spring Boot, see "<>", earlier in this chapter.) +TIP: A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be +<>. + The following class shows the `@DataMongoTest` annotation in use: [source,java,indent=0] @@ -6886,8 +6894,6 @@ the following example: } ---- -A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be -<>. @@ -6899,6 +6905,9 @@ configures Spring Data Neo4j repositories. Regular `@Component` beans are not lo the `ApplicationContext`. (For more about using Neo4J with Spring Boot, see "<>", earlier in this chapter.) +TIP: A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be +<>. + The following example shows a typical setup for using Neo4J tests in Spring Boot: [source,java,indent=0] @@ -6943,9 +6952,6 @@ as follows: ---- -A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be -<>. - [[boot-features-testing-spring-boot-applications-testing-autoconfigured-redis-test]] @@ -6955,6 +6961,9 @@ You can use `@DataRedisTest` to test Redis applications. By default, it scans fo beans are not loaded into the `ApplicationContext`. (For more about using Redis with Spring Boot, see "<>", earlier in this chapter.) +TIP: A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be +<>. + The following example shows the `@DataRedisTest` annotation in use: [source,java,indent=0] @@ -6975,9 +6984,6 @@ The following example shows the `@DataRedisTest` annotation in use: } ---- -A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be -<>. - [[boot-features-testing-spring-boot-applications-testing-autoconfigured-ldap-test]] @@ -6988,6 +6994,9 @@ classes, and configures Spring Data LDAP repositories. Regular `@Component` bean loaded into the `ApplicationContext`. (For more about using LDAP with Spring Boot, see "<>", earlier in this chapter.) +TIP: A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be +<>. + The following example shows the `@DataLdapTest` annotation in use: [source,java,indent=0] @@ -7028,19 +7037,20 @@ following example: } ---- -A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be -<>. - [[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-client]] ==== Auto-configured REST Clients You can use the `@RestClientTest` annotation to test REST clients. By default, it auto-configures Jackson, GSON, and Jsonb support, configures a `RestTemplateBuilder`, and -adds support for `MockRestServiceServer`. The specific beans that you want to test should -be specified by using the `value` or `components` attribute of `@RestClientTest`, as -shown in the following example: +adds support for `MockRestServiceServer`. Regular `@Component` beans are not loaded into +the `ApplicationContext`. + +TIP: A list of the auto-configuration settings that are enabled by `@RestClientTest` can +be <>. +The specific beans that you want to test should be specified by using the `value` or +`components` attribute of `@RestClientTest`, as shown in the following example: [source,java,indent=0] ---- @@ -7066,9 +7076,6 @@ shown in the following example: } ---- -A list of the auto-configuration settings that are enabled by `@RestClientTest` can be -<>. - [[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs]] @@ -7082,9 +7089,10 @@ in Spring REST Docs. are using Gradle). It can also be used to configure the host, scheme, and port that appears in any documented URIs. + + [[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-mock-mvc]] ===== Auto-configured Spring REST Docs Tests with Mock MVC - `@AutoConfigureRestDocs` customizes the `MockMvc` bean to use Spring REST Docs. You can inject it by using `@Autowired` and use it in your tests as you normally would when using Mock MVC and Spring REST Docs, as shown in the following example: @@ -7163,7 +7171,6 @@ generate the default snippets. The following example shows a [[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs-rest-assured]] ===== Auto-configured Spring REST Docs Tests with REST Assured - `@AutoConfigureRestDocs` makes a `RequestSpecification` bean, preconfigured to use Spring REST Docs, available to your tests. You can inject it by using `@Autowired` and use it in your tests as you normally would when using REST Assured and Spring REST Docs, as shown @@ -7185,6 +7192,28 @@ include::{code-examples}/test/autoconfigure/restdocs/restassured/AdvancedConfigu +[[boot-features-testing-spring-boot-applications-testing-auto-configured-additional-auto-config]] +==== Additional Auto-configuration and Slicing +Each slice provides one or more `@AutoConfigure...` annotations that namely defines the +auto-configurations that should be included as part of a slice. Additional +auto-configurations can be added by creating a custom `@AutoConfigure` annotation or +simply by adding `@ImportAutoConfiguration` to the test as shown in the following example: + +[source,java,indent=0] +---- + @RunWith(SpringRunner.class) + @JdbcTest + @ImportAutoConfiguration(IntegrationAutoConfiguration.class) + public class ExampleJdbcTests { + + } +---- + +NOTE: Make sure to not use the regular `@Import` annotation to import auto-configurations +as they are handled in a specific way by Spring Boot. + + + [[boot-features-testing-spring-boot-applications-testing-user-configuration]] ==== User Configuration and Slicing If you <> in a sensible way, your