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

org.springframework.test.context.junit4

## Class SpringJUnit4ClassRunner

- java.lang.Object
- - org.junit.runner.Runner
  - - org.junit.runners.ParentRunner<org.junit.runners.model.FrameworkMethod>
    - - org.junit.runners.BlockJUnit4ClassRunner
      - - org.springframework.test.context.junit4.SpringJUnit4ClassRunner

- All Implemented Interfaces:
    org.junit.runner.Describable, org.junit.runner.manipulation.Filterable, org.junit.runner.manipulation.Sortable

      public class SpringJUnit4ClassRunner
      extends org.junit.runners.BlockJUnit4ClassRunner

  `SpringJUnit4ClassRunner` is a custom extension of `BlockJUnit4ClassRunner` which provides functionality of the Spring TestContext Framework to standard JUnit 4.5+ tests by means of the `TestContextManager` and associated support classes and annotations.

  The following list constitutes all annotations currently supported directly by `SpringJUnit4ClassRunner`. (Note that additional annotations may be supported by various `TestExecutionListeners`)

  - `@Test(expected=...)`
  - `@ExpectedException`
  - `@Test(timeout=...)`
  - `@Timed`
  - `@Repeat`
  - `@Ignore`
  - `@ProfileValueSourceConfiguration`
  - `@IfProfileValue`

  NOTE: As of Spring 3.0, `SpringJUnit4ClassRunner` requires JUnit 4.5+.

  Since:
    2.5
  Author:
    Sam Brannen, Juergen Hoeller
  See Also:
    `TestContextManager`

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `SpringJUnit4ClassRunner(Class<?> clazz)` Constructs a new `SpringJUnit4ClassRunner` and initializes a `TestContextManager` to provide Spring testing functionality to standard JUnit tests.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object` | `createTest()` Delegates to the parent implementation for creating the test instance and then allows the `TestContextManager` to prepare the test instance before returning it.
    `protected TestContextManager` | `createTestContextManager(Class<?> clazz)` Creates a new `TestContextManager` for the supplied test class and the configured default `ContextLoader` class name.
    `protected String` | `getDefaultContextLoaderClassName(Class<?> clazz)` Get the name of the default `ContextLoader` class to use for the supplied test class.
    `org.junit.runner.Description` | `getDescription()` Returns a description suitable for an ignored test class if the test is disabled via `&#064;IfProfileValue` at the class-level, and otherwise delegates to the parent implementation.
    `protected Class<? extends Throwable>` | `getExpectedException(org.junit.runners.model.FrameworkMethod frameworkMethod)` Get the `exception` that the supplied `test method` is expected to throw.
    `protected long` | `getJUnitTimeout(org.junit.runners.model.FrameworkMethod frameworkMethod)` Retrieves the configured JUnit `timeout` from the `@Test` annotation on the supplied `test method`.
    `protected long` | `getSpringTimeout(org.junit.runners.model.FrameworkMethod frameworkMethod)` Retrieves the configured Spring-specific `timeout` from the `@Timed` annotation on the supplied `test method`.
    `protected TestContextManager` | `getTestContextManager()` Get the `TestContextManager` associated with this runner.
    `protected boolean` | `isTestMethodIgnored(org.junit.runners.model.FrameworkMethod frameworkMethod)` Returns `true` if `@Ignore` is present for the supplied `test method` or if the test method is disabled via `&#064;IfProfileValue`.
    `protected org.junit.runners.model.Statement` | `methodBlock(org.junit.runners.model.FrameworkMethod frameworkMethod)` Augments the default JUnit behavior `with potential repeats` of the entire execution chain.
    `protected org.junit.runners.model.Statement` | `possiblyExpectingExceptions(org.junit.runners.model.FrameworkMethod frameworkMethod, Object testInstance, org.junit.runners.model.Statement next)` Performs the same logic as `BlockJUnit4ClassRunner.possiblyExpectingExceptions(FrameworkMethod, Object, Statement)` except that the expected exception is retrieved using `getExpectedException(FrameworkMethod)`.
    `void` | `run(org.junit.runner.notification.RunNotifier notifier)` Check whether the test is enabled in the first place.
    `protected void` | `runChild(org.junit.runners.model.FrameworkMethod frameworkMethod, org.junit.runner.notification.RunNotifier notifier)` Performs the same logic as `BlockJUnit4ClassRunner.runChild(FrameworkMethod, RunNotifier)`, except that tests are determined to be ignored by `isTestMethodIgnored(FrameworkMethod)`.
    `protected org.junit.runners.model.Statement` | `withAfterClasses(org.junit.runners.model.Statement statement)` Wraps the `Statement` returned by the parent implementation with a `RunAfterTestClassCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
    `protected org.junit.runners.model.Statement` | `withAfters(org.junit.runners.model.FrameworkMethod frameworkMethod, Object testInstance, org.junit.runners.model.Statement statement)` Wraps the `Statement` returned by the parent implementation with a `RunAfterTestMethodCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
    `protected org.junit.runners.model.Statement` | `withBeforeClasses(org.junit.runners.model.Statement statement)` Wraps the `Statement` returned by the parent implementation with a `RunBeforeTestClassCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
    `protected org.junit.runners.model.Statement` | `withBefores(org.junit.runners.model.FrameworkMethod frameworkMethod, Object testInstance, org.junit.runners.model.Statement statement)` Wraps the `Statement` returned by the parent implementation with a `RunBeforeTestMethodCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
    `protected org.junit.runners.model.Statement` | `withPotentialRepeat(org.junit.runners.model.FrameworkMethod frameworkMethod, Object testInstance, org.junit.runners.model.Statement next)` Supports Spring's `@Repeat` annotation by returning a `SpringRepeat` statement initialized with the configured repeat count or `1` if no repeat count is configured.
    `protected org.junit.runners.model.Statement` | `withPotentialTimeout(org.junit.runners.model.FrameworkMethod frameworkMethod, Object testInstance, org.junit.runners.model.Statement next)` Supports both Spring's `@Timed` and JUnit's `@Test(timeout=...)` annotations, but not both simultaneously.

    - ### Methods inherited from class org.junit.runners.BlockJUnit4ClassRunner

      `collectInitializationErrors, computeTestMethods, describeChild, getChildren, getTestRules, methodInvoker, rules, testName, validateConstructor, validateInstanceMethods, validateNoNonStaticInnerClass, validateOnlyOneConstructor, validateTestMethods, validateZeroArgConstructor`

    - ### Methods inherited from class org.junit.runners.ParentRunner

      `childrenInvoker, classBlock, classRules, filter, getName, getRunnerAnnotations, getTestClass, runLeaf, setScheduler, sort, validatePublicVoidNoArgMethods`

    - ### Methods inherited from class org.junit.runner.Runner

      `testCount`

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

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

