Document @DynamicPropertySource use cases that require @DirtiesContext

Closes gh-25850

spring-test/src/main/java/org/springframework/test/context/DynamicPropertySource.java

@@ -39,7 +39,14 @@
  * {@code PropertySources}. Values are dynamic and provided via a
  * {@link java.util.function.Supplier} which is only invoked when the property
  * is resolved. Typically, method references are used to supply values, as in the
- * following example.
+ * example below.
+ *
+ * <p><strong>NOTE</strong>: if you use {@code @DynamicPropertySource} in a base
+ * class and discover that tests in subclasses fail because the dynamic properties
+ * change between subclasses, you may need to annotate your base class with
+ * {@link org.springframework.test.annotation.DirtiesContext @DirtiesContext} to
+ * ensure that each subclass gets its own {@code ApplicationContext} with the
+ * correct dynamic properties.
  *
  * <h3>Precedence</h3>
  * <p>Dynamic properties have higher precedence than those loaded from
@@ -77,6 +84,7 @@
  * @see ContextConfiguration
  * @see TestPropertySource
  * @see org.springframework.core.env.PropertySource
+ * @see org.springframework.test.annotation.DirtiesContext
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)

src/docs/asciidoc/testing.adoc

@@ -4093,11 +4093,14 @@ integration tests that need to add properties with dynamic values to the set of
 `PropertySources` in the `Environment` for the `ApplicationContext` loaded for the
 integration test.
 
-NOTE: The `@DynamicPropertySource` annotation and its supporting infrastructure were
+[NOTE]
+====
+The `@DynamicPropertySource` annotation and its supporting infrastructure were
 originally designed to allow properties from
 https://www.testcontainers.org/[Testcontainers] based tests to be exposed easily to
 Spring integration tests. However, this feature may also be used with any form of
 external resource whose lifecycle is maintained outside the test's `ApplicationContext`.
+====
 
 In contrast to the <<testcontext-ctx-management-property-sources,`@TestPropertySource`>>
 annotation that is applied at the class level, `@DynamicPropertySource` must be applied
@@ -4112,6 +4115,15 @@ available to components within the test's `ApplicationContext` via the `redis.ho
 abstraction or injected directly into Spring-managed components – for example, via
 `@Value("${redis.host}")` and `@Value("${redis.port}")`, respectively.
 
+[TIP]
+====
+If you use `@DynamicPropertySource` in a base class and discover that tests in subclasses
+fail because the dynamic properties change between subclasses, you may need to annotate
+your base class with <<spring-testing-annotation-dirtiescontext, `@DirtiesContext`>> to
+ensure that each subclass gets its own `ApplicationContext` with the correct dynamic
+properties.
+====
+
 [source,java,indent=0,subs="verbatim,quotes",role="primary"]
 .Java
 ----
@@ -4458,10 +4470,10 @@ the underlying context cache, you can set the log level for the
 In the unlikely case that a test corrupts the application context and requires reloading
 (for example, by modifying a bean definition or the state of an application object), you
 can annotate your test class or test method with `@DirtiesContext` (see the discussion of
-`@DirtiesContext` in <<spring-testing-annotation-dirtiescontext>>). This instructs Spring
-to remove the context from the cache and rebuild the application context before running
-the next test that requires the same application context. Note that support for the
-`@DirtiesContext` annotation is provided by the
+`@DirtiesContext` in <<spring-testing-annotation-dirtiescontext, Spring Testing
+Annotations>>). This instructs Spring to remove the context from the cache and rebuild
+the application context before running the next test that requires the same application
+context. Note that support for the `@DirtiesContext` annotation is provided by the
 `DirtiesContextBeforeModesTestExecutionListener` and the
 `DirtiesContextTestExecutionListener`, which are enabled by default.