Merge branch '6.2.x'

Author: sbrannen

framework-docs/modules/ROOT/pages/testing/testcontext-framework/tel-config.adoc

@@ -7,16 +7,17 @@ by default, exactly in the following order:
 * `ServletTestExecutionListener`: Configures Servlet API mocks for a
   `WebApplicationContext`.
 * `DirtiesContextBeforeModesTestExecutionListener`: Handles the `@DirtiesContext`
-  annotation for "`before`" modes.
+  annotation for "before" modes.
 * `ApplicationEventsTestExecutionListener`: Provides support for
   xref:testing/testcontext-framework/application-events.adoc[`ApplicationEvents`].
-* `BeanOverrideTestExecutionListener`: Provides support for xref:testing/testcontext-framework/bean-overriding.adoc[] .
+* `BeanOverrideTestExecutionListener`: Provides support for
+  xref:testing/testcontext-framework/bean-overriding.adoc[].
 * `DependencyInjectionTestExecutionListener`: Provides dependency injection for the test
   instance.
 * `MicrometerObservationRegistryTestExecutionListener`: Provides support for
   Micrometer's `ObservationRegistry`.
 * `DirtiesContextTestExecutionListener`: Handles the `@DirtiesContext` annotation for
-  "`after`" modes.
+  "after" modes.
 * `CommonCachesTestExecutionListener`: Clears resource caches in the test's
   `ApplicationContext` if necessary.
 * `TransactionalTestExecutionListener`: Provides transactional test execution with
@@ -161,15 +162,16 @@ change from release to release -- for example, `SqlScriptsTestExecutionListener`
 introduced in Spring Framework 4.1, and `DirtiesContextBeforeModesTestExecutionListener`
 was introduced in Spring Framework 4.2. Furthermore, third-party frameworks like Spring
 Boot and Spring Security register their own default `TestExecutionListener`
-implementations by using the aforementioned xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-automatic-discovery[automatic discovery mechanism]
-.
+implementations by using the aforementioned
+xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-automatic-discovery[automatic discovery mechanism].
 
 To avoid having to be aware of and re-declare all default listeners, you can set the
 `mergeMode` attribute of `@TestExecutionListeners` to `MergeMode.MERGE_WITH_DEFAULTS`.
 `MERGE_WITH_DEFAULTS` indicates that locally declared listeners should be merged with the
 default listeners. The merging algorithm ensures that duplicates are removed from the
 list and that the resulting set of merged listeners is sorted according to the semantics
-of `AnnotationAwareOrderComparator`, as described in xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-ordering[Ordering `TestExecutionListener` Implementations].
+of `AnnotationAwareOrderComparator`, as described in
+xref:testing/testcontext-framework/tel-config.adoc#testcontext-tel-config-ordering[Ordering `TestExecutionListener` Implementations].
 If a listener implements `Ordered` or is annotated with `@Order`, it can influence the
 position in which it is merged with the defaults. Otherwise, locally declared listeners
 are appended to the list of default listeners when merged.

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2023 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -22,8 +22,9 @@
  * the listener is registered.
  *
  * <p>Note that not all testing frameworks support all lifecycle callbacks defined
