org.gradle.tooling

## Interface TestLauncher

- All Superinterfaces:
    ConfigurableLauncher<TestLauncher>, LongRunningOperation

      @Incubating
      public interface TestLauncher
      extends ConfigurableLauncher<TestLauncher>

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

- - ### Method Summary

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

    - ### Methods inherited from interface org.gradle.tooling.ConfigurableLauncher

      `addProgressListener, addProgressListener, addProgressListener, addProgressListener, setColorOutput, setEnvironmentVariables, setJavaHome, setJvmArguments, setJvmArguments, setStandardError, setStandardInput, setStandardOutput, withArguments, withArguments, withCancellationToken`

- - ### Method Detail

    - #### withTests

          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

    - #### withTests

          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

    - #### withJvmTestClasses

          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

    - #### withJvmTestClasses

          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

    - #### withJvmTestMethods

          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

    - #### withJvmTestMethods

          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

    - #### run

          void run()
                   throws TestExecutionException

      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.
        `UnsupportedVersionException` - When the target Gradle version does not support test execution.
        `UnsupportedBuildArgumentException` - When there is a problem with build arguments provided by `ConfigurableLauncher.withArguments(String...)`.
        `UnsupportedOperationConfigurationException` - When the target Gradle version does not support some requested configuration option.
        `BuildException` - On some failure while executing the tests in the Gradle build.
        `BuildCancelledException` - When the operation was cancelled before it completed successfully.
        `GradleConnectionException` - On some other failure using the connection.
        `IllegalStateException` - When the connection has been closed or is closing.
      Since:
        2.6

    - #### run

          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(GradleConnectionException)` method is called with the appropriate exception. See `run()` for a description of the various exceptions that the operation may fail with.

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