root
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Actions 12 Packages Projects Releases Wiki Activity

Rework SpringApplicationTest documentation 

Closes gh-5477
This commit is contained in:
Phillip Webb 2016-03-31 16:58:47 -07:00
parent 33f0ea3480
commit c167e4fd0e
2 changed files with 34 additions and 113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
spring-boot-docs/src/main/asciidoc/howto.adoc
View File

@ -543,15 +543,16 @@ that and be sure that it has initialized is to add a `@Bean` of type
`ApplicationListener<EmbeddedServletContainerInitializedEvent>` and pull the container `ApplicationListener<EmbeddedServletContainerInitializedEvent>` and pull the container
out of the event when it is published. out of the event when it is published.
A useful practice for use with `@WebIntegrationTest` is to set `server.port=0` Tests that use `@SpringApplicationTest(webEnvironment=WebEnvironment.RANDOM_PORT)` can
and then inject the actual port. For example: also inject the actual port into a field using the `@LocalServerPort` annotation. For
example:
[source,java,indent=0,subs="verbatim,quotes,attributes"] [source,java,indent=0,subs="verbatim,quotes,attributes"]
---- ----
@RunWith(SpringJUnit4ClassRunner.class) @RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(SampleDataJpaApplication.class) @SpringApplicationConfiguration(SampleDataJpaApplication.class)
@WebIntegrationTest("server.port:0") @SpringApplicationTest(webEnvironment=WebEnvironment.RANDOM_PORT)
public class CityRepositoryIntegrationTests { public class MyWebIntegrationTests {
@Autowired @Autowired
EmbeddedWebApplicationContext server; EmbeddedWebApplicationContext server;

138
spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc
View File

@ -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 features of Spring Boot are only installed in the context by default if you use
`SpringApplication` to create it. `SpringApplication` to create it.
Spring Boot provides three annotations which can be used as an alternative the standard Spring Boot provides a `@SpringApplicationTest` annotation which can be used as an
`spring-test` `@ContextConfiguration` annotation when you need Spring Boot features. All alternative the standard `spring-test` `@ContextConfiguration` annotation when you need
three work by creating the `ApplicationContext` used in your tests via Spring Boot features. The annotation works by creating the `ApplicationContext` used
`SpringApplication`. in your tests via `SpringApplication`.
The specific annotation that you choose will depend on the type of test that you are writing: You can use the `webEnvironment` attribute of `@SpringApplicationTest` to further refine
how your tests will run:
* `@SpringApplicationTest` -- Loads an `ApplicationContext` or `WebApplicationContext` * `MOCK` -- Loads a `WebApplicationContext` and provides a mock servlet environment.
(depending on your classpath) using `SpringApplication` and provides a mock servlet environment. Embedded servlet containers are not started Embedded servlet containers are not started when using this annotation. If servlet
when using this annotation. APIs are not on your classpath this mode will transparantly fallback to creating a
* `@WebIntegrationTest` -- Loads an `EmbeddedWebApplicationContext` using regular non-web `ApplicationContext`.
`SpringApplication` and provides a real servlet environment. Embedded servlet containers * `RANDOM_PORT` -- Loads an `EmbeddedWebApplicationContext` and provides a real
are started and listening on a defined or random port. servlet environment. Embedded servlet containers are started and listening on a random
* `@IntegrationTest` -- Loads an `ApplicationContext` using `SpringApplication` but does port.
not provides _any_ servlet environment (mock or otherwise). * `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`, `@WebIntegrationTest` and NOTE: In addition to `@SpringApplicationTest` a number of other annotations are also
`@IntegrationTest` a number of other annotations are also provided for testing more provided for testing more specific slices of an application. See below for details.
specific slices of an application. See below for details.
TIP: Don't forget to also add `@RunWith(SpringRunner.class)` to your test, otherwise TIP: Don't forget to also add `@RunWith(SpringRunner.class)` to your test, otherwise
the annotations will be ignored. 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 [[boot-features-testing-spring-boot-applications-working-with-random-ports]]
classpath. If you're developing a non-web application, the regular ==== Working with random ports
`ApplicationContext` is used. 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)`
The `@Configuration` classes to load can either be explicitly defined using an available port will be picked at random each time your test runs.
`@ContextConfiguration`, specified as inner-classes or
<<boot-features-testing-spring-boot-applications-detecting-config, detected automatically>>
[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-detecting-config, detected automatically>>
The `@LocalServerPort` annotation can be used to
<<howto-discover-the-http-port-at-runtime,inject the actual port used>> into your test.
For convenience, tests that need to make REST calls to the started server can additionally 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. `@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] [source,java,indent=0]
---- ----
import org.junit.*; import org.junit.*;
@ -4483,7 +4443,7 @@ random ports.
import static org.assertj.core.api.Assertions.* import static org.assertj.core.api.Assertions.*
@RunWith(SpringRunner.class) @RunWith(SpringRunner.class)
@WebIntegrationTest(randomPort=true) @SpringApplicationTest(webEnvironment=WebEnvironment.RANDOM_PORT)
public class MyWebIntegrationTests { public class MyWebIntegrationTests {
@Autowired @Autowired
@ -4498,46 +4458,6 @@ random ports.
} }
---- ----
See <<howto-discover-the-http-port-at-runtime>> 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
<<boot-features-testing-spring-boot-applications-detecting-config, detected automatically>>
[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]] [[boot-features-testing-spring-boot-applications-mocking-beans]]
@ -4832,7 +4752,7 @@ Spring's test framework into Spock.
NOTE: The annotations <<boot-features-testing-spring-boot-applications,described above>> NOTE: The annotations <<boot-features-testing-spring-boot-applications,described above>>
can be used with Spock, i.e. you can annotate your `Specification` with 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.