Package org.springframework.test.context

# Class TestContextManager

java.lang.Object
org.springframework.test.context.TestContextManager

public class TestContextManager extends Object
`TestContextManager` is the main entry point into the Spring TestContext Framework.

Specifically, a `TestContextManager` is responsible for managing a single `TestContext` and signaling events to each registered `TestExecutionListener` at the following test execution points.

- `before test class execution`: prior to any before class callbacks of a particular testing framework — for example, JUnit Jupiter's `@BeforeAll`
- `test instance preparation`: immediately following instantiation of the test class
- `before test setup`: prior to any before method callbacks of a particular testing framework — for example, JUnit Jupiter's `@BeforeEach`
- `before test execution`: immediately before execution of the test method but after test setup
- `after test execution`: immediately after execution of the test method but before test tear down
- `after test tear down`: after any after method callbacks of a particular testing framework — for example, JUnit Jupiter's `@AfterEach`
- `after test class execution`: after any after class callbacks of a particular testing framework — for example, JUnit Jupiter's `@AfterAll`

Support for loading and accessing application contexts, dependency injection of test instances, transactional execution of test methods, etc. is provided by `ContextLoaders` and `TestExecutionListeners`, which are configured via `@ContextConfiguration` and `@TestExecutionListeners`, respectively.

Bootstrapping of the `TestContext`, the default `ContextLoader`, default `TestExecutionListeners`, and their collaborators is performed by a `TestContextBootstrapper`, which is configured via `@BootstrapWith`.

Since:
  2.5
Author:
  Sam Brannen, Juergen Hoeller
See Also:
  - `BootstrapWith`
  - `BootstrapContext`
  - `TestContextBootstrapper`
  - `TestContext`
  - `TestExecutionListener`
  - `TestExecutionListeners`
  - `ContextConfiguration`
  - `ContextHierarchy`

## Constructor Summary

Constructors
Constructor
Description
`TestContextManager(Class<?> testClass)`
Construct a new `TestContextManager` for the supplied test class.
`TestContextManager(TestContextBootstrapper testContextBootstrapper)`
Construct a new `TestContextManager` using the supplied `TestContextBootstrapper` and register the necessary `TestExecutionListeners`.

## Method Summary

Modifier and Type
Method
Description
`void`
`afterTestClass()`
Hook for post-processing a test class after execution of all tests within the class.
`void`
`afterTestExecution(Object testInstance, Method testMethod, Throwable exception)`
Hook for post-processing a test immediately after execution of the test method in the supplied test context — for example, for timing or logging purposes.
`void`
`afterTestMethod(Object testInstance, Method testMethod, Throwable exception)`
Hook for post-processing a test after execution of after lifecycle callbacks of the underlying test framework — for example, tearing down test fixtures, ending a transaction, etc.
`void`
`beforeTestClass()`
Hook for pre-processing a test class before execution of any tests within the class.
`void`
`beforeTestExecution(Object testInstance, Method testMethod)`
Hook for pre-processing a test immediately before execution of the test method in the supplied test context — for example, for timing or logging purposes.
`void`
`beforeTestMethod(Object testInstance, Method testMethod)`
Hook for pre-processing a test before execution of before lifecycle callbacks of the underlying test framework — for example, setting up test fixtures, starting a transaction, etc.
`final TestContext`
`getTestContext()`
Get the `TestContext` managed by this `TestContextManager`.
`final List<TestExecutionListener>`
`getTestExecutionListeners()`
Get the current `TestExecutionListeners` registered for this `TestContextManager`.
`void`
`prepareTestInstance(Object testInstance)`
Hook for preparing a test instance prior to execution of any individual test methods — for example, to inject dependencies.
`void`
`registerTestExecutionListeners(List<TestExecutionListener> testExecutionListeners)`
Register the supplied list of `TestExecutionListeners` by appending them to the list of listeners used by this `TestContextManager`.
`void`
`registerTestExecutionListeners(TestExecutionListener... testExecutionListeners)`
Register the supplied array of `TestExecutionListeners` by appending them to the list of listeners used by this `TestContextManager`.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### TestContextManager

public TestContextManager(Class<?> testClass)
Construct a new `TestContextManager` for the supplied test class.

Delegates to `TestContextManager(TestContextBootstrapper)` with the `TestContextBootstrapper` configured for the test class. If the `@BootstrapWith` annotation is present on the test class, either directly or as a meta-annotation, then its `value` will be used as the bootstrapper type; otherwise, the `DefaultTestContextBootstrapper` will be used.

Parameters:
  `testClass` - the test class to be managed
See Also:
  - `TestContextManager(TestContextBootstrapper)`

