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

org.junit.runner

## Class Request

- java.lang.Object
- - org.junit.runner.Request

-     public abstract class Request
      extends java.lang.Object

  A `Request` is an abstract description of tests to be run. Older versions of JUnit did not need such a concept--tests to be run were described either by classes containing tests or a tree of `Test`s. However, we want to support filtering and sorting, so we need a more abstract specification than the tests themselves and a richer specification than just the classes.

  The flow when JUnit runs tests is that a `Request` specifies some tests to be run -> a `Runner` is created for each class implied by the `Request` -> the `Runner` returns a detailed `Description` which is a tree structure of the tests to be run.

  Since:
    4.0

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Request()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Request` | `aClass(java.lang.Class<?> clazz)` Create a `Request` that, when processed, will run all the tests in a class.
    `static Request` | `classes(java.lang.Class<?>... classes)` Create a `Request` that, when processed, will run all the tests in a set of classes with the default `Computer`.
    `static Request` | `classes(Computer computer, java.lang.Class<?>... classes)` Create a `Request` that, when processed, will run all the tests in a set of classes.
    `static Request` | `classWithoutSuiteMethod(java.lang.Class<?> clazz)` Create a `Request` that, when processed, will run all the tests in a class.
    `static Request` | `errorReport(java.lang.Class<?> klass, java.lang.Throwable cause)` Creates a `Request` that, when processed, will report an error for the given test class with the given cause.
    `Request` | `filterWith(Description desiredDescription)` Returns a Request that only runs contains tests whose `Description` equals `desiredDescription`
    `Request` | `filterWith(Filter filter)` Returns a Request that only contains those tests that should run when `filter` is applied
    `abstract Runner` | `getRunner()` Returns a `Runner` for this Request
    `static Request` | `method(java.lang.Class<?> clazz, java.lang.String methodName)` Create a `Request` that, when processed, will run a single test.
    `static Request` | `runner(Runner runner)`
    `Request` | `sortWith(java.util.Comparator<Description> comparator)` Returns a Request whose Tests can be run in a certain order, defined by `comparator`

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

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

- - ### Constructor Detail

    - #### Request

          public Request()

  - ### Method Detail

    - #### method

          public static Request method(java.lang.Class<?> clazz,
                       java.lang.String methodName)

      Create a `Request` that, when processed, will run a single test. This is done by filtering out all other tests. This method is used to support rerunning single tests.
      Parameters:
        `clazz` - the class of the test
        `methodName` - the name of the test
      Returns:
        a `Request` that will cause a single test be run

    - #### aClass

          public static Request aClass(java.lang.Class<?> clazz)

      Create a `Request` that, when processed, will run all the tests in a class. The odd name is necessary because `class` is a reserved word.
      Parameters:
        `clazz` - the class containing the tests
      Returns:
        a `Request` that will cause all tests in the class to be run

    - #### classWithoutSuiteMethod

          public static Request classWithoutSuiteMethod(java.lang.Class<?> clazz)

      Create a `Request` that, when processed, will run all the tests in a class. If the class has a suite() method, it will be ignored.
      Parameters:
        `clazz` - the class containing the tests
      Returns:
        a `Request` that will cause all tests in the class to be run

    - #### classes

          public static Request classes(Computer computer,
                        java.lang.Class<?>... classes)

      Create a `Request` that, when processed, will run all the tests in a set of classes.
      Parameters:
        `computer` - Helps construct Runners from classes
        `classes` - the classes containing the tests
      Returns:
        a `Request` that will cause all tests in the classes to be run

    - #### classes

          public static Request classes(java.lang.Class<?>... classes)

      Create a `Request` that, when processed, will run all the tests in a set of classes with the default `Computer`.
      Parameters:
        `classes` - the classes containing the tests
      Returns:
        a `Request` that will cause all tests in the classes to be run

    - #### errorReport

          public static Request errorReport(java.lang.Class<?> klass,
                            java.lang.Throwable cause)

      Creates a `Request` that, when processed, will report an error for the given test class with the given cause.

    - #### runner

          public static Request runner(Runner runner)

      Parameters:
        `runner` - the runner to return
      Returns:
        a `Request` that will run the given runner when invoked

    - #### getRunner

          public abstract Runner getRunner()

      Returns a `Runner` for this Request
      Returns:
        corresponding `Runner` for this Request

    - #### filterWith

          public Request filterWith(Filter filter)

      Returns a Request that only contains those tests that should run when `filter` is applied
      Parameters:
        `filter` - The `Filter` to apply to this Request
      Returns:
        the filtered Request

    - #### filterWith

          public Request filterWith(Description desiredDescription)

      Returns a Request that only runs contains tests whose `Description` equals `desiredDescription`
      Parameters:
        `desiredDescription` - `Description` of those tests that should be run
      Returns:
        the filtered Request

    - #### sortWith

          public Request sortWith(java.util.Comparator<Description> comparator)

      Returns a Request whose Tests can be run in a certain order, defined by `comparator`

      For example, here is code to run a test suite in alphabetical order:

           private static Comparator<Description> forward() {
           return new Comparator<Description>() {
           public int compare(Description o1, Description o2) {
           return o1.getDisplayName().compareTo(o2.getDisplayName());
           }
           };
           }

           public static main() {
           new JUnitCore().run(Request.aClass(AllTests.class).sortWith(forward()));
           }

      Parameters:
        `comparator` - definition of the order of the tests in this Request
      Returns:
        a Request with ordered Tests