abstract class GradleRunner
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(File)
} method. It is a requirement that a project directory be set.
The #withArguments(String...)
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.
Please see the Gradle TestKit User Guide chapter for more information.
Since
2.6
GradleRunner()
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 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 The The GradleRunner instances are not thread safe and cannot be used concurrently. However, multiple instances are able to be used concurrently. Please see the Gradle TestKit User Guide chapter for more information. |
abstract fun build(): BuildResult
Executes a build, expecting it to complete without failure. |
|
abstract fun buildAndFail(): BuildResult
Executes a build, expecting it to complete with failure. |
|
open static fun create(): GradleRunner
Creates a new Gradle runner. The runner requires a Gradle distribution (and therefore a specific version of Gradle) in order to execute builds. This method will find a Gradle distribution, based on the filesystem location of this class. That is, it is expected that this class is loaded from a Gradle distribution. When using the runner as part of tests being executed by Gradle (i.e. a build using the When using the runner as part of tests being executed by an IDE, this means that the same distribution of Gradle that was used when importing the project will be used. |
|
abstract fun forwardOutput(): GradleRunner
Forwards the output of executed builds to the The output of the build is always available via This method does not separate the standard output and error output. The two streams will be merged as they typically are when using Gradle from a command line interface. If you require separation of the streams, you can use Calling this method will negate the effect of previously calling |
|
abstract fun forwardStdError(writer: Writer): GradleRunner
Configures the runner to forward standard error output from builds to the given writer. The output of the build is always available via Calling this method will negate the effect of previously calling The given writer will not be closed by the runner. |
|
abstract fun forwardStdOutput(writer: Writer): GradleRunner
Configures the runner to forward standard output from builds to the given writer. The output of the build is always available via Calling this method will negate the effect of previously calling The given writer will not be closed by the runner. When executing builds with Gradle versions earlier than 2.9 in debug mode, any output produced by the build that was written directly to |
|
abstract fun getArguments(): MutableList<String>
The build arguments. Effectively, the command line arguments to Gradle. This includes all tasks, flags, properties etc. The returned list is immutable. |
|
abstract fun getPluginClasspath(): MutableList<out File>
The injected plugin classpath for the build. The returned list is immutable. Returns an empty list if no classpath was provided with |
|
abstract fun getProjectDir(): File
The directory that the build will be executed in. This is analogous to the current directory when executing Gradle from the command line. |
|
abstract fun isDebug(): Boolean
Indicates whether the build should be executed “in process” so that it is debuggable. If debug support is not enabled, the build will be executed in an entirely separate process. This means that any debugger that is attached to the test execution process will not be attached to the build process. When debug support is enabled, the build is executed in the same process that is using the Gradle Runner, allowing the build to be debugged. Debug support is off (i.e. |
|
abstract fun withArguments(arguments: MutableList<String>): GradleRunner abstract fun withArguments(vararg arguments: String): GradleRunner
Sets the build arguments. |
|
abstract fun withDebug(flag: Boolean): GradleRunner
Sets whether debugging support is enabled. |
|
abstract fun withGradleDistribution(distribution: URI): GradleRunner
Configures the runner to execute the build using the distribution of Gradle specified. The given URI must point to a valid Gradle distribution ZIP file. This method is typically used as an alternative to Unless previously downloaded, this method will cause the Gradle runtime at the given URI to be downloaded. The download will be cached beneath the Gradle User Home directory, the location of which is determined by the following in order of precedence:
If neither are present, |
|
abstract fun withGradleInstallation(installation: File): GradleRunner
Configures the runner to execute the build using the installation of Gradle specified. The given file must be a directory containing a valid Gradle installation. Alternatively, you may use |
|
abstract fun withGradleVersion(versionNumber: String): GradleRunner
Configures the runner to execute the build with the version of Gradle specified. Unless previously downloaded, this method will cause the Gradle runtime for the version specified to be downloaded over the Internet from Gradle's distribution servers. The download will be cached beneath the Gradle User Home directory, the location of which is determined by the following in order of precedence:
If neither are present, Alternatively, you may use To use a non standard Gradle runtime, or to obtain the runtime from an alternative location, use |
|
abstract fun withPluginClasspath(): GradleRunner
Sets the plugin classpath based on the Gradle plugin development plugin conventions. The 'java-gradle-plugin' generates a file describing the plugin under test and makes it available to the test runtime. This method configures the runner to use this file. Please consult the Gradle documentation of this plugin for more information. This method looks for a file named Plugins from classpath are able to be resolved using the Calling this method will replace any previous classpath specified via Note: this method will cause an InvalidRunnerConfigurationException to be emitted when the build is executed, if the version of Gradle executing the build (i.e. not the version of the runner) is earlier than Gradle 2.8 as those versions do not support this feature. Please consult the TestKit Gradle User Guide chapter alternative strategies that can be used for older Gradle versions. abstract fun withPluginClasspath(classpath: MutableIterable<File>): GradleRunner
Sets the injected plugin classpath for the build. Plugins from the given classpath are able to be resolved using the Note: this method will cause an InvalidRunnerConfigurationException to be emitted when the build is executed, if the version of Gradle executing the build (i.e. not the version of the runner) is earlier than Gradle 2.8 as those versions do not support this feature. Please consult the TestKit Gradle User Guide chapter alternative strategies that can be used for older Gradle versions. |
|
abstract fun withProjectDir(projectDir: File): GradleRunner
Sets the directory that the Gradle will be executed in. This is typically set to the root project of the build under test. A project directory must be set. This method must be called before All builds executed with the runner effectively do not search parent directories for a |
|
abstract fun withTestKitDir(testKitDir: File): GradleRunner
Sets the directory to use for TestKit's working storage needs. This directory is used internally to store various files required by the runner. If no explicit Gradle user home is specified via the build arguments (i.e. the If no value has been specified when the build is initiated, a directory unique to the current operating system user will be created and used within the JVM's temporary directory as advertised by the You may wish to specify a location that is within your project and regularly cleaned, such as the project's build directory. The actual contents of this directory are an internal implementation detail and may change at any time. |