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
`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`