Package 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

Modifier and Type
Method
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 Details

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