### TestContextManager

public TestContextManager(TestContextBootstrapper testContextBootstrapper)
Construct a new `TestContextManager` using the supplied `TestContextBootstrapper` and register the necessary `TestExecutionListeners`.

Delegates to the supplied `TestContextBootstrapper` for building the `TestContext` and retrieving the `TestExecutionListeners`.

Parameters:
  `testContextBootstrapper` - the bootstrapper to use
Since:
  4.2
See Also:
  - `TestContextBootstrapper.buildTestContext()`
  - `TestContextBootstrapper.getTestExecutionListeners()`
  - `registerTestExecutionListeners(java.util.List<org.springframework.test.context.TestExecutionListener>)`

## Method Details

### getTestContext

public final TestContext getTestContext()
Get the `TestContext` managed by this `TestContextManager`.

### registerTestExecutionListeners

public void registerTestExecutionListeners(List<TestExecutionListener> testExecutionListeners)
Register the supplied list of `TestExecutionListeners` by appending them to the list of listeners used by this `TestContextManager`.

See Also:
  - `registerTestExecutionListeners(TestExecutionListener...)`

### registerTestExecutionListeners

public void registerTestExecutionListeners(TestExecutionListener... testExecutionListeners)
Register the supplied array of `TestExecutionListeners` by appending them to the list of listeners used by this `TestContextManager`.

### getTestExecutionListeners

public final List<TestExecutionListener> getTestExecutionListeners()
Get the current `TestExecutionListeners` registered for this `TestContextManager`.

Allows for modifications, for example, adding a listener to the beginning of the list. However, make sure to keep the list stable while actually executing tests.

### beforeTestClass

public void beforeTestClass() throws Exception
Hook for pre-processing a test class before execution of any tests within the class. Should be called prior to any framework-specific before class methods — for example, methods annotated with JUnit Jupiter's `@BeforeAll`.

An attempt will be made to give each registered `TestExecutionListener` a chance to pre-process the test class execution. If a listener throws an exception, however, the remaining registered listeners will not be called.

Throws:
  `Exception` - if a registered TestExecutionListener throws an exception
Since:
  3.0
See Also:
  - `getTestExecutionListeners()`

### prepareTestInstance

public void prepareTestInstance(Object testInstance) throws Exception
Hook for preparing a test instance prior to execution of any individual test methods — for example, to inject dependencies.

This method should be called immediately after instantiation of the test class or as soon after instantiation as possible (as is the case with the `SpringMethodRule`). In any case, this method must be called prior to any framework-specific lifecycle callbacks.

The managed `TestContext` will be updated with the supplied `testInstance`.

An attempt will be made to give each registered `TestExecutionListener` a chance to prepare the test instance. If a listener throws an exception, however, the remaining registered listeners will not be called.

Parameters:
  `testInstance` - the test instance to prepare
Throws:
  `Exception` - if a registered TestExecutionListener throws an exception
See Also:
  - `getTestExecutionListeners()`

### beforeTestMethod

public void beforeTestMethod(Object testInstance, Method testMethod) throws Exception
Hook for pre-processing a test before execution of before lifecycle callbacks of the underlying test framework — for example, setting up test fixtures, starting a transaction, etc.

This method must be called immediately prior to framework-specific before lifecycle callbacks — for example, methods annotated with JUnit Jupiter's `@BeforeEach`. For historical reasons, this method is named `beforeTestMethod`. Since the introduction of `beforeTestExecution(java.lang.Object, java.lang.reflect.Method)`, a more suitable name for this method might be something like `beforeTestSetUp` or `beforeEach`; however, it is unfortunately impossible to rename this method due to backward compatibility concerns.

The managed `TestContext` will be updated with the supplied `testInstance` and `testMethod`.

An attempt will be made to give each registered `TestExecutionListener` a chance to perform its pre-processing. If a listener throws an exception, however, the remaining registered listeners will not be called.

Parameters:
  `testInstance` - the current test instance
  `testMethod` - the test method which is about to be executed on the test instance
Throws:
  `Exception` - if a registered TestExecutionListener throws an exception
See Also:
  - `afterTestMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)`
  - `beforeTestExecution(java.lang.Object, java.lang.reflect.Method)`
  - `afterTestExecution(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)`
  - `getTestExecutionListeners()`

### beforeTestExecution

public void beforeTestExecution(Object testInstance, Method testMethod) throws Exception
Hook for pre-processing a test immediately before execution of the test method in the supplied test context — for example, for timing or logging purposes.

This method must be called after framework-specific before lifecycle callbacks — for example, methods annotated with JUnit Jupiter's `@BeforeEach`.

