Document test-method scoped TestContext semantics

Although gh-35680 introduced support for JUnit Jupiter's TEST_METHOD
ExtensionContextScope in the SpringExtension and
BeanOverrideTestExecutionListener, those were internal changes that are
not directly visible by TestExecutionListener authors.

However, in order to be compatible with a test-method scoped
TestContext (which takes its values from the current Jupiter
ExtensionContext), existing third-party TestExecutionListener
implementations may need to be modified similar to how
BeanOverrideTestExecutionListener was modified in commit d24a31d.

To raise awareness of how to deal with such issues, this commit
documents test-method TestContext semantics for TestExecutionListener
authors.

Closes gh-35716

Author: sbrannen

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

@@ -98,6 +98,20 @@ default void publishEvent(Function<TestContext, ? extends ApplicationEvent> even
 
 	/**
 	 * Get the {@linkplain Class test class} for this test context.
+	 * <p>Since JUnit Jupiter 5.12, if the
+	 * {@link org.springframework.test.context.junit.jupiter.SpringExtension
+	 * SpringExtension} is used with a {@linkplain
+	 * org.junit.jupiter.api.extension.TestInstantiationAwareExtension.ExtensionContextScope#TEST_METHOD
+	 * test-method scoped} {@link org.junit.jupiter.api.extension.ExtensionContext
+	 * ExtensionContext}, the {@code Class} returned from this method may refer
+	 * to the test class for the current {@linkplain #getTestMethod() test method},
+	 * which may be a {@link org.junit.jupiter.api.Nested @Nested} test class
+	 * within the class for the {@linkplain #getTestInstance() test instance}.
+	 * Thus, if you need consistent access to the class for the current test
+	 * instance within an implementation of
+	 * {@link TestExecutionListener#prepareTestInstance(TestContext)}, you should
+	 * invoke {@code testContext.getTestInstance().getClass()} instead of
+	 * {@code testContext.getTestClass()}.
 	 * @return the test class (never {@code null})
 	 */
 	Class<?> getTestClass();

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

@@ -150,6 +150,19 @@ default void beforeTestClass(TestContext testContext) throws Exception {
 	 * {@link org.springframework.test.context.junit4.rules.SpringMethodRule
 	 * SpringMethodRule}). In any case, this method must be called prior to any
 	 * framework-specific lifecycle callbacks.
+	 * <p>Since JUnit Jupiter 5.12, if the
+	 * {@link org.springframework.test.context.junit.jupiter.SpringExtension
+	 * SpringExtension} is used with a {@linkplain
+	 * org.junit.jupiter.api.extension.TestInstantiationAwareExtension.ExtensionContextScope#TEST_METHOD
+	 * test-method scoped} {@link org.junit.jupiter.api.extension.ExtensionContext
+	 * ExtensionContext}, the {@link Class} returned from
+	 * {@link TestContext#getTestClass()} may refer to the test class for the
+	 * current {@linkplain TestContext#getTestMethod() test method}, which may be
+	 * a {@link org.junit.jupiter.api.Nested @Nested} test class within the class
+	 * for the {@linkplain TestContext#getTestInstance() test instance}. Thus, if
+	 * you need consistent access to the class for the current test instance, you
+	 * should invoke {@code testContext.getTestInstance().getClass()} instead of
+	 * {@code testContext.getTestClass()}.
 	 * <p>See the {@linkplain TestExecutionListener class-level documentation}
 	 * for details on wrapping behavior for listeners.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by