Improve documentation for using a mock environment with @SpringBootTest

Closes gh-13827

Author: snicoll

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
+<<boot-features-testing-spring-boot-applications-detecting-config,creating the
+`ApplicationContext` used in your tests through `SpringApplication`>>. In addition to
+`@SpringBootTest` a number of other annotations are also provided for
 <<boot-features-testing-spring-boot-applications-testing-autoconfigured-tests,testing more
 specific slices>> 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
+<<boot-features-testing-spring-boot-applications-testing-with-mock-environment,
+`@AutoConfigureMockMvc` or `@AutoConfigureWebTestClient`>> 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
+<<boot-features-testing-spring-boot-applications-testing-autoconfigured-mvc-tests,using
+`@WebMvcTest` instead>>.
+
+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]]

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[]

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[]