Documentation for @IntegrationTest

Fixes gh-499

spring-boot-docs/src/main/asciidoc/howto.adoc

@@ -355,7 +355,35 @@ 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 wehen it is published.
 
+A really useful thing to do in is to autowire the
+`EmbeddedWebApplicationContext` into a test case and use it to
+discover the port that the app is running on. In that way you can use
+a test profile that chooses a random port (`server.port=0`) and make
+your test suite independent of its environment. Example:
 
+[source,java,indent=0,subs="verbatim,quotes,attributes"]
+----
+	@RunWith(SpringJUnit4ClassRunner.class)
+	@SpringApplicationConfiguration(classes = SampleDataJpaApplication.class)
+    @WebApplication
+    @IntegrationTest
+    @ActiveProfiles("test")
+	public class CityRepositoryIntegrationTests {
+
+		@Autowired
+		EmbeddedWebApplicationContext server;
+
+        int port;
+
+        @Before
+        public void init() {
+            port = server.getEmbeddedServletContainer().getPort();
+        }
+
+		// ...
+
+	}
+----
 
 [[howto-configure-tomcat]]
 === Configure Tomcat

spring-boot-docs/src/main/asciidoc/spring-boot-features.adoc

@@ -1434,6 +1434,32 @@ TIP: The context loader guesses whether you want to test a web application or no
 `MockMVC`) by looking for the `@WebAppConfiguration` annotation.  (`MockMVC` and
 `@WebAppConfiguration` are part of `spring-test`).
 
+If you want a web application to start up and listen on its normal
+port, so you can test it with HTTP (e.g. using `RestTemplate`)
+annotate your test class (or one of its superclasses)
+`@IntegrationTest`. This can be very useful because it means you can
+test the full stack of your application, but also inject its
+components into the test class and use them to assert the internal
+state of the application after an HTTP interaction. Example:
+
+
+[source,java,indent=0,subs="verbatim,quotes,attributes"]
+----
+	@RunWith(SpringJUnit4ClassRunner.class)
+	@SpringApplicationConfiguration(classes = SampleDataJpaApplication.class)
+    @WebApplication
+    @IntegrationTest
+	public class CityRepositoryIntegrationTests {
+
+		@Autowired
+		CityRepository repository;
+
+        RestTemplate restTemplate = RestTemplates.get();
+
+		// ... interact with the running server
+
+	}
+----
 
 
 [[boot-features-test-utilities]]