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.
Type | Name and description |
---|---|
BuildResult |
build() Executes a build, expecting it to complete without failure. |
BuildResult |
buildAndFail() Executes a build, expecting it to complete with failure. |
static GradleRunner |
create() Creates a new Gradle runner. |
List<String> |
getArguments() The build arguments. |
File |
getProjectDir() The directory that the build will be executed in. |
GradleRunner |
withArguments(List<String> arguments) Sets the build arguments. |
GradleRunner |
withArguments(String... arguments) Sets the build arguments. |
GradleRunner |
withProjectDir(File projectDir) Sets the directory that the Gradle will be executed in. |
Executes a build, expecting it to complete without failure.
Executes a build, expecting it to complete with failure.
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 gradleTestKit()
dependency),
this means that the same distribution of Gradle that is executing the tests will be used by runner returned by this method.
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.
The build arguments.
Effectively, the command line arguments to Gradle. This includes all tasks, flags, properties etc. The returned list is an unmodifiable view of items.
The directory that the build will be executed in.
This is analogous to the current directory when executing Gradle from the command line.
Sets the build arguments.
arguments
- the build argumentsSets the build arguments.
arguments
- the build argumentsSets 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 build() or buildAndFail().
All builds executed with the runner effectively implicitly add the --no-search-upwards
argument.
This suppresses Gradle's default behaviour of searching upwards through the file system in order to find the root of the current project tree.
This default behaviour is often utilised when focusing on a particular build within a multi-project build.
This behaviour is suppressed due to test builds being executed potentially being created within a “real build”
(e.g. under the /build
directory of the plugin's project directory).
projectDir
- the project directorythis