# TestLauncher

interface TestLauncher : ConfigurableLauncher<TestLauncher> (source)

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

If the target Gradle version is >=6.8 then you can use `TestLauncher` to execute tests from included builds. Test operation descriptors from included builds work out-of-the-box. You can target tasks from included builds by specifying the task identity path (i.e. `':included-build-name:subproject-name:taskName'`).

However, you cannot use the methods with included builds that don't specify the target test tasks (e.g. `withJvmTestClasses()` and `withJvmTestMethods()`). Those methods configure all test tasks in the root build only.

#### Since

2.6

## Functions

addArguments
Link copied to clipboard
abstract fun addArguments(arguments: Iterable<String>): T
abstract fun addArguments(arguments: Array<String>): T
abstract fun addArguments(arguments: Iterable<String>): LongRunningOperation
abstract fun addArguments(arguments: Array<String>): LongRunningOperation
Appends new command line arguments to the existing list.
addJvmArguments
Link copied to clipboard
abstract fun addJvmArguments(jvmArguments: Iterable<String>): T
abstract fun addJvmArguments(jvmArguments: Array<String>): T
abstract fun addJvmArguments(jvmArguments: Iterable<String>): LongRunningOperation
abstract fun addJvmArguments(jvmArguments: Array<String>): LongRunningOperation
Appends Java VM arguments to the existing list.
addProgressListener
Link copied to clipboard
abstract fun addProgressListener(listener: ProgressListener): T
abstract fun addProgressListener(listener: ProgressListener): LongRunningOperation
Adds a progress listener which will receive progress events as the operation runs.
abstract fun addProgressListener(listener: ProgressListener): T
abstract fun addProgressListener(listener: ProgressListener): LongRunningOperation
Adds a progress listener which will receive progress events of all types as the operation runs.
abstract fun addProgressListener(listener: ProgressListener, eventTypes: Set<OperationType>): T
abstract fun addProgressListener(listener: ProgressListener, operationTypes: Array<OperationType>): T
abstract fun addProgressListener(listener: ProgressListener, operationTypes: Set<OperationType>): LongRunningOperation
abstract fun addProgressListener(listener: ProgressListener, operationTypes: Array<OperationType>): LongRunningOperation
Adds a progress listener which will receive progress events as the operations of the requested type run.
debugTestsOn
Link copied to clipboard
abstract fun debugTestsOn(port: Int): TestLauncher
Configures test JVM to run in debug mode.
forTasks
Link copied to clipboard
@Incubating
abstract fun forTasks(tasks: Array<String>): TestLauncher
Sets the tasks to be executed.
run
Link copied to clipboard
abstract fun run()
Executes the tests, blocking until complete.
abstract fun run(handler: ResultHandler<in Void>)
Starts executing the tests.
setColorOutput
Link copied to clipboard
abstract fun setColorOutput(colorOutput: Boolean): T
abstract fun setColorOutput(colorOutput: Boolean): LongRunningOperation
Specifies whether to generate colored (ANSI encoded) output for logging.
setEnvironmentVariables
Link copied to clipboard
abstract fun setEnvironmentVariables(envVariables: Map<String, String>): T
abstract fun setEnvironmentVariables(@Nullable envVariables: @Nullable Map<String, String>): LongRunningOperation
Specifies the environment variables to use for this operation.
setJavaHome
Link copied to clipboard
abstract fun setJavaHome(javaHome: File): T
abstract fun setJavaHome(@Nullable javaHome: @Nullable File): LongRunningOperation
Specifies the Java home directory to use for this operation.
setJvmArguments
Link copied to clipboard
abstract fun setJvmArguments(jvmArguments: Iterable<String>): T
abstract fun setJvmArguments(jvmArguments: Array<String>): T
abstract fun setJvmArguments(@Nullable jvmArguments: @Nullable Iterable<String>): LongRunningOperation
abstract fun setJvmArguments(@Nullable jvmArguments: Array<@Nullable String>): LongRunningOperation
Specifies the Java VM arguments to use for this operation.
setStandardError
Link copied to clipboard
abstract fun setStandardError(outputStream: OutputStream): T
Sets the which should receive standard error logging generated while running the operation.
abstract fun setStandardError(outputStream: OutputStream): LongRunningOperation
Sets the OutputStream which should receive standard error logging generated while running the operation.
setStandardInput
Link copied to clipboard
abstract fun setStandardInput(inputStream: InputStream): T
Sets the that will be used as standard input for this operation.
abstract fun setStandardInput(inputStream: InputStream): LongRunningOperation
Sets the java.io.InputStream that will be used as standard input for this operation.
setStandardOutput
Link copied to clipboard
abstract fun setStandardOutput(outputStream: OutputStream): T
Sets the which should receive standard output logging generated while running the operation.
abstract fun setStandardOutput(outputStream: OutputStream): LongRunningOperation
Sets the java.io.OutputStream which should receive standard output logging generated while running the operation.
withArguments
Link copied to clipboard
abstract fun withArguments(arguments: Iterable<String>): T
abstract fun withArguments(arguments: Array<String>): T
abstract fun withArguments(@Nullable arguments: @Nullable Iterable<String>): LongRunningOperation
abstract fun withArguments(@Nullable arguments: Array<@Nullable String>): LongRunningOperation
Specify the command line build arguments.
withCancellationToken
Link copied to clipboard
abstract fun withCancellationToken(cancellationToken: CancellationToken): T
abstract fun withCancellationToken(cancellationToken: CancellationToken): LongRunningOperation
Sets the cancellation token to use to cancel the operation if required.
withDetailedFailure
Link copied to clipboard
abstract fun withDetailedFailure(): T
Adds more detailed information about the build failure to the that provides insights into the reasons for the failure, making it easier to diagnose and fix issues.
@Incubating
abstract fun withDetailedFailure(): LongRunningOperation
Adds more detailed information about the build failure to the GradleConnectionException that provides insights into the reasons for the failure, making it easier to diagnose and fix issues.
withJvmTestClasses
Link copied to clipboard
abstract fun withJvmTestClasses(testClasses: Iterable<String>): TestLauncher
abstract fun withJvmTestClasses(testClasses: Array<String>): TestLauncher
Adds tests to be executed declared by class name.
withJvmTestMethods
Link copied to clipboard
abstract fun withJvmTestMethods(testClass: String, methods: Iterable<String>): TestLauncher
Adds tests to be executed declared by class and methods name.
abstract fun withJvmTestMethods(testClass: String, methods: Array<String>): TestLauncher
Adds tests to be executed declared by class and method name.
withSystemProperties
Link copied to clipboard
abstract fun withSystemProperties(systemProperties: Map<String, String>): T
@Incubating
abstract fun withSystemProperties(systemProperties: Map<String, String>): LongRunningOperation
Sets system properties to pass to the build.
withTaskAndTestClasses
Link copied to clipboard
abstract fun withTaskAndTestClasses(task: String, testClasses: Iterable<String>): TestLauncher
Adds tests to be executed declared by the container task and the class name.
withTaskAndTestMethods
Link copied to clipboard
abstract fun withTaskAndTestMethods(task: String, testClass: String, methods: Iterable<String>): TestLauncher
Adds tests to be executed declared by the container task, class and method name.
withTests
Link copied to clipboard
abstract fun withTests(descriptors: Iterable<out TestOperationDescriptor>): TestLauncher
abstract fun withTests(descriptors: Array<TestOperationDescriptor>): TestLauncher
Adds tests to be executed by passing test descriptors received from a previous Gradle Run.
withTestsFor
Link copied to clipboard
@Incubating
abstract fun withTestsFor(testSpec: Action<TestSpecs>): TestLauncher
Adds tests to be executed declared using a fine-grained test selection API.