Package org.springframework.test.context

# Annotation Interface TestExecutionListeners

@Target(TYPE) @Retention(RUNTIME) @Documented @Inherited public @interface TestExecutionListeners
`@TestExecutionListeners` is an annotation that can be applied to a test class to configure which `TestExecutionListeners` should be registered with a `TestContextManager`.

`@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 `TestExecutionListener`.

This annotation may be used as a meta-annotation to create custom composed annotations. In addition, this annotation will be inherited from an enclosing test class by default. See `@NestedTestConfiguration` for details.

### Switching to default `TestExecutionListener` implementations

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.

     // Switch to default listeners
     @TestExecutionListeners(listeners = {}, inheritListeners = false, mergeMode = MERGE_WITH_DEFAULTS)
     class MyTests extends BaseTests {
         // ...
     }

Since:
  2.5
Author:
  Sam Brannen
See Also:
  - `TestExecutionListener`
  - `TestContextManager`
  - `ContextConfiguration`

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static enum`
`TestExecutionListeners.MergeMode`
Enumeration of modes that dictate whether explicitly declared listeners are merged with the default listeners when `@TestExecutionListeners` is declared on a class that does not inherit listeners from a superclass or enclosing class.

## Optional Element Summary

Optional Elements
Modifier and Type
Optional Element
Description
`boolean`
`inheritListeners`
Whether `TestExecutionListeners` from superclasses and enclosing classes should be inherited.
`Class<? extends TestExecutionListener>[]`
`listeners`
The `TestExecutionListeners` to register with the `TestContextManager`.
`TestExecutionListeners.MergeMode`
`mergeMode`
The merge mode to use when `@TestExecutionListeners` is declared on a class that does not inherit listeners from a superclass or enclosing class.
`Class<? extends TestExecutionListener>[]`
`value`
Alias for `listeners()`.

## Element Details

### value

@AliasFor("listeners") Class<? extends TestExecutionListener>[] value
Alias for `listeners()`.

This attribute may not be used in conjunction with `listeners()`, but it may be used instead of `listeners()`.

Default:
  {}

### listeners

@AliasFor("value") Class<? extends TestExecutionListener>[] listeners
The `TestExecutionListeners` to register with the `TestContextManager`.

This attribute may not be used in conjunction with `value()`, but it may be used instead of `value()`.

See Also:
  - `ServletTestExecutionListener`
  - `DirtiesContextBeforeModesTestExecutionListener`
  - `ApplicationEventsTestExecutionListener`
  - `BeanOverrideTestExecutionListener`
  - `DependencyInjectionTestExecutionListener`
  - `DirtiesContextTestExecutionListener`
  - `CommonCachesTestExecutionListener`
  - `TransactionalTestExecutionListener`
  - `SqlScriptsTestExecutionListener`
  - `EventPublishingTestExecutionListener`
  - `MockitoResetTestExecutionListener`

Default:
  {}

### inheritListeners

boolean inheritListeners
Whether `TestExecutionListeners` from superclasses and enclosing classes should be inherited.

The default value is `true`, which means that an annotated class will inherit the listeners defined by an annotated superclass or enclosing class. Specifically, the listeners for an annotated class will be appended to the list of listeners defined by an annotated superclass or enclosing class. Thus, subclasses and nested classes have the option of extending the list of listeners. In the following example, `AbstractBaseTest` will be configured with `DependencyInjectionTestExecutionListener` and `DirtiesContextTestExecutionListener`; whereas, `TransactionalTest` will be configured with `DependencyInjectionTestExecutionListener`, `DirtiesContextTestExecutionListener`, and `TransactionalTestExecutionListener`, in that order.

     @TestExecutionListeners({
         DependencyInjectionTestExecutionListener.class,
         DirtiesContextTestExecutionListener.class
     })
     public abstract class AbstractBaseTest {
             // ...
     }

     @TestExecutionListeners(TransactionalTestExecutionListener.class)
     public class TransactionalTest extends AbstractBaseTest {
             // ...
     }

If `inheritListeners` is set to `false`, the listeners for the annotated class will shadow and effectively replace any listeners defined by a superclass or enclosing class.

Default:
  true

### mergeMode

TestExecutionListeners.MergeMode mergeMode
The merge mode to use when `@TestExecutionListeners` is declared on a class that does not inherit listeners from a superclass or enclosing class.

Can be set to `MERGE_WITH_DEFAULTS` to have locally declared listeners merged with the default listeners.

The mode is ignored if listeners are inherited from a superclass or enclosing class.

Defaults to `REPLACE_DEFAULTS` for backwards compatibility.

Since:
  4.1
See Also:
  - `TestExecutionListeners.MergeMode`

Default:
  REPLACE_DEFAULTS