TestContextManager (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

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, which provides support for loading and accessing `application contexts`, dependency injection of test instances, `transactional` execution of test methods, etc.

  Specifically, a `TestContextManager` is responsible for managing a single `TestContext` and signaling events to all registered `TestExecutionListeners` at well defined test execution points:

  - `before test class execution`: prior to any before class methods of a particular testing framework (e.g., JUnit 4's `@BeforeClass`)
  - `test instance preparation`: immediately following instantiation of the test instance
  - `before test method execution`: prior to any before methods of a particular testing framework (e.g., JUnit 4's `@Before`)
  - `after test method execution`: after any after methods of a particular testing framework (e.g., JUnit 4's `@After`)
  - `after test class execution`: after any after class methods of a particular testing framework (e.g., JUnit 4's `@AfterClass`)
  Since:
    2.5
  Author:
    Sam Brannen, Juergen Hoeller
  See Also:
    `TestContext`, `TestExecutionListeners`, `ContextConfiguration`, `TransactionConfiguration`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `TestContextManager(Class<?> testClass)` Delegates to `TestContextManager(Class, String)` with a value of `null` for the default `ContextLoader` class name.
    `TestContextManager(Class<?> testClass, String defaultContextLoaderClassName)` Constructs a new `TestContextManager` for the specified `test class` and automatically `registers` the `TestExecutionListeners` configured for the test class via the `@TestExecutionListeners` annotation.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterTestClass()` Hook for post-processing a test class after execution of all tests within the class.
    `void` | `afterTestMethod(Object testInstance, Method testMethod, Throwable exception)` Hook for post-processing a test after execution of the supplied `test method`, for example for 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` | `beforeTestMethod(Object testInstance, Method testMethod)` Hook for pre-processing a test before execution of the supplied `test method`, for example for setting up test fixtures, starting a transaction, etc.
    `protected Set<Class<? extends TestExecutionListener>>` | `getDefaultTestExecutionListenerClasses()` Determine the default `TestExecutionListener` classes.
    `protected TestContext` | `getTestContext()` Returns the `TestContext` managed by this `TestContextManager`.
    `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 for injecting dependencies, etc.
    `void` | `registerTestExecutionListeners(TestExecutionListener... testExecutionListeners)` Register the supplied `TestExecutionListeners` by appending them to the set 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 Detail

    - #### TestContextManager

          public TestContextManager(Class<?> testClass)

      Delegates to `TestContextManager(Class, String)` with a value of `null` for the default `ContextLoader` class name.

    - #### TestContextManager

          public TestContextManager(Class<?> testClass,
                            String defaultContextLoaderClassName)

      Constructs a new `TestContextManager` for the specified `test class` and automatically `registers` the `TestExecutionListeners` configured for the test class via the `@TestExecutionListeners` annotation.
      Parameters:
        `testClass` - the test class to be managed
        `defaultContextLoaderClassName` - the name of the default `ContextLoader` class to use (may be `null`)
      See Also:
        `registerTestExecutionListeners(TestExecutionListener...)`, `retrieveTestExecutionListeners(Class)`

  - ### Method Detail

    - #### getTestContext

          protected final TestContext getTestContext()

      Returns the `TestContext` managed by this `TestContextManager`.

    - #### registerTestExecutionListeners

          public void registerTestExecutionListeners(TestExecutionListener... testExecutionListeners)

      Register the supplied `TestExecutionListeners` by appending them to the set of listeners used by this `TestContextManager`.

    - #### getTestExecutionListeners

          public final List<TestExecutionListener> getTestExecutionListeners()

      Get the current `TestExecutionListeners` registered for this `TestContextManager`.

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

    - #### getDefaultTestExecutionListenerClasses

          protected Set<Class<? extends TestExecutionListener>> getDefaultTestExecutionListenerClasses()

      Determine the default `TestExecutionListener` classes.

    - #### 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 (e.g., methods annotated with JUnit's `@BeforeClass`).

      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
      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 for injecting dependencies, etc. Should be called immediately after instantiation of the test instance.

      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 (never `null`)
      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 the supplied `test method`, for example for setting up test fixtures, starting a transaction, etc. Should be called prior to any framework-specific before methods (e.g., methods annotated with JUnit's `@Before`).

      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 pre-process the test method execution. If a listener throws an exception, however, the remaining registered listeners will not be called.

      Parameters:
        `testInstance` - the current test instance (never `null`)
        `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:
        `getTestExecutionListeners()`

    - #### afterTestMethod

          public void afterTestMethod(Object testInstance,
                             Method testMethod,
                             Throwable exception)
                               throws Exception

      Hook for post-processing a test after execution of the supplied `test method`, for example for tearing down test fixtures, ending a transaction, etc. Should be called after any framework-specific after methods (e.g., methods annotated with JUnit's `@After`).

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

      Each registered `TestExecutionListener` will be given a chance to post-process the test method execution. If a listener throws an exception, the remaining registered listeners will still be called, but the first exception thrown will be tracked and rethrown after all listeners have executed. Note that registered listeners will be executed in the opposite order in which they were registered.

      Parameters:
        `testInstance` - the current test instance (never `null`)
        `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:
        `getTestExecutionListeners()`

    - #### 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 (e.g., methods annotated with JUnit's `@AfterClass`).

      Each registered `TestExecutionListener` will be given a chance to post-process the test class. If a listener throws an exception, the remaining registered listeners will still be called, but the first exception thrown will be tracked and rethrown after all listeners have executed. Note that registered listeners will be executed in the opposite order in which they were registered.

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