diff --git a/spring-boot-docs/src/main/asciidoc/howto.adoc b/spring-boot-docs/src/main/asciidoc/howto.adoc index 390806331d..c8783d161f 100644 --- a/spring-boot-docs/src/main/asciidoc/howto.adoc +++ b/spring-boot-docs/src/main/asciidoc/howto.adoc @@ -543,15 +543,16 @@ that and be sure that it has initialized is to add a `@Bean` of type `ApplicationListener` and pull the container out of the event when it is published. -A useful practice for use with `@WebIntegrationTest` is to set `server.port=0` -and then inject the actual port. For example: +Tests that use `@SpringApplicationTest(webEnvironment=WebEnvironment.RANDOM_PORT)` can +also inject the actual port into a field using the `@LocalServerPort` annotation. For +example: [source,java,indent=0,subs="verbatim,quotes,attributes"] ---- @RunWith(SpringJUnit4ClassRunner.class) @SpringApplicationConfiguration(SampleDataJpaApplication.class) - @WebIntegrationTest("server.port:0") - public class CityRepositoryIntegrationTests { + @SpringApplicationTest(webEnvironment=WebEnvironment.RANDOM_PORT) + public class MyWebIntegrationTests { @Autowired EmbeddedWebApplicationContext server; diff --git a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc index 406fe4d4b1..9d7210be9f 100644 --- a/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc +++ b/spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc @@ -4349,25 +4349,29 @@ One thing to watch out for though is that the external properties, logging and o features of Spring Boot are only installed in the context by default if you use `SpringApplication` to create it. -Spring Boot provides three annotations which can be used as an alternative the standard -`spring-test` `@ContextConfiguration` annotation when you need Spring Boot features. All -three work by creating the `ApplicationContext` used in your tests via -`SpringApplication`. - -The specific annotation that you choose will depend on the type of test that you are writing: - -* `@SpringApplicationTest` -- Loads an `ApplicationContext` or `WebApplicationContext` - (depending on your classpath) using `SpringApplication` and provides a mock servlet environment. Embedded servlet containers are not started - when using this annotation. -* `@WebIntegrationTest` -- Loads an `EmbeddedWebApplicationContext` using - `SpringApplication` and provides a real servlet environment. Embedded servlet containers - are started and listening on a defined or random port. -* `@IntegrationTest` -- Loads an `ApplicationContext` using `SpringApplication` but does - not provides _any_ servlet environment (mock or otherwise). - -NOTE: In addition to `@SpringApplicationTest`, `@WebIntegrationTest` and -`@IntegrationTest` a number of other annotations are also provided for testing more -specific slices of an application. See below for details. +Spring Boot provides a `@SpringApplicationTest` annotation which can be used as an +alternative the standard `spring-test` `@ContextConfiguration` annotation when you need +Spring Boot features. The annotation works by creating the `ApplicationContext` used +in your tests via `SpringApplication`. + +You can use the `webEnvironment` attribute of `@SpringApplicationTest` to further refine +how your tests will run: + +* `MOCK` -- Loads a `WebApplicationContext` and provides a mock servlet environment. + Embedded servlet containers are not started when using this annotation. If servlet + APIs are not on your classpath this mode will transparantly fallback to creating a + regular non-web `ApplicationContext`. +* `RANDOM_PORT` -- Loads an `EmbeddedWebApplicationContext` and provides a real + servlet environment. Embedded servlet containers are started and listening on a random + port. +* `DEFINED_PORT` -- Loads an `EmbeddedWebApplicationContext` and provides a real + servlet environment. Embedded servlet containers are started and listening on a defined + port (i.e from your `application.properties` or on the default port `8080`). +* `NONE` -- Loads an `ApplicationContext` using `SpringApplication` but does not provides + _any_ servlet environment (mock or otherwise). + +NOTE: In addition to `@SpringApplicationTest` a number of other annotations are also +provided for testing more specific slices of an application. See below for details. TIP: Don't forget to also add `@RunWith(SpringRunner.class)` to your test, otherwise the annotations will be ignored. @@ -4416,62 +4420,18 @@ will need to register the `TypeExcludeFilter` with it. See -[[boot-features-testing-spring-boot-applications-using-springapplicationtest]] -==== Using @SpringApplicationTest -Use the `@SpringApplicationTest` annotation to load a `ApplicationContext` or -`WebApplicationContext` via `SpringApplication` and configure it with a mock -servlet environment. Embedded servlet containers will not be started when using -`@SpringApplicationTest`. -A `WebApplicationContext` is created when Servlet API jars are present on your -classpath. If you're developing a non-web application, the regular -`ApplicationContext` is used. - -The `@Configuration` classes to load can either be explicitly defined using -`@ContextConfiguration`, specified as inner-classes or -<> - -[source,java,indent=0] ----- - import org.junit.*; - import org.junit.runner.*; - import org.springframework.beans.factory.annotation.*; - import org.springframework.boot.test.context.*; - import org.springframework.test.context.junit4.*; - - @RunWith(SpringRunner.class) - @SpringApplicationTest - public class MySpringApplicationTests { - - @Autowired - private MyComponent component; - - // ... tests - - } ----- - - - -[[boot-features-testing-spring-boot-applications-using-webintegrationtest]] -==== Using @WebIntegrationTest -Use the `@WebIntegrationTest` annotation to load a `WebApplicationContext` via -`SpringApplication` and configure it with fully running server listening on the appropriate -port. - -The `@Configuration` classes to load can either be explicitly defined using -`@ContextConfiguration`, specified as inner-classes or -<> +[[boot-features-testing-spring-boot-applications-working-with-random-ports]] +==== Working with random ports +If you need to start a full running server for tests, we recommend that you use random +ports. If you use `@SpringApplicationTest(webEnvironment=WebEnvironment.RANDOM_PORT)` +an available port will be picked at random each time your test runs. +The `@LocalServerPort` annotation can be used to +<> into your test. For convenience, tests that need to make REST calls to the started server can additionally `@Autowire` a `TestRestTemplate` which will resolve relative links to the running server. -To change the port you can add environment properties to `@WebIntegrationTest` as colon- -or equals-separated name-value pairs, e.g. `@WebIntegrationTest("server.port:9000")`. -Additionally you can set the `server.port` and `management.port` properties to `0` -or use the `randomPort` attribute in order to run your integration tests using -random ports. - [source,java,indent=0] ---- import org.junit.*; @@ -4483,7 +4443,7 @@ random ports. import static org.assertj.core.api.Assertions.* @RunWith(SpringRunner.class) - @WebIntegrationTest(randomPort=true) + @SpringApplicationTest(webEnvironment=WebEnvironment.RANDOM_PORT) public class MyWebIntegrationTests { @Autowired @@ -4498,46 +4458,6 @@ random ports. } ---- -See <> for a description of how you can discover -the actual port that was allocated for the duration of the tests if you're not using the -injected `TestRestTemplate`. - - - -[[boot-features-testing-spring-boot-applications-using-integrationtest]] -==== Using @IntegrationTest -Use the `@IntegrationTest` annotation to load an `ApplicationContext` via -`SpringApplication` for non web-applications. Mock servlet support is explicitly disabled -for tests annotated with `@IntegrationTest`. - -The `@Configuration` classes to load can either be explicitly defined using -`@ContextConfiguration`, specified as inner-classes or -<> - -[source,java,indent=0] ----- - import org.junit.*; - import org.junit.runner.*; - import org.springframework.beans.factory.annotation.*; - import org.springframework.boot.test.context.*; - import org.springframework.test.context.junit4.*; - - @RunWith(SpringRunner.class) - @IntegrationTest - public class MyIntegrationTests { - - @Autowired - private MyComponent component; - - // ... tests - - } ----- - -NOTE: Although it's possible to use the `@WebAppConfiguration` annotation in combination -with `@IntegrationTest` if you want to start a full web server, the `@WebIntegrationTest` -annotation is generally preferable. - [[boot-features-testing-spring-boot-applications-mocking-beans]] @@ -4832,7 +4752,7 @@ Spring's test framework into Spock. NOTE: The annotations <> can be used with Spock, i.e. you can annotate your `Specification` with -`@WebIntegrationTest` to suit the needs of your tests. +`@SpringApplicationTest` to suit the needs of your tests.