GitHub-Spring
/
spring-boot
mirror of https://github.com/spring-projects/spring-boot.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Rework SpringApplicationTest documentation 

Closes gh-5477
pull/5552/head
Phillip Webb 10 years ago
parent
33f0ea3480
commit
c167e4fd0e
2 changed files with 37 additions and 116 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 9
      spring-boot-docs/src/main/asciidoc/howto.adoc
  2. 144
      spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

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

@ -543,15 +543,16 @@ that and be sure that it has initialized is to add a `@Bean` of type @@ -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
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;

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

@ -4349,25 +4349,29 @@ One thing to watch out for though is that the external properties, logging and o @@ -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 @@ -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
<<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>>
[[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
<<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
`@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. @@ -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. @@ -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]]
@ -4832,7 +4752,7 @@ Spring's test framework into Spock. @@ -4832,7 +4752,7 @@ Spring's test framework into Spock.
NOTE: The annotations <<boot-features-testing-spring-boot-applications,described above>>
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.

Write Preview
Loading…
Cancel
Save