From 6a9b5d21f4eb1126f327718dba5fb77bd98c9ca2 Mon Sep 17 00:00:00 2001
From: Sam Brannen <104798+sbrannen@users.noreply.github.com>
Date: Tue, 24 Sep 2024 11:55:34 +0200
Subject: [PATCH] =?UTF-8?q?Document=20that=20TestContextAnnotationUtils=20?=
 =?UTF-8?q?is=20required=20for=20@=E2=81=A0Nested=20support?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes gh-33586
---
 .../testcontext-framework/support-classes.adoc    |  8 ++++++++
 .../test/context/NestedTestConfiguration.java     | 15 +++++++++++----
 .../test/context/TestContextAnnotationUtils.java  |  6 ++++--
 3 files changed, 23 insertions(+), 6 deletions(-)

diff --git a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc
index e957865c93..1ee5856ecf 100644
--- a/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc
+++ b/framework-docs/modules/ROOT/pages/testing/testcontext-framework/support-classes.adoc
@@ -542,6 +542,14 @@ 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.
 
+[TIP]
+====
+If you are developing a component that integrates with the Spring TestContext Framework
+and needs to support annotation inheritance within enclosing class hierarchies, you must
+use the annotation search utilities provided in `TestContextAnnotationUtils` in order to
+honor `@NestedTestConfiguration` semantics.
+====
+
 In order to allow development teams to change the default to `OVERRIDE` – for example,
 for compatibility with Spring Framework 5.0 through 5.2 – the default mode can be changed
 globally via a JVM system property or a `spring.properties` file in the root of the
diff --git a/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java b/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java
index c090ddb351..8dc0e821b0 100644
--- a/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java
+++ b/spring-test/src/main/java/org/springframework/test/context/NestedTestConfiguration.java
@@ -58,10 +58,16 @@ import org.springframework.lang.Nullable;
  * <p>This annotation may be used as a <em>meta-annotation</em> to create custom
  * <em>composed annotations</em>.
  *
- * <p>As of Spring Framework 5.3, the use of this annotation typically only makes
- * sense in conjunction with {@link org.junit.jupiter.api.Nested @Nested} test
- * classes in JUnit Jupiter; however, there may be other testing frameworks with
- * support for nested test classes that could also make use of this annotation.
+ * <p>The use of this annotation typically only makes sense in conjunction with
+ * {@link org.junit.jupiter.api.Nested @Nested} test classes in JUnit Jupiter;
+ * however, there may be other testing frameworks with support for nested test
+ * classes that could also make use of this annotation.
+ *
+ * <p>If you are developing a component that integrates with the Spring TestContext
+ * Framework and needs to support annotation inheritance within enclosing class
+ * hierarchies, you must use the annotation search utilities provided in
+ * {@link TestContextAnnotationUtils} in order to honor
+ * {@code @NestedTestConfiguration} semantics.
  *
  * <h3>Supported Annotations</h3>
  * <p>The <em>Spring TestContext Framework</em> honors {@code @NestedTestConfiguration}
@@ -89,6 +95,7 @@ import org.springframework.lang.Nullable;
  * @since 5.3
  * @see EnclosingConfiguration#INHERIT
  * @see EnclosingConfiguration#OVERRIDE
+ * @see TestContextAnnotationUtils
  */
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java b/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java
index be01566361..6053c11572 100644
--- a/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java
+++ b/spring-test/src/main/java/org/springframework/test/context/TestContextAnnotationUtils.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2024 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.
@@ -47,7 +47,8 @@ import org.springframework.util.ObjectUtils;
  * and {@link AnnotatedElementUtils}, while transparently honoring
  * {@link NestedTestConfiguration @NestedTestConfiguration} semantics.
  *
- * <p>Mainly for internal use within the <em>Spring TestContext Framework</em>.
+ * <p>Mainly for internal use within the <em>Spring TestContext Framework</em>
+ * but also supported for third-party integrations with the TestContext framework.
  *
  * <p>Whereas {@code AnnotationUtils} and {@code AnnotatedElementUtils} provide
  * utilities for <em>getting</em> or <em>finding</em> annotations,
@@ -70,6 +71,7 @@ import org.springframework.util.ObjectUtils;
  * @see AnnotationUtils
  * @see AnnotatedElementUtils
  * @see AnnotationDescriptor
+ * @see NestedTestConfiguration
  */
 public abstract class TestContextAnnotationUtils {