Clarify behavior of JMX in @SpringBootTest

Closes gh-13008

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

@@ -5363,7 +5363,13 @@ features of Spring Boot are only installed in the context by default if you use
 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 via `SpringApplication`.
+in your tests via `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 will run:
@@ -5388,12 +5394,6 @@ or `DEFINED_PORT` implicitly provides a real servlet environment, HTTP client an
 server will run in separate threads, thus separate transactions. Any transaction
 initiated on the server won't rollback in this case.
 
-NOTE: In addition to `@SpringBootTest` 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.
-
 
 
 [[boot-features-testing-spring-boot-applications-detecting-config]]
@@ -5482,6 +5482,19 @@ include::{code-examples}/test/web/RandomPortExampleTests.java[tag=test-random-po
 
 
 
+[[boot-features-testing-spring-boot-applications-jmx]]
+==== Using JMX
+As the test context framework caches context, JMX is disabled by default to prevent
+identical components to register on the same domain. If such test needs access to an
+`MBeanServer`, consider marking it dirty as well:
+
+[source,java,indent=0]
+----
+include::{test-examples}/jmx/SampleJmxTests.java[tag=test]
+----
+
+
+
 [[boot-features-testing-spring-boot-applications-mocking-beans]]
 ==== Mocking and spying beans
 It's sometimes necessary to mock certain components within your application context when

spring-boot-docs/src/test/java/org/springframework/boot/jmx/SampleApp.java

@@ -0,0 +1,32 @@
+/*
+ * 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.jmx;
+
+import org.springframework.boot.SpringBootConfiguration;
+import org.springframework.boot.autoconfigure.ImportAutoConfiguration;
+import org.springframework.boot.autoconfigure.jmx.JmxAutoConfiguration;
+
+/**
+ * A sample {@link SpringBootConfiguration} that only enables JMX auto-configuration.
+ *
+ * @author Stephane Nicoll
+ */
+@SpringBootConfiguration
+@ImportAutoConfiguration(JmxAutoConfiguration.class)
+public class SampleApp {
+
+}

spring-boot-docs/src/test/java/org/springframework/boot/jmx/SampleJmxTests.java

@@ -0,0 +1,50 @@
+/*
+ * 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.jmx;
+
+import javax.management.MBeanServer;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.annotation.DirtiesContext;
+import org.springframework.test.context.junit4.SpringRunner;
+
+/**
+ * Example integration test that uses JMX.
+ *
+ * @author Stephane Nicoll
+ */
+// tag::test[]
+@RunWith(SpringRunner.class)
+@SpringBootTest(properties = "spring.jmx.enabled=true")
+@DirtiesContext
+public class SampleJmxTests {
+
+	@Autowired
+	private MBeanServer mBeanServer;
+
+	@Test
+	public void exampleTest() {
+		// ...
+
+	}
+
+}
+// end::test[]