The managed `TestContext` will be updated with the supplied `testInstance` and `testMethod`.

An attempt will be made to give each registered `TestExecutionListener` a chance to perform its pre-processing. If a listener throws an exception, however, the remaining registered listeners will not be called.

Parameters:
  `testInstance` - the current test instance
  `testMethod` - the test method which is about to be executed on the test instance
Throws:
  `Exception` - if a registered TestExecutionListener throws an exception
Since:
  5.0
See Also:
  - `beforeTestMethod(java.lang.Object, java.lang.reflect.Method)`
  - `afterTestMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)`
  - `beforeTestExecution(java.lang.Object, java.lang.reflect.Method)`
  - `afterTestExecution(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)`
  - `getTestExecutionListeners()`

### afterTestExecution

public void afterTestExecution(Object testInstance, Method testMethod, @Nullable Throwable exception) throws Exception
Hook for post-processing a test immediately after execution of the test method in the supplied test context — for example, for timing or logging purposes.

This method must be called before framework-specific after lifecycle callbacks — for example, methods annotated with JUnit Jupiter's `@AfterEach`.

The managed `TestContext` will be updated with the supplied `testInstance`, `testMethod`, and `exception`.

Each registered `TestExecutionListener` will be given a chance to perform its post-processing. If a listener throws an exception, the remaining registered listeners will still be called. After all listeners have executed, the first caught exception will be rethrown with any subsequent exceptions suppressed in the first exception.

Note that listeners will be executed in the opposite order in which they were registered.

Parameters:
  `testInstance` - the current test instance
  `testMethod` - the test method which has just been executed on the test instance
  `exception` - the exception that was thrown during execution of the test method or by a TestExecutionListener, or `null` if none was thrown
Throws:
  `Exception` - if a registered TestExecutionListener throws an exception
Since:
  5.0
See Also:
  - `beforeTestMethod(java.lang.Object, java.lang.reflect.Method)`
  - `afterTestMethod(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)`
  - `beforeTestExecution(java.lang.Object, java.lang.reflect.Method)`
  - `getTestExecutionListeners()`
  - `Throwable.addSuppressed(Throwable)`

### afterTestMethod

public void afterTestMethod(Object testInstance, Method testMethod, @Nullable Throwable exception) throws Exception
Hook for post-processing a test after execution of after lifecycle callbacks of the underlying test framework — for example, tearing down test fixtures, ending a transaction, etc.

This method must be called immediately after framework-specific after lifecycle callbacks — for example, methods annotated with JUnit Jupiter's `@AfterEach`. For historical reasons, this method is named `afterTestMethod`. Since the introduction of `afterTestExecution(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)`, a more suitable name for this method might be something like `afterTestTearDown` or `afterEach`; however, it is unfortunately impossible to rename this method due to backward compatibility concerns.

The managed `TestContext` will be updated with the supplied `testInstance`, `testMethod`, and `exception`.

Each registered `TestExecutionListener` will be given a chance to perform its post-processing. If a listener throws an exception, the remaining registered listeners will still be called. After all listeners have executed, the first caught exception will be rethrown with any subsequent exceptions suppressed in the first exception.

Note that listeners will be executed in the opposite order in which they were registered.

Parameters:
  `testInstance` - the current test instance
  `testMethod` - the test method which has just been executed on the test instance
  `exception` - the exception that was thrown during execution of the test method or by a TestExecutionListener, or `null` if none was thrown
Throws:
  `Exception` - if a registered TestExecutionListener throws an exception
See Also:
  - `beforeTestMethod(java.lang.Object, java.lang.reflect.Method)`
  - `beforeTestExecution(java.lang.Object, java.lang.reflect.Method)`
  - `afterTestExecution(java.lang.Object, java.lang.reflect.Method, java.lang.Throwable)`
  - `getTestExecutionListeners()`
  - `Throwable.addSuppressed(Throwable)`

### afterTestClass

public void afterTestClass() throws Exception
Hook for post-processing a test class after execution of all tests within the class. Should be called after any framework-specific after class methods — for example, methods annotated with JUnit Jupiter's `@AfterAll`.

Each registered `TestExecutionListener` will be given a chance to perform its post-processing. If a listener throws an exception, the remaining registered listeners will still be called. After all listeners have executed, the first caught exception will be rethrown with any subsequent exceptions suppressed in the first exception.

Note that listeners will be executed in the opposite order in which they were registered.

Throws:
  `Exception` - if a registered TestExecutionListener throws an exception
Since:
  3.0
See Also:
  - `getTestExecutionListeners()`
  - `Throwable.addSuppressed(Throwable)`