Skip to content

Commit

Permalink
Review slice documentation to clarify the scope and alternative options
Browse files Browse the repository at this point in the history 
Closes gh-13810
  • Loading branch information
@snicoll
snicoll committed Aug 24, 2018
1 parent f53e6c7 commit af426e3
Showing 1 changed file with 73 additions and 44 deletions.
117 changes: 73 additions & 44 deletions spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View file
Expand Up @@ -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
Expand All @@ -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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

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
Expand Down Expand Up @@ -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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



[[boot-features-testing-spring-boot-applications-testing-autoconfigured-mvc-tests]]
Expand All @@ -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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

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.

Expand Down Expand Up @@ -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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

TIP: Sometimes writing Spring MVC tests is not enough; Spring Boot can help you run
<<boot-features-testing-spring-boot-applications-testing-with-running-server,
full end-to-end tests with an actual server>>.



[[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
Expand All @@ -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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

TIP: If you need to register extra components, such as Jackson `Module`, you can import
additional configuration classes using `@Import` on your test.

Expand Down Expand Up @@ -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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

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`.
Expand All @@ -6672,13 +6674,17 @@ 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
configures an in-memory embedded database, scans for `@Entity` classes, and configures
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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

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
Expand Down Expand Up @@ -6756,16 +6762,16 @@ following example:
}
----

A list of the auto-configuration settings that are enabled by `@DataJpaTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



[[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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

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
Expand Down Expand Up @@ -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
"<<boot-features-testing-spring-boot-applications-testing-autoconfigured-jpa-test>>".)

A list of the auto-configuration that is enabled by `@JdbcTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



[[boot-features-testing-spring-boot-applications-testing-autoconfigured-jooq-test]]
Expand All @@ -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 "<<boot-features-jooq>>", earlier in this chapter.)
jOOQ with Spring Boot, see "<<boot-features-jooq>>", 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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

`@JooqTest` configures a `DSLContext`. Regular `@Component` beans are not loaded into the
`ApplicationContext`. The following example shows the `@JooqTest` annotation in use:
Expand Down Expand Up @@ -6833,8 +6840,6 @@ test class as
<<boot-features-testing-spring-boot-applications-testing-autoconfigured-jdbc-test,shown
in the JDBC example>>.

A list of the auto-configuration that is enabled by `@JooqTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



Expand All @@ -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 "<<boot-features-mongodb>>", earlier in this chapter.)

TIP: A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

The following class shows the `@DataMongoTest` annotation in use:

[source,java,indent=0]
Expand Down Expand Up @@ -6886,8 +6894,6 @@ the following example:
}
----

A list of the auto-configuration settings that are enabled by `@DataMongoTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



Expand All @@ -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
"<<boot-features-neo4j>>", earlier in this chapter.)

TIP: A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

The following example shows a typical setup for using Neo4J tests in Spring Boot:

[source,java,indent=0]
Expand Down Expand Up @@ -6943,9 +6952,6 @@ as follows:
----


A list of the auto-configuration settings that are enabled by `@DataNeo4jTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



[[boot-features-testing-spring-boot-applications-testing-autoconfigured-redis-test]]
Expand All @@ -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 "<<boot-features-redis>>", earlier in this chapter.)

TIP: A list of the auto-configuration settings that are enabled by `@DataRedisTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

The following example shows the `@DataRedisTest` annotation in use:

[source,java,indent=0]
Expand All @@ -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
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



[[boot-features-testing-spring-boot-applications-testing-autoconfigured-ldap-test]]
Expand All @@ -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 "<<boot-features-ldap>>", earlier in this chapter.)

TIP: A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

The following example shows the `@DataLdapTest` annotation in use:

[source,java,indent=0]
Expand Down Expand Up @@ -7028,19 +7037,20 @@ following example:
}
----

A list of the auto-configuration settings that are enabled by `@DataLdapTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



[[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 <<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.

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]
----
Expand All @@ -7066,9 +7076,6 @@ shown in the following example:
}
----

A list of the auto-configuration settings that are enabled by `@RestClientTest` can be
<<appendix-test-auto-configuration#test-auto-configuration,found in the appendix>>.



[[boot-features-testing-spring-boot-applications-testing-autoconfigured-rest-docs]]
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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 <<using-boot-structuring-your-code, structure your code>> in a sensible way, your
Expand Down

0 comments on commit af426e3

Please sign in to comment.