api / org.gradle.testkit.runner

Package org.gradle.testkit.runner



interface BuildResult

The result of executing a build, via the GradleRunner.


interface BuildTask

A task that was executed when running a specific build.


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.


class TaskOutcome

The outcome of executing a task during a build.



open class InvalidPluginMetadataException : IllegalStateException

Thrown when the plugin under test metadata cannot be read.


open class InvalidRunnerConfigurationException : IllegalStateException

Thrown when a build cannot be executed due to the runner being in an invalid state.


open class UnexpectedBuildFailure : UnexpectedBuildResultException

Thrown when executing a build that was expected to succeed, but failed.


abstract class UnexpectedBuildResultException : RuntimeException

Base class for UnexpectedBuildFailure and UnexpectedBuildSuccess.


open class UnexpectedBuildSuccess : UnexpectedBuildResultException

Thrown when executing a build that was expected to fail, but succeeded.


open class UnsupportedFeatureException : RuntimeException

Thrown when a build was executed with a target Gradle version that does not support a specific feature.