Package: org.gradle.tooling

## [Java] Interface TestLauncher

- org.gradle.tooling.LongRunningOperation

- All Superinterfaces:
    ConfigurableLauncher, LongRunningOperation

  A `TestLauncher` allows you to execute tests in a Gradle build.

  Since:
    2.6

- - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `void` | `run()` Executes the tests, blocking until complete.
    `void` | `run(ResultHandler<? super Void> handler)` Starts executing the tests.
    `TestLauncher` | `withJvmTestClasses(String... testClasses)` Adds tests to be executed declared by class name.
    `TestLauncher` | `withJvmTestClasses(Iterable<String> testClasses)` Adds tests to be executed declared by class name.
    `TestLauncher` | `withJvmTestMethods(String testClass, String... methods)` Adds tests to be executed declared by class and method name.
    `TestLauncher` | `withJvmTestMethods(String testClass, Iterable<String> methods)` Adds tests to be executed declared by class and methods name.
    `TestLauncher` | `withTests(TestOperationDescriptor... descriptors)` Adds tests to be executed by passing test descriptors received from a previous Gradle Run.
    `TestLauncher` | `withTests(Iterable<? extends TestOperationDescriptor> descriptors)` Adds tests to be executed by passing test descriptors received from a previous Gradle Run.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `interface ConfigurableLauncher` | `addProgressListener, addProgressListener, addProgressListener, addProgressListener, setColorOutput, setJavaHome, setJvmArguments, setJvmArguments, setStandardError, setStandardInput, setStandardOutput, withArguments, withArguments, withCancellationToken`
    `interface LongRunningOperation` | `addProgressListener, addProgressListener, addProgressListener, addProgressListener, setColorOutput, setJavaHome, setJvmArguments, setJvmArguments, setStandardError, setStandardInput, setStandardOutput, withArguments, withArguments, withCancellationToken`

- - ### Method Detail

    - #### public void run()

      Executes the tests, blocking until complete.

      throws:
        TestExecutionException when one or more tests fail, or no tests for execution declared or no matching tests can be found.
      throws:
        UnsupportedVersionException When the target Gradle version does not support test execution.
      throws:
        org.gradle.tooling.exceptions.UnsupportedBuildArgumentException When there is a problem with build arguments provided by withArguments(String...).
      throws:
        org.gradle.tooling.exceptions.UnsupportedOperationConfigurationException When the target Gradle version does not support some requested configuration option.
      throws:
        BuildException On some failure while executing the tests in the Gradle build.
      throws:
        BuildCancelledException When the operation was cancelled before it completed successfully.
      throws:
        GradleConnectionException On some other failure using the connection.
      throws:
        IllegalStateException When the connection has been closed or is closing.
      Since:
        2.6

    - #### public void run(ResultHandler<? super Void> handler)

      Starts executing the tests. This method returns immediately, and the result is later passed to the given handler.

      If the operation fails, the handler's ResultHandler.onFailure method is called with the appropriate exception. See run() for a description of the various exceptions that the operation may fail with.

      throws:
        IllegalStateException When the connection has been closed or is closing.
      Parameters:
        `handler` - The handler to supply the result to.
      Since:
        2.6

    - #### public TestLauncher withJvmTestClasses(String... testClasses)

      Adds tests to be executed declared by class name.

      Parameters:
        `testClasses` - The class names of the tests to be executed.
      Returns:
        this
      Since:
        2.6

    - #### public TestLauncher withJvmTestClasses(Iterable<String> testClasses)

      Adds tests to be executed declared by class name.

      Parameters:
        `testClasses` - The class names of the tests to be executed.
      Returns:
        this
      Since:
        2.6

    - #### public TestLauncher withJvmTestMethods(String testClass, String... methods)

      Adds tests to be executed declared by class and method name.

      Parameters:
        `testClass` - The name of the class containing the methods to execute.
        `methods` - The names of the test methods to be executed.
      Returns:
        this
      Since:
        2.7

    - #### public TestLauncher withJvmTestMethods(String testClass, Iterable<String> methods)

      Adds tests to be executed declared by class and methods name.

      Parameters:
        `testClass` - The name of the class containing the methods to execute.
        `methods` - The names of the test methods to be executed.
      Returns:
        this
      Since:
        2.7

    - #### public TestLauncher withTests(TestOperationDescriptor... descriptors)

      Adds tests to be executed by passing test descriptors received from a previous Gradle Run.

      Parameters:
        `descriptors` - The OperationDescriptor defining one or more tests.
      Returns:
        this
      Since:
        2.6

    - #### public TestLauncher withTests(Iterable<? extends TestOperationDescriptor> descriptors)

      Adds tests to be executed by passing test descriptors received from a previous Gradle Run.

      Parameters:
        `descriptors` - The OperationDescriptor defining one or more tests.
      Returns:
        this
      Since:
        2.6