Document how to switch to the default set of TestExecutionListeners

Closes gh-29281

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2021 the original author or authors.
+ * Copyright 2002-2022 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.
@@ -41,8 +41,24 @@
  * {@link org.springframework.core.annotation.Order @Order} annotation. See
  * {@link TestContextBootstrapper#getTestExecutionListeners()} for details.
  *
- * <p>Spring provides the following out-of-the-box implementations (all of
- * which implement {@code Ordered}):
+ * <h3>Registering TestExecutionListener Implementations</h3>
+ *
+ * <p>A {@code TestExecutionListener} can be registered explicitly for a test class,
+ * its subclasses, and its nested classes by using the
+ * {@link TestExecutionListeners @TestExecutionListeners} annotation. Explicit
+ * registration is suitable for custom listeners that are used in limited testing
+ * scenarios. However, it can become cumbersome if a custom listener needs to be
+ * used across an entire test suite. This issue is addressed through support for
+ * automatic discovery of <em>default</em> {@code TestExecutionListener}
+ * implementations through the
+ * {@link org.springframework.core.io.support.SpringFactoriesLoader SpringFactoriesLoader}
+ * mechanism. Specifically, default {@code TestExecutionListener} implementations
+ * can be registered under the {@code org.springframework.test.context.TestExecutionListener}
+ * key in a {@code META-INF/spring.factories} properties file.
+ *
+ * <p>Spring provides the following implementations. Each of these implements
+ * {@code Ordered} and is registered automatically by default.
+ *
  * <ul>
  * <li>{@link org.springframework.test.context.web.ServletTestExecutionListener
  * ServletTestExecutionListener}</li>

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

@@ -30,16 +30,30 @@
  * which {@link TestExecutionListener TestExecutionListeners} should be
  * registered with a {@link TestContextManager}.
  *
- * <p>Typically, {@code @TestExecutionListeners} will be used in conjunction
- * with {@link ContextConfiguration @ContextConfiguration}.
+ * <p>{@code @TestExecutionListeners} is used to register listeners for a
+ * particular test class, its subclasses, and its nested classes. If you wish to
+ * register a listener globally, you should register it via the automatic discovery
+ * mechanism described in {@link TestExecutionListener}.
  *
  * <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, this annotation will be inherited from an
- * enclosing test class by default. See
+ * <em>composed annotations</em>. As of Spring Framework 5.3, this annotation will
+ * be inherited from an enclosing test class by default. See
  * {@link NestedTestConfiguration @NestedTestConfiguration} for details.
  *
+ * <h3>Switching to default {@code TestExecutionListener} implementations</h3>
+ *
+ * <p>If you extend a class that is annotated with {@code @TestExecutionListeners}
+ * and you need to switch to using the <em>default</em> set of listeners, you
+ * can annotate your class with the following.
+ *
+ * <pre class="code">
+ * // Switch to default listeners
+ * &#064;TestExecutionListeners(listeners = {}, inheritListeners = false, mergeMode = MERGE_WITH_DEFAULTS)
+ * class MyTests extends BaseTests {
+ *     // ...
+ * }
+ * </pre>
+ *
  * @author Sam Brannen
  * @since 2.5
  * @see TestExecutionListener

src/docs/asciidoc/testing.adoc

@@ -1098,10 +1098,10 @@ javadoc.
 [[spring-testing-annotation-testexecutionlisteners]]
 ===== `@TestExecutionListeners`
 
-`@TestExecutionListeners` defines class-level metadata for configuring the
-`TestExecutionListener` implementations that should be registered with the
-`TestContextManager`. Typically, `@TestExecutionListeners` is used in conjunction with
-`@ContextConfiguration`.
+`@TestExecutionListeners` is used to register listeners for a particular test class, its
+subclasses, and its nested classes. If you wish to register a listener globally, you
+should register it via the automatic discovery mechanism described in
+<<testcontext-tel-config>>.
 
 The following example shows how to register two `TestExecutionListener` implementations:
 
@@ -1132,7 +1132,9 @@ By default, `@TestExecutionListeners` provides support for inheriting listeners
 superclasses or enclosing classes. See
 <<testcontext-junit-jupiter-nested-test-configuration>> and the 
 {api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`
-javadoc] for an example and further details.
+javadoc] for an example and further details. If you discover that you need to switch
+back to using the default `TestExecutionListener` implementations, see the note
+in <<testcontext-tel-config-registering-tels>>.
 
 [[spring-testing-annotation-recordapplicationevents]]
 ===== `@RecordApplicationEvents`
@@ -2460,12 +2462,46 @@ by default, exactly in the following order:
 [[testcontext-tel-config-registering-tels]]
 ===== Registering `TestExecutionListener` Implementations
 
-You can register `TestExecutionListener` implementations for a test class and its
-subclasses by using the `@TestExecutionListeners` annotation. See
+You can register `TestExecutionListener` implementations explicitly for a test class, its
+subclasses, and its nested classes by using the `@TestExecutionListeners` annotation. See
 <<integration-testing-annotations, annotation support>> and the javadoc for
 {api-spring-framework}/test/context/TestExecutionListeners.html[`@TestExecutionListeners`]
 for details and examples.
 
+.Switching to default `TestExecutionListener` implementations
+[NOTE]
+====
+If you extend a class that is annotated with `@TestExecutionListeners` and you need to
+switch to using the default set of listeners, you can annotate your class with the
+following.
+
+[source,java,indent=0,subs="verbatim,quotes",role="primary"]
+.Java
+----
+	// Switch to default listeners
+	@TestExecutionListeners(
+		listeners = {},
+		inheritListeners = false,
+		mergeMode = MERGE_WITH_DEFAULTS)
+	class MyTest extends BaseTest {
+		// class body...
+	}
+----
+
+[source,kotlin,indent=0,subs="verbatim,quotes",role="secondary"]
+.Kotlin
+----
+	// Switch to default listeners
+	@TestExecutionListeners(
+		listeners = [],
+		inheritListeners = false,
+		mergeMode = MERGE_WITH_DEFAULTS)
+	class MyTest : BaseTest {
+		// class body...
+	}
+----
+====
+
 [[testcontext-tel-config-automatic-discovery]]
 ===== Automatic Discovery of Default `TestExecutionListener` Implementations