- * in this API. For example, {@link #beforeTestExecution} and
- * {@link #afterTestExecution} are not supported in conjunction with JUnit 4 when
+ * in this API. For example, the {@link #beforeTestExecution(TestContext)
+ * beforeTestExecution} and {@link #afterTestExecution(TestContext)
+ * afterTestExecution} callbacks are not supported in conjunction with JUnit 4 when
  * using the {@link org.springframework.test.context.junit4.rules.SpringMethodRule
  * SpringMethodRule}.
  *
@@ -41,6 +42,35 @@
  * {@link org.springframework.core.annotation.Order @Order} annotation. See
  * {@link TestContextBootstrapper#getTestExecutionListeners()} for details.
  *
+ * <h3>Wrapping Behavior for Listeners</h3>
+ *
+ * <p>The {@link TestContextManager} guarantees <em>wrapping</em> behavior for
+ * multiple registered listeners that implement lifecycle callbacks such as
+ * {@link #beforeTestClass(TestContext) beforeTestClass},
+ * {@link #afterTestClass(TestContext) afterTestClass},
+ * {@link #beforeTestMethod(TestContext) beforeTestMethod},
+ * {@link #afterTestMethod(TestContext) afterTestMethod},
+ * {@link #beforeTestExecution(TestContext) beforeTestExecution}, and
+ * {@link #afterTestExecution(TestContext) afterTestExecution}. This means that,
+ * given two listeners {@code Listener1} and {@code Listener2} with {@code Listener1}
+ * registered before {@code Listener2}, any <em>before</em> callbacks implemented
+ * by {@code Listener1} are guaranteed to be invoked <strong>before</strong> any
+ * <em>before</em> callbacks implemented by {@code Listener2}. Similarly, given
+ * the same two listeners registered in the same order, any <em>after</em>
+ * callbacks implemented by {@code Listener1} are guaranteed to be invoked
+ * <strong>after</strong> any <em>after</em> callbacks implemented by
+ * {@code Listener2}. {@code Listener1} is therefore said to <em>wrap</em>
+ * {@code Listener2}.
+ *
+ * <p>For a concrete example, consider the relationship between the
+ * {@link org.springframework.test.context.transaction.TransactionalTestExecutionListener
+ * TransactionalTestExecutionListener} and the
+ * {@link org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener
+ * SqlScriptsTestExecutionListener}. The {@code SqlScriptsTestExecutionListener}
+ * is registered after the {@code TransactionalTestExecutionListener}, so that
+ * SQL scripts are executed within a transaction managed by the
+ * {@code TransactionalTestExecutionListener}.
+ *
  * <h3>Registering TestExecutionListener Implementations</h3>
  *
  * <p>A {@code TestExecutionListener} can be registered explicitly for a test class,
@@ -100,6 +130,8 @@ public interface TestExecutionListener {
 	 * the class.
 	 * <p>This method should be called immediately before framework-specific
 	 * <em>before class</em> lifecycle callbacks.
+	 * <p>See the {@linkplain TestExecutionListener class-level documentation}
+	 * for details on wrapping behavior for lifecycle callbacks.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by
 	 * concrete classes as necessary.
 	 * @param testContext the test context for the test; never {@code null}
@@ -118,6 +150,8 @@ 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>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
 	 * concrete classes as necessary.
 	 * @param testContext the test context for the test; never {@code null}
@@ -137,6 +171,8 @@ default void prepareTestInstance(TestContext testContext) throws Exception {
 	 * this method might be something like {@code beforeTestSetUp} or
 	 * {@code beforeEach}; however, it is unfortunately impossible to rename
 	 * this method due to backward compatibility concerns.
+	 * <p>See the {@linkplain TestExecutionListener class-level documentation}
+	 * for details on wrapping behavior for lifecycle callbacks.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by
 	 * concrete classes as necessary.
 	 * @param testContext the test context in which the test method will be
@@ -156,6 +192,8 @@ default void beforeTestMethod(TestContext testContext) throws Exception {
 	 * or logging purposes.
 	 * <p>This method <strong>must</strong> be called after framework-specific
 	 * <em>before</em> lifecycle callbacks.
+	 * <p>See the {@linkplain TestExecutionListener class-level documentation}
+	 * for details on wrapping behavior for lifecycle callbacks.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by
 	 * concrete classes as necessary.
 	 * @param testContext the test context in which the test method will be
@@ -176,6 +214,8 @@ default void beforeTestExecution(TestContext testContext) throws Exception {
 	 * or logging purposes.
 	 * <p>This method <strong>must</strong> be called before framework-specific
 	 * <em>after</em> lifecycle callbacks.
+	 * <p>See the {@linkplain TestExecutionListener class-level documentation}
+	 * for details on wrapping behavior for lifecycle callbacks.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by
 	 * concrete classes as necessary.
 	 * @param testContext the test context in which the test method will be
@@ -200,6 +240,8 @@ default void afterTestExecution(TestContext testContext) throws Exception {
 	 * this method might be something like {@code afterTestTearDown} or
 	 * {@code afterEach}; however, it is unfortunately impossible to rename
 	 * this method due to backward compatibility concerns.
+	 * <p>See the {@linkplain TestExecutionListener class-level documentation}
+	 * for details on wrapping behavior for lifecycle callbacks.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by
 	 * concrete classes as necessary.
 	 * @param testContext the test context in which the test method was
@@ -217,6 +259,8 @@ default void afterTestMethod(TestContext testContext) throws Exception {
 	 * the class.
 	 * <p>This method should be called immediately after framework-specific
 	 * <em>after class</em> lifecycle callbacks.
+	 * <p>See the {@linkplain TestExecutionListener class-level documentation}
+	 * for details on wrapping behavior for lifecycle callbacks.
 	 * <p>The default implementation is <em>empty</em>. Can be overridden by
 	 * concrete classes as necessary.
 	 * @param testContext the test context for the test; never {@code null}