Introduce before/after test execution callbacks in TestExecutionListener

Issue: SPR-4365

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

@@ -55,6 +55,7 @@ package org.springframework.test.context;
  * @author Sam Brannen
  * @author Juergen Hoeller
  * @since 2.5
+ * @see TestContextManager
  * @see org.springframework.test.context.support.AbstractTestExecutionListener
  */
 public interface TestExecutionListener {
@@ -70,6 +71,7 @@ public interface TestExecutionListener {
 	 * concrete classes as necessary.
 	 * @param testContext the test context for the test; never {@code null}
 	 * @throws Exception allows any exception to propagate
+	 * @since 3.0
 	 */
 	default void beforeTestClass(TestContext testContext) throws Exception {
 		/* no-op */
@@ -90,34 +92,90 @@ public interface TestExecutionListener {
 	}
 
 	/**
-	 * Pre-processes a test <em>before</em> execution of the
-	 * {@link java.lang.reflect.Method test method} in the supplied
-	 * {@link TestContext test context}, for example by setting up test
-	 * fixtures.
-	 * <p>This method should be called immediately prior to framework-specific
-	 * <em>before</em> lifecycle callbacks.
+	 * Pre-processes a test <em>before</em> execution of <em>before</em>
+	 * lifecycle callbacks of the underlying test framework &mdash; for example,
+	 * by setting up test fixtures.
+	 * <p>This method <strong>must</strong> be called immediately prior to
+	 * framework-specific <em>before</em> lifecycle callbacks. For historical
+	 * reasons, this method is named {@code beforeTestMethod}. Since the
+	 * introduction of {@link #beforeTestExecution}, a more suitable name for
+	 * 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>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
 	 * executed; never {@code null}
 	 * @throws Exception allows any exception to propagate
+	 * @see #afterTestMethod
+	 * @see #beforeTestExecution
+	 * @see #afterTestExecution
 	 */
 	default void beforeTestMethod(TestContext testContext) throws Exception {
 		/* no-op */
 	}
 
 	/**
-	 * Post-processes a test <em>after</em> execution of the
+	 * Pre-processes a test <em>immediately before</em> execution of the
 	 * {@link java.lang.reflect.Method test method} in the supplied
-	 * {@link TestContext test context}, for example by tearing down test
-	 * fixtures.
-	 * <p>This method should be called immediately after framework-specific
+	 * {@link TestContext test context} &mdash; for example, for timing
+	 * or logging purposes.
+	 * <p>This method <strong>must</strong> be called after framework-specific
+	 * <em>before</em> 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
+	 * executed; never {@code null}
+	 * @throws Exception allows any exception to propagate
+	 * @since 5.0
+	 * @see #beforeTestMethod
+	 * @see #afterTestMethod
+	 * @see #afterTestExecution
+	 */
+	default void beforeTestExecution(TestContext testContext) throws Exception {
+		/* no-op */
+	}
+
+	/**
+	 * Post-processes a test <em>immediately after</em> execution of the
+	 * {@link java.lang.reflect.Method test method} in the supplied
+	 * {@link TestContext test context} &mdash; for example, for timing
+	 * or logging purposes.
+	 * <p>This method <strong>must</strong> be called before framework-specific
 	 * <em>after</em> 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
+	 * executed; never {@code null}
+	 * @throws Exception allows any exception to propagate
+	 * @since 5.0
+	 * @see #beforeTestMethod
+	 * @see #afterTestMethod
+	 * @see #beforeTestExecution
+	 */
+	default void afterTestExecution(TestContext testContext) throws Exception {
+		/* no-op */
+	}
+
+	/**
+	 * Post-processes a test <em>after</em> execution of <em>after</em>
+	 * lifecycle callbacks of the underlying test framework &mdash; for example,
+	 * by tearing down test fixtures.
+	 * <p>This method <strong>must</strong> be called immediately after
+	 * framework-specific <em>after</em> lifecycle callbacks. For historical
+	 * reasons, this method is named {@code afterTestMethod}. Since the
+	 * introduction of {@link #afterTestExecution}, a more suitable name for
+	 * 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>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
 	 * executed; never {@code null}
 	 * @throws Exception allows any exception to propagate
+	 * @see #beforeTestMethod
+	 * @see #beforeTestExecution
+	 * @see #afterTestExecution
 	 */
 	default void afterTestMethod(TestContext testContext) throws Exception {
 		/* no-op */
@@ -134,6 +192,7 @@ public interface TestExecutionListener {
 	 * concrete classes as necessary.
 	 * @param testContext the test context for the test; never {@code null}
 	 * @throws Exception allows any exception to propagate
+	 * @since 3.0
 	 */
 	default void afterTestClass(TestContext testContext) throws Exception {
 		/* no-op */