gradle
8.6

# GradleRunner

abstract class GradleRunner(source)

Executes a Gradle build, allowing inspection of the outcome.

A Gradle runner can be used to functionally test build logic, by executing a contrived build. Assertions can then be made on the outcome of the build, such as the state of files created by the build, or what tasks were actually executed during the build.

A runner can be created via the create method.

Typically, the test code using the runner will programmatically create a build (e.g. by writing Gradle build files to a temporary space) to execute. The build to execute is effectively specified by the withProjectDir} method. It is a requirement that a project directory be set.

The withArguments method allows the build arguments to be specified, just as they would be on the command line.

The build method can be used to invoke the build when it is expected to succeed, while the buildAndFail method can be used when the build is expected to fail.

GradleRunner instances are not thread safe and cannot be used concurrently. However, multiple instances are able to be used concurrently.

On Windows, Gradle runner disables file system watching for the executed build, since the Windows watchers add a file lock on the root project directory, causing problems when trying to delete it. You can still enable file system watching manually for your test by adding the `--watch-fs` command line argument via withArguments.

Please see the Gradle TestKit User Manual chapter for more information.

## Constructors

GradleRunner
Link copied to clipboard
constructor()

## Functions

build
Link copied to clipboard
abstract fun build(): BuildResult
Executes a build, expecting it to complete without failure.
buildAndFail
Link copied to clipboard
abstract fun buildAndFail(): BuildResult
Executes a build, expecting it to complete with failure.
create
Link copied to clipboard
open fun create(): GradleRunner
Creates a new Gradle runner.
forwardOutput
Link copied to clipboard
abstract fun forwardOutput(): GradleRunner
Forwards the output of executed builds to the System.out stream.
forwardStdError
Link copied to clipboard
abstract fun forwardStdError(writer: Writer): GradleRunner
Configures the runner to forward standard error output from builds to the given writer.
forwardStdOutput
Link copied to clipboard
abstract fun forwardStdOutput(writer: Writer): GradleRunner
Configures the runner to forward standard output from builds to the given writer.
getArguments
Link copied to clipboard
abstract fun getArguments(): List<String>
The build arguments.
getEnvironment
Link copied to clipboard
@Nullable
abstract fun getEnvironment(): Map<String, String>
Environment variables for the build.
getPluginClasspath
Link copied to clipboard
abstract fun getPluginClasspath(): List<out File>
The injected plugin classpath for the build.
getProjectDir
Link copied to clipboard
abstract fun getProjectDir(): File
The directory that the build will be executed in.
isDebug
Link copied to clipboard
abstract fun isDebug(): Boolean
Indicates whether the build should be executed “in process” so that it is debuggable.
run
Link copied to clipboard
@Incubating
abstract fun run(): BuildResult
Executes a build, without expecting a particular outcome.
withArguments
Link copied to clipboard
abstract fun withArguments(arguments: Array<String>): GradleRunner
abstract fun withArguments(arguments: List<String>): GradleRunner
Sets the build arguments.
withDebug
Link copied to clipboard
abstract fun withDebug(flag: Boolean): GradleRunner
Sets whether debugging support is enabled.
withEnvironment
Link copied to clipboard
abstract fun withEnvironment(@Nullable environmentVariables: Map<String, String>): GradleRunner
Sets the environment variables for the build.
withGradleDistribution
Link copied to clipboard
abstract fun withGradleDistribution(distribution: URI): GradleRunner
Configures the runner to execute the build using the distribution of Gradle specified.
withGradleInstallation
Link copied to clipboard
abstract fun withGradleInstallation(installation: File): GradleRunner
Configures the runner to execute the build using the installation of Gradle specified.
withGradleVersion
Link copied to clipboard
abstract fun withGradleVersion(versionNumber: String): GradleRunner
Configures the runner to execute the build with the version of Gradle specified.
withPluginClasspath
Link copied to clipboard
abstract fun withPluginClasspath(): GradleRunner
Sets the plugin classpath based on the Gradle plugin development plugin conventions.
abstract fun withPluginClasspath(classpath: Iterable<out File>): GradleRunner
Sets the injected plugin classpath for the build.
withProjectDir
Link copied to clipboard
abstract fun withProjectDir(projectDir: File): GradleRunner
Sets the directory that the Gradle will be executed in.
withTestKitDir
Link copied to clipboard
abstract fun withTestKitDir(testKitDir: File): GradleRunner
Sets the directory to use for TestKit's working storage needs.