- - ### Constructor Detail

    - #### SpringJUnit4ClassRunner

          public SpringJUnit4ClassRunner(Class<?> clazz)
                                  throws org.junit.runners.model.InitializationError

      Constructs a new `SpringJUnit4ClassRunner` and initializes a `TestContextManager` to provide Spring testing functionality to standard JUnit tests.
      Parameters:
        `clazz` - the test class to be run
      Throws:
        `org.junit.runners.model.InitializationError`
      See Also:
        `createTestContextManager(Class)`

  - ### Method Detail

    - #### createTestContextManager

          protected TestContextManager createTestContextManager(Class<?> clazz)

      Creates a new `TestContextManager` for the supplied test class and the configured default `ContextLoader` class name. Can be overridden by subclasses.
      Parameters:
        `clazz` - the test class to be managed
      See Also:
        `getDefaultContextLoaderClassName(Class)`

    - #### getTestContextManager

          protected final TestContextManager getTestContextManager()

      Get the `TestContextManager` associated with this runner.

    - #### getDefaultContextLoaderClassName

          protected String getDefaultContextLoaderClassName(Class<?> clazz)

      Get the name of the default `ContextLoader` class to use for the supplied test class. The named class will be used if the test class does not explicitly declare a `ContextLoader` class via the `&#064;ContextConfiguration` annotation.

      The default implementation returns `null`, thus implying use of the standard default `ContextLoader` class name. Can be overridden by subclasses.

      Parameters:
        `clazz` - the test class
      Returns:
        `null`

    - #### getDescription

          public org.junit.runner.Description getDescription()

      Returns a description suitable for an ignored test class if the test is disabled via `&#064;IfProfileValue` at the class-level, and otherwise delegates to the parent implementation.
      Specified by:
        `getDescription` in interface `org.junit.runner.Describable`
      Overrides:
        `getDescription` in class `org.junit.runners.ParentRunner<org.junit.runners.model.FrameworkMethod>`
      See Also:
        `ProfileValueUtils.isTestEnabledInThisEnvironment(Class)`

    - #### run

          public void run(org.junit.runner.notification.RunNotifier notifier)

      Check whether the test is enabled in the first place. This prevents classes with a non-matching `&#064;IfProfileValue` annotation from running altogether, even skipping the execution of `prepareTestInstance()` `TestExecutionListener` methods.
      Overrides:
        `run` in class `org.junit.runners.ParentRunner<org.junit.runners.model.FrameworkMethod>`
      See Also:
        `ProfileValueUtils.isTestEnabledInThisEnvironment(Class)`, `IfProfileValue`, `TestExecutionListener`

    - #### withBeforeClasses

          protected org.junit.runners.model.Statement withBeforeClasses(org.junit.runners.model.Statement statement)

      Wraps the `Statement` returned by the parent implementation with a `RunBeforeTestClassCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
      Overrides:
        `withBeforeClasses` in class `org.junit.runners.ParentRunner<org.junit.runners.model.FrameworkMethod>`
      See Also:
        `RunBeforeTestClassCallbacks`

    - #### withAfterClasses

          protected org.junit.runners.model.Statement withAfterClasses(org.junit.runners.model.Statement statement)

      Wraps the `Statement` returned by the parent implementation with a `RunAfterTestClassCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
      Overrides:
        `withAfterClasses` in class `org.junit.runners.ParentRunner<org.junit.runners.model.FrameworkMethod>`
      See Also:
        `RunAfterTestClassCallbacks`

    - #### createTest

          protected Object createTest()
                               throws Exception

      Delegates to the parent implementation for creating the test instance and then allows the `TestContextManager` to prepare the test instance before returning it.
      Overrides:
        `createTest` in class `org.junit.runners.BlockJUnit4ClassRunner`
      Throws:
        `Exception`
      See Also:
        `TestContextManager.prepareTestInstance(Object)`

    - #### runChild

          protected void runChild(org.junit.runners.model.FrameworkMethod frameworkMethod,
                      org.junit.runner.notification.RunNotifier notifier)

      Performs the same logic as `BlockJUnit4ClassRunner.runChild(FrameworkMethod, RunNotifier)`, except that tests are determined to be ignored by `isTestMethodIgnored(FrameworkMethod)`.
      Overrides:
        `runChild` in class `org.junit.runners.BlockJUnit4ClassRunner`

    - #### methodBlock

          protected org.junit.runners.model.Statement methodBlock(org.junit.runners.model.FrameworkMethod frameworkMethod)

      Augments the default JUnit behavior `with potential repeats` of the entire execution chain.

      Furthermore, support for timeouts has been moved down the execution chain in order to include execution of `@Before` and `@After` methods within the timed execution. Note that this differs from the default JUnit behavior of executing `&#064;Before` and `&#064;After` methods in the main thread while executing the actual test method in a separate thread. Thus, the end effect is that `&#064;Before` and `&#064;After` methods will be executed in the same thread as the test method. As a consequence, JUnit-specified timeouts will work fine in combination with Spring transactions. Note that JUnit-specific timeouts still differ from Spring-specific timeouts in that the former execute in a separate thread while the latter simply execute in the main thread (like regular tests).

      Overrides:
        `methodBlock` in class `org.junit.runners.BlockJUnit4ClassRunner`
      See Also:
        `possiblyExpectingExceptions(FrameworkMethod, Object, Statement)`, `withBefores(FrameworkMethod, Object, Statement)`, `withAfters(FrameworkMethod, Object, Statement)`, `withPotentialTimeout(FrameworkMethod, Object, Statement)`, `withPotentialRepeat(FrameworkMethod, Object, Statement)`

    - #### isTestMethodIgnored

          protected boolean isTestMethodIgnored(org.junit.runners.model.FrameworkMethod frameworkMethod)

      Returns `true` if `@Ignore` is present for the supplied `test method` or if the test method is disabled via `&#064;IfProfileValue`.
      See Also:
        `ProfileValueUtils.isTestEnabledInThisEnvironment(Method, Class)`

    - #### possiblyExpectingExceptions

          protected org.junit.runners.model.Statement possiblyExpectingExceptions(org.junit.runners.model.FrameworkMethod frameworkMethod,
                                                                      Object testInstance,
                                                                      org.junit.runners.model.Statement next)

      Performs the same logic as `BlockJUnit4ClassRunner.possiblyExpectingExceptions(FrameworkMethod, Object, Statement)` except that the expected exception is retrieved using `getExpectedException(FrameworkMethod)`.
      Overrides:
        `possiblyExpectingExceptions` in class `org.junit.runners.BlockJUnit4ClassRunner`

    - #### getExpectedException

          protected Class<? extends Throwable> getExpectedException(org.junit.runners.model.FrameworkMethod frameworkMethod)

      Get the `exception` that the supplied `test method` is expected to throw.

      Supports both Spring's `@ExpectedException(...)` and JUnit's `@Test(expected=...)` annotations, but not both simultaneously.

      Returns:
        the expected exception, or `null` if none was specified

    - #### withPotentialTimeout

          protected org.junit.runners.model.Statement withPotentialTimeout(org.junit.runners.model.FrameworkMethod frameworkMethod,
                                                               Object testInstance,
                                                               org.junit.runners.model.Statement next)

      Supports both Spring's `@Timed` and JUnit's `@Test(timeout=...)` annotations, but not both simultaneously. Returns either a `SpringFailOnTimeout`, a `FailOnTimeout`, or the unmodified, supplied `Statement` as appropriate.
      Overrides:
        `withPotentialTimeout` in class `org.junit.runners.BlockJUnit4ClassRunner`
      See Also:
        `getSpringTimeout(FrameworkMethod)`, `getJUnitTimeout(FrameworkMethod)`

    - #### getJUnitTimeout

          protected long getJUnitTimeout(org.junit.runners.model.FrameworkMethod frameworkMethod)

      Retrieves the configured JUnit `timeout` from the `@Test` annotation on the supplied `test method`.
      Returns:
        the timeout, or `0` if none was specified.

    - #### getSpringTimeout

          protected long getSpringTimeout(org.junit.runners.model.FrameworkMethod frameworkMethod)

      Retrieves the configured Spring-specific `timeout` from the `@Timed` annotation on the supplied `test method`.
      Returns:
        the timeout, or `0` if none was specified.

    - #### withBefores

          protected org.junit.runners.model.Statement withBefores(org.junit.runners.model.FrameworkMethod frameworkMethod,
                                                      Object testInstance,
                                                      org.junit.runners.model.Statement statement)

      Wraps the `Statement` returned by the parent implementation with a `RunBeforeTestMethodCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
      Overrides:
        `withBefores` in class `org.junit.runners.BlockJUnit4ClassRunner`
      See Also:
        `RunBeforeTestMethodCallbacks`

    - #### withAfters

          protected org.junit.runners.model.Statement withAfters(org.junit.runners.model.FrameworkMethod frameworkMethod,
                                                     Object testInstance,
                                                     org.junit.runners.model.Statement statement)

      Wraps the `Statement` returned by the parent implementation with a `RunAfterTestMethodCallbacks` statement, thus preserving the default functionality but adding support for the Spring TestContext Framework.
      Overrides:
        `withAfters` in class `org.junit.runners.BlockJUnit4ClassRunner`
      See Also:
        `RunAfterTestMethodCallbacks`

    - #### withPotentialRepeat

          protected org.junit.runners.model.Statement withPotentialRepeat(org.junit.runners.model.FrameworkMethod frameworkMethod,
                                                              Object testInstance,
                                                              org.junit.runners.model.Statement next)

      Supports Spring's `@Repeat` annotation by returning a `SpringRepeat` statement initialized with the configured repeat count or `1` if no repeat count is configured.
      See Also:
        `SpringRepeat`