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

org.junit.runners

## Class ParentRunner<T>

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

- All Implemented Interfaces:
    Describable, Filterable, Sortable
  Direct Known Subclasses:
    BlockJUnit4ClassRunner, Suite

      public abstract class ParentRunner<T>
      extends Runner
      implements Filterable, Sortable

  Provides most of the functionality specific to a Runner that implements a "parent node" in the test tree, with children defined by objects of some data type `T`. (For `BlockJUnit4ClassRunner`, `T` is `Method` . For `Suite`, `T` is `Class`.) Subclasses must implement finding the children of the node, describing each child, and running each child. ParentRunner will filter and sort children, handle `@BeforeClass` and `@AfterClass` methods, handle annotated `ClassRule`s, create a composite `Description`, and run children sequentially.
  Since:
    4.5

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `ParentRunner(java.lang.Class<?> testClass)` Constructs a new `ParentRunner` that will run `@TestClass`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Statement` | `childrenInvoker(RunNotifier notifier)` Returns a `Statement`: Call `runChild(Object, RunNotifier)` on each object returned by `getChildren()` (subject to any imposed filter and sort)
    `protected Statement` | `classBlock(RunNotifier notifier)` Constructs a `Statement` to run all of the tests in the test class.
    `protected java.util.List<TestRule>` | `classRules()`
    `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 `getTestClass()`).
    `protected TestClass` | `createTestClass(java.lang.Class<?> testClass)`
    `protected abstract Description` | `describeChild(T child)` Returns a `Description` for `child`, which can be assumed to be an element of the list returned by `getChildren()`
    `void` | `filter(Filter filter)` Remove tests that don't pass the parameter `filter`.
    `protected abstract java.util.List<T>` | `getChildren()` Returns a list of objects that define the children of this Runner.
    `Description` | `getDescription()`
    `protected java.lang.String` | `getName()` Returns a name used to describe this Runner
    `protected java.lang.annotation.Annotation[]` | `getRunnerAnnotations()`
    `TestClass` | `getTestClass()` Returns a `TestClass` object wrapping the class to be executed.
    `protected boolean` | `isIgnored(T child)` Evaluates whether a child is ignored.
    `void` | `run(RunNotifier notifier)` Run the tests for this runner.
    `protected abstract void` | `runChild(T child, RunNotifier notifier)` Runs the test corresponding to `child`, which can be assumed to be an element of the list returned by `getChildren()`.
    `protected void` | `runLeaf(Statement statement, Description description, RunNotifier notifier)` Runs a `Statement` that represents a leaf (aka atomic) test.
    `void` | `setScheduler(RunnerScheduler scheduler)` Sets a scheduler that determines the order and parallelization of children.
    `void` | `sort(Sorter sorter)` Sorts the tests using `sorter`
    `protected void` | `validatePublicVoidNoArgMethods(java.lang.Class<? extends java.lang.annotation.Annotation> annotation, boolean isStatic, java.util.List<java.lang.Throwable> errors)` Adds to `errors` if any method in this class is annotated with `annotation`, but: is not public, or takes parameters, or returns something other than void, or is static (given `isStatic is false`), or is not static (given `isStatic is true`).
    `protected Statement` | `withAfterClasses(Statement statement)` Returns a `Statement`: run all non-overridden `@AfterClass` methods on this class and superclasses before executing `statement`; all AfterClass methods are always executed: exceptions thrown by previous steps are combined, if necessary, with exceptions from AfterClass methods into a `MultipleFailureException`.
    `protected Statement` | `withBeforeClasses(Statement statement)` Returns a `Statement`: run all non-overridden `@BeforeClass` methods on this class and superclasses before executing `statement`; if any throws an Exception, stop execution and pass the exception on.

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

    - #### ParentRunner

          protected ParentRunner(java.lang.Class<?> testClass)
                          throws InitializationError

      Constructs a new `ParentRunner` that will run `@TestClass`
      Throws:
        `InitializationError`

  - ### Method Detail

    - #### createTestClass

          protected TestClass createTestClass(java.lang.Class<?> testClass)

    - #### getChildren

          protected abstract java.util.List<T> getChildren()

      Returns a list of objects that define the children of this Runner.

    - #### describeChild

          protected abstract Description describeChild(T child)

      Returns a `Description` for `child`, which can be assumed to be an element of the list returned by `getChildren()`

    - #### runChild

          protected abstract void runChild(T child,
                      RunNotifier notifier)

      Runs the test corresponding to `child`, which can be assumed to be an element of the list returned by `getChildren()`. Subclasses are responsible for making sure that relevant test events are reported through `notifier`

    - #### collectInitializationErrors

          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 `getTestClass()`). Default implementation adds an error for each method annotated with `@BeforeClass` or `@AfterClass` that is not `public static void` with no arguments.

    - #### validatePublicVoidNoArgMethods

          protected void validatePublicVoidNoArgMethods(java.lang.Class<? extends java.lang.annotation.Annotation> annotation,
                                            boolean isStatic,
                                            java.util.List<java.lang.Throwable> errors)

      Adds to `errors` if any method in this class is annotated with `annotation`, but:
      - is not public, or
      - takes parameters, or
      - returns something other than void, or
      - is static (given `isStatic is false`), or
      - is not static (given `isStatic is true`).

    - #### classBlock

          protected Statement classBlock(RunNotifier notifier)

      Constructs a `Statement` to run all of the tests in the test class. Override to add pre-/post-processing. Here is an outline of the implementation:
      1. Determine the children to be run using `getChildren()` (subject to any imposed filter and sort).
      2. If there are any children remaining after filtering and ignoring, construct a statement that will:
         1. Apply all `ClassRule`s on the test-class and superclasses.
         2. Run all non-overridden `@BeforeClass` methods on the test-class and superclasses; if any throws an Exception, stop execution and pass the exception on.
         3. Run all remaining tests on the test-class.
         4. Run all non-overridden `@AfterClass` methods on the test-class and superclasses: exceptions thrown by previous steps are combined, if necessary, with exceptions from AfterClass methods into a `MultipleFailureException`.
      Returns:
        `Statement`

    - #### withBeforeClasses

          protected Statement withBeforeClasses(Statement statement)

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

    - #### withAfterClasses

          protected Statement withAfterClasses(Statement statement)

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

    - #### classRules

          protected java.util.List<TestRule> classRules()

      Returns:
        the `ClassRule`s that can transform the block that runs each method in the tested class.

    - #### childrenInvoker

          protected Statement childrenInvoker(RunNotifier notifier)

      Returns a `Statement`: Call `runChild(Object, RunNotifier)` on each object returned by `getChildren()` (subject to any imposed filter and sort)

    - #### isIgnored

          protected boolean isIgnored(T child)

      Evaluates whether a child is ignored. The default implementation always returns `false`.

      `BlockJUnit4ClassRunner`, for example, overrides this method to filter tests based on the `Ignore` annotation.

    - #### getName

          protected java.lang.String getName()

      Returns a name used to describe this Runner

    - #### getTestClass

          public final TestClass getTestClass()

      Returns a `TestClass` object wrapping the class to be executed.

    - #### runLeaf

          protected final void runLeaf(Statement statement,
                     Description description,
                     RunNotifier notifier)

      Runs a `Statement` that represents a leaf (aka atomic) test.

    - #### getRunnerAnnotations

          protected java.lang.annotation.Annotation[] getRunnerAnnotations()

      Returns:
        the annotations that should be attached to this runner's description.

    - #### getDescription

          public Description getDescription()

      Specified by:
        `getDescription` in interface `Describable`
      Specified by:
        `getDescription` in class `Runner`
      Returns:
        a `Description` showing the tests to be run by the receiver

    - #### run

          public void run(RunNotifier notifier)

      Description copied from class: `Runner`
      Run the tests for this runner.
      Specified by:
        `run` in class `Runner`
      Parameters:
        `notifier` - will be notified of events while tests are being run--tests being started, finishing, and failing

    - #### filter

          public void filter(Filter filter)
                      throws NoTestsRemainException

      Description copied from interface: `Filterable`
      Remove tests that don't pass the parameter `filter`.
      Specified by:
        `filter` in interface `Filterable`
      Parameters:
        `filter` - the `Filter` to apply
      Throws:
        `NoTestsRemainException` - if all tests are filtered out

    - #### sort

          public void sort(Sorter sorter)

      Description copied from interface: `Sortable`
      Sorts the tests using `sorter`
      Specified by:
        `sort` in interface `Sortable`
      Parameters:
        `sorter` - the `Sorter` to use for sorting the tests

    - #### setScheduler

          public void setScheduler(RunnerScheduler scheduler)

      Sets a scheduler that determines the order and parallelization of children. Highly experimental feature that may change.