BlockJUnit4ClassRunner (JUnit API)
Date: 2018-08-04

org.junit.runners

## Class BlockJUnit4ClassRunner

- java.lang.Object
- - org.junit.runner.Runner
  - - org.junit.runners.ParentRunner<FrameworkMethod>
    - - org.junit.runners.BlockJUnit4ClassRunner

- All Implemented Interfaces:
    Describable, Filterable, Sortable
  Direct Known Subclasses:
    BlockJUnit4ClassRunnerWithParameters, JUnit4, Theories

      public class BlockJUnit4ClassRunner
      extends ParentRunner<FrameworkMethod>

  Implements the JUnit 4 standard test case class model, as defined by the annotations in the org.junit package. Many users will never notice this class: it is now the default test class runner, but it should have exactly the same behavior as the old test class runner (`JUnit4ClassRunner`).

  BlockJUnit4ClassRunner has advantages for writers of custom JUnit runners that are slight changes to the default behavior, however:

  - It has a much simpler implementation based on `Statement`s, allowing new operations to be inserted into the appropriate point in the execution flow.
  - It is published, and extension and reuse are encouraged, whereas `JUnit4ClassRunner` was in an internal package, and is now deprecated.

  In turn, in 2009 we introduced `Rule`s. In many cases where extending BlockJUnit4ClassRunner was necessary to add new behavior, `Rule`s can be used, which makes the extension more reusable and composable.

  Since:
    4.5

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `BlockJUnit4ClassRunner(java.lang.Class<?> klass)` Creates a BlockJUnit4ClassRunner to run `klass`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `collectInitializationErrors(java.util.List<java.lang.Throwable> errors)` Adds to `errors` a throwable for each problem noted with the test class (available from `ParentRunner.getTestClass()`).
    `protected java.util.List<FrameworkMethod>` | `computeTestMethods()` Returns the methods that run tests.
    `protected java.lang.Object` | `createTest()` Returns a new fixture for running a test.
    `protected Description` | `describeChild(FrameworkMethod method)` Returns a `Description` for `child`, which can be assumed to be an element of the list returned by `ParentRunner.getChildren()`
    `protected java.util.List<FrameworkMethod>` | `getChildren()` Returns a list of objects that define the children of this Runner.
    `protected java.util.List<TestRule>` | `getTestRules(java.lang.Object target)`
    `protected boolean` | `isIgnored(FrameworkMethod child)` Evaluates whether `FrameworkMethod`s are ignored based on the `Ignore` annotation.
    `protected Statement` | `methodBlock(FrameworkMethod method)` Returns a Statement that, when executed, either returns normally if `method` passes, or throws an exception if `method` fails.
    `protected Statement` | `methodInvoker(FrameworkMethod method, java.lang.Object test)` Returns a `Statement` that invokes `method` on `test`
    `protected Statement` | `possiblyExpectingExceptions(FrameworkMethod method, java.lang.Object test, Statement next)` Returns a `Statement`: if `method`'s `@Test` annotation has the `expecting` attribute, return normally only if `next` throws an exception of the correct type, and throw an exception otherwise.
    `protected java.util.List<MethodRule>` | `rules(java.lang.Object target)`
    `protected void` | `runChild(FrameworkMethod method, RunNotifier notifier)` Runs the test corresponding to `child`, which can be assumed to be an element of the list returned by `ParentRunner.getChildren()`.
    `protected java.lang.String` | `testName(FrameworkMethod method)` Returns the name that describes `method` for `Description`s.
    `protected void` | `validateConstructor(java.util.List<java.lang.Throwable> errors)` Adds to `errors` if the test class has more than one constructor, or if the constructor takes parameters.
    `protected void` | `validateFields(java.util.List<java.lang.Throwable> errors)`
    `protected void` | `validateInstanceMethods(java.util.List<java.lang.Throwable> errors)` Deprecated.
    `protected void` | `validateNoNonStaticInnerClass(java.util.List<java.lang.Throwable> errors)`
    `protected void` | `validateOnlyOneConstructor(java.util.List<java.lang.Throwable> errors)` Adds to `errors` if the test class has more than one constructor (do not override)
    `protected void` | `validateTestMethods(java.util.List<java.lang.Throwable> errors)` Adds to `errors` for each method annotated with `@Test`that is not a public, void instance method with no arguments.
    `protected void` | `validateZeroArgConstructor(java.util.List<java.lang.Throwable> errors)` Adds to `errors` if the test class's single constructor takes parameters (do not override)
    `protected Statement` | `withAfters(FrameworkMethod method, java.lang.Object target, Statement statement)` Returns a `Statement`: run all non-overridden `@After` methods on this class and superclasses before running `next`; all After methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from After methods into a `MultipleFailureException`.
    `protected Statement` | `withBefores(FrameworkMethod method, java.lang.Object target, Statement statement)` Returns a `Statement`: run all non-overridden `@Before` methods on this class and superclasses before running `next`; if any throws an Exception, stop execution and pass the exception on.
    `protected Statement` | `withPotentialTimeout(FrameworkMethod method, java.lang.Object test, Statement next)` Deprecated.

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

      `childrenInvoker, classBlock, classRules, createTestClass, filter, getDescription, getName, getRunnerAnnotations, getTestClass, run, runLeaf, setScheduler, sort, validatePublicVoidNoArgMethods, withAfterClasses, withBeforeClasses`

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

    - #### BlockJUnit4ClassRunner

          public BlockJUnit4ClassRunner(java.lang.Class<?> klass)
                                 throws InitializationError

      Creates a BlockJUnit4ClassRunner to run `klass`
      Throws:
        `InitializationError` - if the test class is malformed.

  - ### Method Detail

    - #### runChild

          protected void runChild(FrameworkMethod method,
                      RunNotifier notifier)

      Description copied from class: `ParentRunner`
      Runs the test corresponding to `child`, which can be assumed to be an element of the list returned by `ParentRunner.getChildren()`. Subclasses are responsible for making sure that relevant test events are reported through `notifier`
      Specified by:
        `runChild` in class `ParentRunner<FrameworkMethod>`

    - #### isIgnored

          protected boolean isIgnored(FrameworkMethod child)

      Evaluates whether `FrameworkMethod`s are ignored based on the `Ignore` annotation.
      Overrides:
        `isIgnored` in class `ParentRunner<FrameworkMethod>`

    - #### describeChild

          protected Description describeChild(FrameworkMethod method)

      Description copied from class: `ParentRunner`
      Returns a `Description` for `child`, which can be assumed to be an element of the list returned by `ParentRunner.getChildren()`
      Specified by:
        `describeChild` in class `ParentRunner<FrameworkMethod>`

    - #### getChildren

          protected java.util.List<FrameworkMethod> getChildren()

      Description copied from class: `ParentRunner`
      Returns a list of objects that define the children of this Runner.
      Specified by:
        `getChildren` in class `ParentRunner<FrameworkMethod>`

    - #### computeTestMethods

          protected java.util.List<FrameworkMethod> computeTestMethods()

      Returns the methods that run tests. Default implementation returns all methods annotated with `@Test` on this class and superclasses that are not overridden.

    - #### collectInitializationErrors

          protected void collectInitializationErrors(java.util.List<java.lang.Throwable> errors)

      Description copied from class: `ParentRunner`
      Adds to `errors` a throwable for each problem noted with the test class (available from `ParentRunner.getTestClass()`). Default implementation adds an error for each method annotated with `@BeforeClass` or `@AfterClass` that is not `public static void` with no arguments.
      Overrides:
        `collectInitializationErrors` in class `ParentRunner<FrameworkMethod>`

    - #### validateNoNonStaticInnerClass

          protected void validateNoNonStaticInnerClass(java.util.List<java.lang.Throwable> errors)

    - #### validateConstructor

          protected void validateConstructor(java.util.List<java.lang.Throwable> errors)

      Adds to `errors` if the test class has more than one constructor, or if the constructor takes parameters. Override if a subclass requires different validation rules.

    - #### validateOnlyOneConstructor

          protected void validateOnlyOneConstructor(java.util.List<java.lang.Throwable> errors)

      Adds to `errors` if the test class has more than one constructor (do not override)

    - #### validateZeroArgConstructor

          protected void validateZeroArgConstructor(java.util.List<java.lang.Throwable> errors)

      Adds to `errors` if the test class's single constructor takes parameters (do not override)

    - #### validateInstanceMethods

          @Deprecated
          protected void validateInstanceMethods(java.util.List<java.lang.Throwable> errors)

      Deprecated.
      Adds to `errors` for each method annotated with `@Test`, `@Before`, or `@After` that is not a public, void instance method with no arguments.

    - #### validateFields

          protected void validateFields(java.util.List<java.lang.Throwable> errors)

    - #### validateTestMethods

          protected void validateTestMethods(java.util.List<java.lang.Throwable> errors)

      Adds to `errors` for each method annotated with `@Test`that is not a public, void instance method with no arguments.

    - #### createTest

          protected java.lang.Object createTest()
                                         throws java.lang.Exception

      Returns a new fixture for running a test. Default implementation executes the test class's no-argument constructor (validation should have ensured one exists).
      Throws:
        `java.lang.Exception`

    - #### testName

          protected java.lang.String testName(FrameworkMethod method)

      Returns the name that describes `method` for `Description`s. Default implementation is the method's name

    - #### methodBlock

          protected Statement methodBlock(FrameworkMethod method)

      Returns a Statement that, when executed, either returns normally if `method` passes, or throws an exception if `method` fails. Here is an outline of the default implementation:
      - Invoke `method` on the result of `createTest()`, and throw any exceptions thrown by either operation.
      - HOWEVER, if `method`'s `@Test` annotation has the `expecting` attribute, return normally only if the previous step threw an exception of the correct type, and throw an exception otherwise.
      - HOWEVER, if `method`'s `@Test` annotation has the `timeout` attribute, throw an exception if the previous step takes more than the specified number of milliseconds.
      - ALWAYS run all non-overridden `@Before` methods on this class and superclasses before any of the previous steps; if any throws an Exception, stop execution and pass the exception on.
      - ALWAYS run all non-overridden `@After` methods on this class and superclasses after any of the previous steps; all After methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from After methods into a `MultipleFailureException`.
      - ALWAYS allow `@Rule` fields to modify the execution of the above steps. A `Rule` may prevent all execution of the above steps, or add additional behavior before and after, or modify thrown exceptions. For more information, see `TestRule`
      This can be overridden in subclasses, either by overriding this method, or the implementations creating each sub-statement.

    - #### methodInvoker

          protected Statement methodInvoker(FrameworkMethod method,
                                java.lang.Object test)

      Returns a `Statement` that invokes `method` on `test`

    - #### possiblyExpectingExceptions

          protected Statement possiblyExpectingExceptions(FrameworkMethod method,
                                              java.lang.Object test,
                                              Statement next)

      Returns a `Statement`: if `method`'s `@Test` annotation has the `expecting` attribute, return normally only if `next` throws an exception of the correct type, and throw an exception otherwise.

    - #### withPotentialTimeout

          @Deprecated
          protected Statement withPotentialTimeout(FrameworkMethod method,
                                                  java.lang.Object test,
                                                  Statement next)

      Deprecated.
      Returns a `Statement`: if `method`'s `@Test` annotation has the `timeout` attribute, throw an exception if `next` takes more than the specified number of milliseconds.

    - #### withBefores

          protected Statement withBefores(FrameworkMethod method,
                              java.lang.Object target,
                              Statement statement)

      Returns a `Statement`: run all non-overridden `@Before` methods on this class and superclasses before running `next`; if any throws an Exception, stop execution and pass the exception on.

    - #### withAfters

          protected Statement withAfters(FrameworkMethod method,
                             java.lang.Object target,
                             Statement statement)

      Returns a `Statement`: run all non-overridden `@After` methods on this class and superclasses before running `next`; all After methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from After methods into a `MultipleFailureException`.

    - #### rules

          protected java.util.List<MethodRule> rules(java.lang.Object target)

      Parameters:
        `target` - the test case instance
      Returns:
        a list of MethodRules that should be applied when executing this test

    - #### getTestRules

          protected java.util.List<TestRule> getTestRules(java.lang.Object target)

      Parameters:
        `target` - the test case instance
      Returns:
        a list of TestRules that should be applied when executing this test