From a1ef3f070a9ddfbfc773607a79ba4b608a9d4b77 Mon Sep 17 00:00:00 2001 From: Stephane Nicoll Date: Thu, 19 Jul 2018 16:40:24 +0200 Subject: [PATCH] Improve documentation for using a mock environment with @SpringBootTest Closes gh-13827 --- .../main/asciidoc/spring-boot-features.adoc | 65 +++++++++++++------ .../docs/test/web/MockMvcExampleTests.java | 49 ++++++++++++++ .../web/MockWebTestClientExampleTests.java | 45 +++++++++++++ 3 files changed, 140 insertions(+), 19 deletions(-) create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockMvcExampleTests.java create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockWebTestClientExampleTests.java 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 4e9085afdc..d929c2276b 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 @@ -6100,37 +6100,38 @@ reference documentation. A Spring Boot application is a Spring `ApplicationContext`, so nothing very special has to be done to test it beyond what you would normally do with a vanilla Spring context. - NOTE: External properties, logging, and other features of Spring Boot are installed in the context by default only if you use `SpringApplication` to create it. Spring Boot provides a `@SpringBootTest` annotation, which can be used as an alternative to the standard `spring-test` `@ContextConfiguration` annotation when you need Spring -Boot features. The annotation works by creating the `ApplicationContext` used in your -tests through `SpringApplication`. In addition to `@SpringBootTest` a number of other -annotations are also provided for +Boot features. The annotation works by +<>. In addition to +`@SpringBootTest` a number of other annotations are also provided for <> of an application. TIP: Don't forget to also add `@RunWith(SpringRunner.class)` to your test, otherwise the annotations will be ignored. -You can use the `webEnvironment` attribute of `@SpringBootTest` to further refine how -your tests 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 transparently falls back to creating a regular -non-web `ApplicationContext`. It can be used in conjunction with -`@AutoConfigureMockMvc` for `MockMvc`-based testing of your application. -* `RANDOM_PORT`: Loads an `ServletWebServerApplicationContext` and provides a real -servlet environment. Embedded servlet containers are started and listen on a random -port. -* `DEFINED_PORT`: Loads a `ServletWebServerApplicationContext` and provides a real -servlet environment. Embedded servlet containers are started and listen on a defined port -(from your `application.properties` or on the default port of `8080`). +By default, `@SpringBootTest` will not start a server. You can use the `webEnvironment` +attribute of `@SpringBootTest` to further refine how your tests run: + +* `MOCK`(Default) : Loads a web `ApplicationContext` and provides a mock web +environment. Embedded servers are not started when using this annotation. If a web +environment is not available on your classpath, this mode transparently falls back to +creating a regular non-web `ApplicationContext`. It can be used in conjunction with +<> for mock-based testing of your +web application. +* `RANDOM_PORT`: Loads a `WebServerApplicationContext` and provides a real web +environment. Embedded servers are started and listen on a random port. +* `DEFINED_PORT`: Loads a `WebServerApplicationContext` and provides a real web +environment. Embedded servers are started and listen on a defined port (from your +`application.properties` or on the default port of `8080`). * `NONE`: Loads an `ApplicationContext` by using `SpringApplication` but does not provide -_any_ servlet environment (mock or otherwise). +_any_ web environment (mock or otherwise). NOTE: If your test is `@Transactional`, it rolls back the transaction at the end of each test method by default. However, as using this arrangement with either `RANDOM_PORT` or @@ -6233,6 +6234,32 @@ NOTE: If you directly use `@ComponentScan` (that is, not through {dc-spring-boot}/context/TypeExcludeFilter.{dc-ext}[the Javadoc] for details. +[[boot-features-testing-spring-boot-applications-testing-with-mock-environment]] +==== Testing with a mock environment +By default, `@SpringBootTest` does not start the server. If you have web endpoints that +you want to test against this mock environment, you can additionally configure +{spring-reference}/testing.html#spring-mvc-test-framework[`MockMvc`] as shown in the +following example: + +[source,java,indent=0] +---- +include::{code-examples}/test/web/MockMvcExampleTests.java[tag=test-mock-mvc] +---- + +TIP: If you want to focus only on the web layer and not start a complete +`ApplicationContext`, consider +<>. + +Alternatively, you can configure a +{spring-reference}testing.html#webtestclient-tests[`WebTestClient`] as shown in the +following example: + +[source,java,indent=0] +---- +include::{code-examples}/test/web/MockWebTestClientExampleTests.java[tag=test-mock-web-test-client] +---- + [[boot-features-testing-spring-boot-applications-testing-with-running-server]] diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockMvcExampleTests.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockMvcExampleTests.java new file mode 100644 index 0000000000..e002f1560f --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockMvcExampleTests.java @@ -0,0 +1,49 @@ +/* + * Copyright 2012-2018 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.test.web; + +// tag::test-mock-mvc[] + +import org.junit.Test; +import org.junit.runner.RunWith; + +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.junit4.SpringRunner; +import org.springframework.test.web.servlet.MockMvc; + +import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content; +import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status; + +@RunWith(SpringRunner.class) +@SpringBootTest +@AutoConfigureMockMvc +public class MockMvcExampleTests { + + @Autowired + private MockMvc mvc; + + @Test + public void exampleTest() throws Exception { + this.mvc.perform(get("/")).andExpect(status().isOk()) + .andExpect(content().string("Hello World")); + } + +} +// end::test-mock-mvc[] diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockWebTestClientExampleTests.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockWebTestClientExampleTests.java new file mode 100644 index 0000000000..ab59e02deb --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/test/web/MockWebTestClientExampleTests.java @@ -0,0 +1,45 @@ +/* + * Copyright 2012-2018 the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.boot.docs.test.web; + +// tag::test-mock-web-test-client[] + +import org.junit.Test; +import org.junit.runner.RunWith; + +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.autoconfigure.web.reactive.AutoConfigureWebTestClient; +import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.junit4.SpringRunner; +import org.springframework.test.web.reactive.server.WebTestClient; + +@RunWith(SpringRunner.class) +@SpringBootTest +@AutoConfigureWebTestClient +public class MockWebTestClientExampleTests { + + @Autowired + private WebTestClient webClient; + + @Test + public void exampleTest() { + this.webClient.get().uri("/").exchange().expectStatus().isOk() + .expectBody(String.class).isEqualTo("Hello World"); + } + +} +// end::test-mock-web-test-client[]