Document @⁠SpringExtensionConfig in the reference manual

This commit also updates the Javadoc for the SpringExtension and
@⁠SpringExtensionConfig to point out that the SpringExtension always
uses a test-class scoped ExtensionContext if
@⁠TestInstance(Lifecycle.PER_CLASS) semantics are in effect.

Closes gh-36240

framework-docs/modules/ROOT/pages/testing/annotations/integration-junit-jupiter.adoc

@@ -5,6 +5,7 @@ The following annotations are supported when used in conjunction with the
 xref:testing/testcontext-framework/support-classes.adoc#testcontext-junit-jupiter-extension[`SpringExtension`]
 and JUnit Jupiter (that is, the programming model in JUnit):
 
+* xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-springextensionconfig[`@SpringExtensionConfig`]
 * xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-springjunitconfig[`@SpringJUnitConfig`]
 * xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-junit-jupiter-springjunitwebconfig[`@SpringJUnitWebConfig`]
 * xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-testconstructor[`@TestConstructor`]
@@ -14,6 +15,47 @@ and JUnit Jupiter (that is, the programming model in JUnit):
 * xref:testing/annotations/integration-spring/annotation-disabledinaotmode.adoc[`@DisabledInAotMode`]
 
 
+[[integration-testing-annotations-springextensionconfig]]
+== `@SpringExtensionConfig`
+
+`@SpringExtensionConfig` is a type-level annotation that can be used to configure the
+behavior of the `SpringExtension`.
+
+As of Spring Framework 7.0, the `SpringExtension` is configured to use a test-method
+scoped `ExtensionContext`, which enables consistent dependency injection into fields and
+constructors from the `ApplicationContext` for the current test method in a `@Nested`
+test class hierarchy. However, if a third-party `TestExecutionListener` is not compatible
+with the semantics associated with a test-method scoped extension context — or if a
+developer wishes to switch to test-class scoped semantics — the `SpringExtension` can be
+configured to use a test-class scoped `ExtensionContext` by annotating a top-level test
+class with `@SpringExtensionConfig(useTestClassScopedExtensionContext = true)`.
+
+[TIP]
+====
+If your top-level test class is configured to use JUnit Jupiter's
+`@TestInstance(Lifecycle.PER_CLASS)` semantics, the `SpringExtension` will always use a
+test-class scoped `ExtensionContext`, and there is no need to declare
+`@SpringExtensionConfig(useTestClassScopedExtensionContext = true)`.
+====
+
+[NOTE]
+====
+This annotation is currently only applicable to `@Nested` test class hierarchies and
+should be applied to the top-level enclosing class of a `@Nested` test class hierarchy.
+
+Consequently, there is no need to declare this annotation on a test class that does not
+contain `@Nested` test classes.
+====
+
+[NOTE]
+====
+xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-nestedtestconfiguration[`@NestedTestConfiguration`]
+does not apply to this annotation.
+
+`@SpringExtensionConfig` will always be detected within a `@Nested` test class hierarchy,
+effectively disregarding any `@NestedTestConfiguration(OVERRIDE)` declarations.
+====
+
 [[integration-testing-annotations-junit-jupiter-springjunitconfig]]
 == `@SpringJUnitConfig`
 

framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc

@@ -392,6 +392,17 @@ any of its subclasses and nested classes. Thus, you may annotate a top-level tes
 with `@NestedTestConfiguration`, and that will apply to all of its nested test classes
 recursively.
 
+[NOTE]
+====
+As of Spring Framework 7.0, the `SpringExtension` uses a test-method scoped
+`ExtensionContext` within `@Nested` test class hierarchies by default. However, the
+`SpringExtension` can be configured to use a test-class scoped `ExtensionContext`.
+
+See the documentation for
+xref:testing/annotations/integration-junit-jupiter.adoc#integration-testing-annotations-springextensionconfig[`@SpringExtensionConfig`]
+for details.
+====
+
 [TIP]
 ====
 If you are developing a component that integrates with the Spring TestContext Framework

spring-test/src/main/java/org/springframework/test/context/junit/jupiter/SpringExtension.java

@@ -88,7 +88,12 @@ import org.springframework.util.ReflectionUtils.MethodFilter;
  * be configured to use a test-class scoped extension context by annotating a
  * top-level test class with
  * {@link SpringExtensionConfig#useTestClassScopedExtensionContext()
- * @SpringExtensionConfig(useTestClassScopedExtensionContext = true)}.
+ * @SpringExtensionConfig(useTestClassScopedExtensionContext = true)}. Note,
+ * however, that the {@code SpringExtension} will always use a test-class scoped
+ * {@code ExtensionContext} if your top-level test class is configured to use JUnit
+ * Jupiter’s {@code @TestInstance(Lifecycle.PER_CLASS)} semantics, in which case
+ * there is no need to declare
+ * {@code @SpringExtensionConfig(useTestClassScopedExtensionContext = true)}.
  *
  * <p><strong>NOTE:</strong> This class requires JUnit Jupiter 6.0 or higher.
  *

spring-test/src/main/java/org/springframework/test/context/junit/jupiter/SpringExtensionConfig.java

@@ -60,6 +60,11 @@ public @interface SpringExtensionConfig {
 	 * {@code ExtensionContext}. Thus, there is no need to declare this annotation
 	 * attribute with a value of {@code false}.
 	 *
+	 * <p>Similarly, if your top-level test class is configured to use JUnit Jupiter’s
+	 * {@code @TestInstance(Lifecycle.PER_CLASS)} semantics, the {@code SpringExtension}
+	 * will always use a test-class scoped {@code ExtensionContext}, and there is no need
+	 * to declare {@code @SpringExtensionConfig(useTestClassScopedExtensionContext = true)}.
+	 *
 	 * @see SpringExtension
 	 * @see SpringExtension#getTestInstantiationExtensionContextScope(org.junit.jupiter.api.extension.ExtensionContext)
 	 */