Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document how to switch to the default set of TestExecutionListeners

Browse Source 
Closes gh-29281
This commit is contained in:
Sam Brannen
2022-10-07 17:58:22 +02:00
parent 5eee4673c1
commit a599601dd9
3 changed files with 82 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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.
*
* <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>

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

@@ -30,16 +30,30 @@ import org.springframework.core.annotation.AliasFor;
* 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