diff --git a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListener.java b/spring-test/src/main/java/org/springframework/test/context/TestExecutionListener.java
index e10d2422bdc..fc4ea1187a5 100644
--- a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListener.java
+++ b/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 @@ package org.springframework.test.context;
* {@link org.springframework.core.annotation.Order @Order} annotation. See
* {@link TestContextBootstrapper#getTestExecutionListeners()} for details.
*
- * Spring provides the following out-of-the-box implementations (all of
- * which implement {@code Ordered}):
+ *
Registering TestExecutionListener Implementations
+ *
+ * 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 default {@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.
+ *
+ *
Spring provides the following implementations. Each of these implements
+ * {@code Ordered} and is registered automatically by default.
+ *
*
* - {@link org.springframework.test.context.web.ServletTestExecutionListener
* ServletTestExecutionListener}
diff --git a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java b/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java
index 0a0349a8661..c4c26de1b7a 100644
--- a/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java
+++ b/spring-test/src/main/java/org/springframework/test/context/TestExecutionListeners.java
@@ -30,16 +30,30 @@ import org.springframework.core.annotation.AliasFor;
* which {@link TestExecutionListener TestExecutionListeners} should be
* registered with a {@link TestContextManager}.
*
- * Typically, {@code @TestExecutionListeners} will be used in conjunction
- * with {@link ContextConfiguration @ContextConfiguration}.
+ *
{@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}.
*
*
This annotation may be used as a meta-annotation to create custom
- * composed annotations.
- *
- *
As of Spring Framework 5.3, this annotation will be inherited from an
- * enclosing test class by default. See
+ * composed annotations. As of Spring Framework 5.3, this annotation will
+ * be inherited from an enclosing test class by default. See
* {@link NestedTestConfiguration @NestedTestConfiguration} for details.
*
+ *
Switching to default {@code TestExecutionListener} implementations
+ *
+ * If you extend a class that is annotated with {@code @TestExecutionListeners}
+ * and you need to switch to using the default set of listeners, you
+ * can annotate your class with the following.
+ *
+ *
+ * // Switch to default listeners
+ * @TestExecutionListeners(listeners = {}, inheritListeners = false, mergeMode = MERGE_WITH_DEFAULTS)
+ * class MyTests extends BaseTests {
+ * // ...
+ * }
+ *
+ *
* @author Sam Brannen
* @since 2.5
* @see TestExecutionListener
diff --git a/src/docs/asciidoc/testing.adoc b/src/docs/asciidoc/testing.adoc
index 214b9fff286..b64de9d8b08 100644
--- a/src/docs/asciidoc/testing.adoc
+++ b/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
+<>.
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
<> 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 <>.
[[spring-testing-annotation-recordapplicationevents]]
===== `@RecordApplicationEvents`
@@ -2459,12 +2461,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
<> 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