Polish support for publishing TestContext lifecycle events

See gh-18490

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

@@ -44,6 +44,8 @@
  * <p>Spring provides the following out-of-the-box implementations (all of
  * which implement {@code Ordered}):
  * <ul>
+ * <li>{@link org.springframework.test.context.event.EventPublishingTestExecutionListener
+ * EventPublishingTestExecutionListener} (not registered by default)</li>
  * <li>{@link org.springframework.test.context.web.ServletTestExecutionListener
  * ServletTestExecutionListener}</li>
  * <li>{@link org.springframework.test.context.support.DirtiesContextBeforeModesTestExecutionListener
@@ -56,13 +58,12 @@
  * TransactionalTestExecutionListener}</li>
  * <li>{@link org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener
  * SqlScriptsTestExecutionListener}</li>
- * <li>{@link org.springframework.test.context.event.EventPublishingTestExecutionListener
- * EventPublishingTestExecutionListener} (not registered by default)</li>
  * </ul>
  *
  * @author Sam Brannen
  * @author Juergen Hoeller
  * @since 2.5
+ * @see TestExecutionListeners @TestExecutionListeners
  * @see TestContextManager
  * @see org.springframework.test.context.support.AbstractTestExecutionListener
  */

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

@@ -61,12 +61,13 @@
 	 * the {@link TestContextManager}.
 	 * <p>This attribute may <strong>not</strong> be used in conjunction with
 	 * {@link #value}, but it may be used instead of {@link #value}.
+	 * @see org.springframework.test.context.event.EventPublishingTestExecutionListener
 	 * @see org.springframework.test.context.web.ServletTestExecutionListener
+	 * @see org.springframework.test.context.support.DirtiesContextBeforeModesTestExecutionListener
 	 * @see org.springframework.test.context.support.DependencyInjectionTestExecutionListener
 	 * @see org.springframework.test.context.support.DirtiesContextTestExecutionListener
 	 * @see org.springframework.test.context.transaction.TransactionalTestExecutionListener
 	 * @see org.springframework.test.context.jdbc.SqlScriptsTestExecutionListener
-	 * @see org.springframework.test.context.event.EventPublishingTestExecutionListener
 	 */
 	@AliasFor("value")
 	Class<? extends TestExecutionListener>[] listeners() default {};

spring-test/src/main/java/org/springframework/test/context/event/AfterTestClassEvent.java

@@ -19,17 +19,19 @@
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#afterTestClass(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestClass(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.AfterTestClass
+ * @see org.springframework.test.context.event.annotation.AfterTestClass @AfterTestClass
  */
 @SuppressWarnings("serial")
 public class AfterTestClassEvent extends TestContextEvent {
 
-    public AfterTestClassEvent(TestContext source) {
-        super(source);
-    }
+	public AfterTestClassEvent(TestContext source) {
+		super(source);
+	}
+
 }

spring-test/src/main/java/org/springframework/test/context/event/AfterTestExecutionEvent.java

@@ -19,18 +19,19 @@
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#afterTestExecution(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestExecution(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.AfterTestExecution
+ * @see org.springframework.test.context.event.annotation.AfterTestExecution @AfterTestExecution
  */
 @SuppressWarnings("serial")
 public class AfterTestExecutionEvent extends TestContextEvent {
 
-    public AfterTestExecutionEvent(TestContext source) {
-        super(source);
-    }
+	public AfterTestExecutionEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/AfterTestMethodEvent.java

@@ -19,18 +19,19 @@
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#afterTestMethod(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#afterTestMethod(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.AfterTestMethod
+ * @see org.springframework.test.context.event.annotation.AfterTestMethod @AfterTestMethod
  */
 @SuppressWarnings("serial")
 public class AfterTestMethodEvent extends TestContextEvent {
 
-    public AfterTestMethodEvent(TestContext source) {
-        super(source);
-    }
+	public AfterTestMethodEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/BeforeTestClassEvent.java

@@ -19,18 +19,19 @@
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#beforeTestClass(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestClass(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestClass
+ * @see org.springframework.test.context.event.annotation.BeforeTestClass @BeforeTestClass
  */
 @SuppressWarnings("serial")
 public class BeforeTestClassEvent extends TestContextEvent {
 
-    public BeforeTestClassEvent(TestContext source) {
-        super(source);
-    }
+	public BeforeTestClassEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/BeforeTestExecutionEvent.java

@@ -19,18 +19,19 @@
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#beforeTestExecution(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestExecution(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestExecution
+ * @see org.springframework.test.context.event.annotation.BeforeTestExecution @BeforeTestExecution
  */
 @SuppressWarnings("serial")
 public class BeforeTestExecutionEvent extends TestContextEvent {
 
-    public BeforeTestExecutionEvent(TestContext source) {
-        super(source);
-    }
+	public BeforeTestExecutionEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/BeforeTestMethodEvent.java

@@ -19,18 +19,19 @@
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#beforeTestMethod(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#beforeTestMethod(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestMethod
+ * @see org.springframework.test.context.event.annotation.BeforeTestMethod @BeforeTestMethod
  */
 @SuppressWarnings("serial")
 public class BeforeTestMethodEvent extends TestContextEvent {
 
-    public BeforeTestMethodEvent(TestContext source) {
-        super(source);
-    }
+	public BeforeTestMethodEvent(TestContext source) {
+		super(source);
+	}
 
 }

spring-test/src/main/java/org/springframework/test/context/event/EventPublishingTestExecutionListener.java

@@ -16,72 +16,119 @@
 
 package org.springframework.test.context.event;
 
+import org.springframework.core.Ordered;
 import org.springframework.test.context.TestContext;
 import org.springframework.test.context.support.AbstractTestExecutionListener;
 
 /**
- * {@link org.springframework.test.context.TestExecutionListener} that may be used to publish test life-cycle event to
- * the Spring test {@link org.springframework.context.ApplicationContext}.
+ * {@link org.springframework.test.context.TestExecutionListener TestExecutionListener}
+ * that publishes test lifecycle events to a Spring test
+ * {@link org.springframework.context.ApplicationContext ApplicationContext}.
  *
- * <p>These events may be consumed for various reasons, such as resetting {@em mock} beans or tracing test
- * execution. Since these events may consumed as part of regular Spring beans, they can be shared among
- * different test classes.
+ * <p>These events may be consumed for various reasons, such as resetting <em>mock</em>
+ * beans or tracing test execution. Since these events may be consumed by regular
+ * Spring beans, they can be shared among different test classes.
+ * 
+ * <h3>Supported Events</h3>
+ * <ul>
+ * <li>{@link BeforeTestClassEvent}</li>
+ * <li>{@link PrepareTestInstanceEvent}</li>
+ * <li>{@link BeforeTestMethodEvent}</li>
+ * <li>{@link BeforeTestExecutionEvent}</li>
+ * <li>{@link AfterTestExecutionEvent}</li>
+ * <li>{@link AfterTestMethodEvent}</li>
+ * <li>{@link AfterTestClassEvent}</li>
+ * </ul>
  *
- * <p>This {@link org.springframework.test.context.TestExecutionListener} is not active by default. Test classes
- * should be annotated using {@link org.springframework.test.context.TestExecutionListeners}, if they want to use it.
- * Alternatively, it may be added to {@code spring.factories}, if needed.
+ * <p>Note that this {@code TestExecutionListener} is not registered by default,
+ * but it may be registered for a given test class via
+ * {@link org.springframework.test.context.TestExecutionListeners @TestExecutionListeners}
+ * or globally via the {@link org.springframework.core.io.support.SpringFactoriesLoader
+ * SpringFactoriesLoader} mechanism (consult the Javadoc and Spring reference manual for
+ * details).
  *
  * @author Frank Scheffler
+ * @author Sam Brannen
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.BeforeTestClass
- * @see org.springframework.test.context.event.annotation.PrepareTestInstance
- * @see org.springframework.test.context.event.annotation.BeforeTestMethod
- * @see org.springframework.test.context.event.annotation.BeforeTestExecution
- * @see org.springframework.test.context.event.annotation.AfterTestExecution
- * @see org.springframework.test.context.event.annotation.AfterTestMethod
- * @see org.springframework.test.context.event.annotation.AfterTestClass
+ * @see org.springframework.test.context.event.annotation.BeforeTestClass @BeforeTestClass
+ * @see org.springframework.test.context.event.annotation.PrepareTestInstance @PrepareTestInstance
+ * @see org.springframework.test.context.event.annotation.BeforeTestMethod @BeforeTestMethod
+ * @see org.springframework.test.context.event.annotation.BeforeTestExecution @BeforeTestExecution
+ * @see org.springframework.test.context.event.annotation.AfterTestExecution @AfterTestExecution
+ * @see org.springframework.test.context.event.annotation.AfterTestMethod @AfterTestMethod
+ * @see org.springframework.test.context.event.annotation.AfterTestClass @AfterTestClass
  */
 public class EventPublishingTestExecutionListener extends AbstractTestExecutionListener {
 
-    @Override
-    public void beforeTestClass(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new BeforeTestClassEvent(testContext));
-    }
+	/**
+	 * Returns {@link Ordered#HIGHEST_PRECEDENCE}.
+	 */
+	@Override
+	public int getOrder() {
+		return Ordered.HIGHEST_PRECEDENCE;
+	}
 
-    @Override
-    public void prepareTestInstance(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new PrepareTestInstanceEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link BeforeTestClassEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void beforeTestClass(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new BeforeTestClassEvent(testContext));
+	}
 
-    @Override
-    public void beforeTestMethod(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new BeforeTestMethodEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link PrepareTestInstanceEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void prepareTestInstance(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new PrepareTestInstanceEvent(testContext));
+	}
 
-    @Override
-    public void beforeTestExecution(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new BeforeTestExecutionEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link BeforeTestMethodEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void beforeTestMethod(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new BeforeTestMethodEvent(testContext));
+	}
 
-    @Override
-    public void afterTestExecution(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new AfterTestExecutionEvent(testContext));
-    }
+	/**
+	 * Publishes a {@link BeforeTestExecutionEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void beforeTestExecution(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new BeforeTestExecutionEvent(testContext));
+	}
 
-    @Override
-    public void afterTestMethod(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new AfterTestMethodEvent(testContext));
-    }
+	/**
+	 * Publishes an {@link AfterTestExecutionEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void afterTestExecution(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new AfterTestExecutionEvent(testContext));
+	}
+
+	/**
+	 * Publishes an {@link AfterTestMethodEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void afterTestMethod(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new AfterTestMethodEvent(testContext));
+	}
+
+	/**
+	 * Publishes an {@link AfterTestClassEvent} to the {@code ApplicationContext}
+	 * for the supplied {@link TestContext}.
+	 */
+	@Override
+	public void afterTestClass(TestContext testContext) {
+		testContext.getApplicationContext().publishEvent(new AfterTestClassEvent(testContext));
+	}
 
-    @Override
-    public void afterTestClass(TestContext testContext) {
-        testContext.getApplicationContext().publishEvent(
-                new AfterTestClassEvent(testContext));
-    }
 }

spring-test/src/main/java/org/springframework/test/context/event/PrepareTestInstanceEvent.java

@@ -19,18 +19,19 @@
 import org.springframework.test.context.TestContext;
 
 /**
- * {@link TestContextEvent} published by {@link EventPublishingTestExecutionListener} when
- * {@link org.springframework.test.context.TestExecutionListener#prepareTestInstance(TestContext)} is called.
+ * {@link TestContextEvent} published by the {@link EventPublishingTestExecutionListener} when
+ * {@link org.springframework.test.context.TestExecutionListener#prepareTestInstance(TestContext)}
+ * is invoked.
  *
  * @author Frank Scheffler
  * @since 5.2
- * @see org.springframework.test.context.event.annotation.PrepareTestInstance
+ * @see org.springframework.test.context.event.annotation.PrepareTestInstance @PrepareTestInstance
  */
 @SuppressWarnings("serial")
 public class PrepareTestInstanceEvent extends TestContextEvent {
 
-    public PrepareTestInstanceEvent(TestContext source) {
-        super(source);
-    }
+	public PrepareTestInstanceEvent(TestContext source) {
+		super(source);
+	}
 
 }