Package org.gradle.testkit.runner

# Class GradleRunner

java.lang.Object
org.gradle.testkit.runner.GradleRunner

public abstract class GradleRunner extends Object
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.

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(String...)`.

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

Since:
  2.6

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GradleRunner()`

- ## Method Summary

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

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### GradleRunner

    public GradleRunner()

- ## Method Details

  - ### create

    public static GradleRunner create()
    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.

    Returns:
      a new Gradle runner

  - ### withGradleVersion

    public abstract GradleRunner withGradleVersion(String versionNumber)
    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:

    1. The system property `"gradle.user.home"`
    2. The environment variable `"GRADLE_USER_HOME"`

    If neither are present, `"~/.gradle"` will be used, where `"~"` is the value advertised by the JVM's `"user.dir"` system property. The system property and environment variable are read in the process using the runner, not the build process.

    Alternatively, you may use `withGradleInstallation(File)` to use an installation already on the filesystem.

    To use a non standard Gradle runtime, or to obtain the runtime from an alternative location, use `withGradleDistribution(URI)`.

    Parameters:
      `versionNumber` - the version number (e.g. "2.9")
    Returns:
      this
    Since:
      2.9
    See Also:
      - `withGradleInstallation(File)`
      - `withGradleDistribution(URI)`

  - ### withGradleInstallation

    public abstract GradleRunner withGradleInstallation(File installation)
    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 `withGradleVersion(String)` to use an automatically installed Gradle version.

    Parameters:
      `installation` - a valid Gradle installation
    Returns:
      this
    Since:
      2.9
    See Also:
      - `withGradleVersion(String)`
      - `withGradleDistribution(URI)`

  - ### withGradleDistribution

    public abstract GradleRunner withGradleDistribution(URI distribution)
    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 `withGradleVersion(String)`, where it is preferable to obtain the Gradle runtime from "local" servers.

    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:

    1. The system property `"gradle.user.home"`
    2. The environment variable `"GRADLE_USER_HOME"`

    If neither are present, `"~/.gradle"` will be used, where `"~"` is the value advertised by the JVM's `"user.dir"` system property. The system property and environment variable are read in the process using the runner, not the build process.

    Parameters:
      `distribution` - a URI pointing at a valid Gradle distribution zip file
    Returns:
      this
    Since:
      2.9
    See Also:
      - `withGradleVersion(String)`
      - `withGradleInstallation(File)`

  - ### withTestKitDir

    public abstract GradleRunner withTestKitDir(File testKitDir)
    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 `-g «dir»` option}), this directory will also be used for the Gradle user home for the test build.

    If no value has been specified when the build is initiated, a directory will be created within a temporary directory.

    - When executed from a Gradle Test task, the Test task's temporary directory is used (see `Task.getTemporaryDir()`).
    - When executed from somewhere else, the system's temporary directory is used (based on `java.io.tmpdir`).

    This directory is not deleted by the runner after the test build.

    You may wish to specify a location that is within your project and regularly cleaned, such as the project's build directory.

    It can be set using the system property `org.gradle.testkit.dir` for the test process,

    The actual contents of this directory are an internal implementation detail and may change at any time.

    Parameters:
      `testKitDir` - the TestKit directory
    Returns:
      `this`
    Since:
      2.7

  - ### getProjectDir

    public abstract File getProjectDir()
    The directory that the build will be executed in.

    This is analogous to the current directory when executing Gradle from the command line.

    Returns:
      the directory to execute the build in

  - ### withProjectDir

    public abstract GradleRunner withProjectDir(File projectDir)
    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 `build()` or `buildAndFail()`.

    All builds executed with the runner effectively do not search parent directories for a `settings.gradle` file. 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).

    Parameters:
      `projectDir` - the project directory
    Returns:
      `this`
    See Also:
      - `getProjectDir()`

  - ### getArguments

    public abstract List<String> getArguments()
    The build arguments.

    Effectively, the command line arguments to Gradle. This includes all tasks, flags, properties etc.

    The returned list is immutable.

    Returns:
      the build arguments

  - ### withArguments

    public abstract GradleRunner withArguments(List<String> arguments)
    Sets the build arguments.
    Parameters:
      `arguments` - the build arguments
    Returns:
      this
    See Also:
      - `getArguments()`

  - ### withArguments

    public abstract GradleRunner withArguments(String... arguments)
    Sets the build arguments.
    Parameters:
      `arguments` - the build arguments
    Returns:
      this
    See Also:
      - `getArguments()`

  - ### getPluginClasspath

    public abstract List<? extends File> getPluginClasspath()
    The injected plugin classpath for the build.

    The returned list is immutable. Returns an empty list if no classpath was provided with `withPluginClasspath(Iterable)`.

    Returns:
      the classpath of plugins to make available to the build under test
    Since:
      2.8

  - ### withPluginClasspath

    public abstract GradleRunner withPluginClasspath() throws InvalidPluginMetadataException
    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 `plugin-under-test-metadata.properties` on the runtime classpath, and uses the `implementation-classpath` as the classpath, which is expected to a `File.pathSeparatorChar` joined string. If the plugin metadata file cannot be resolved an `InvalidPluginMetadataException` is thrown.

    Plugins from classpath are able to be resolved using the `plugins { }` syntax in the build under test. Please consult the TestKit Gradle User Manual chapter for more information and usage examples.

    Calling this method will replace any previous classpath specified via `withPluginClasspath(Iterable)` and vice versa.

    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 Manual chapter alternative strategies that can be used for older Gradle versions.

    Returns:
      this
    Throws:
      `InvalidPluginMetadataException`
    Since:
      2.13
    See Also:
      - `withPluginClasspath(Iterable)`
      - `getPluginClasspath()`

  - ### withPluginClasspath

    public abstract GradleRunner withPluginClasspath(Iterable<? extends File> classpath)
    Sets the injected plugin classpath for the build.

    Plugins from the given classpath are able to be resolved using the `plugins { }` syntax in the build under test. Please consult the TestKit Gradle User Manual chapter for more information and usage examples.

    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 Manual chapter alternative strategies that can be used for older Gradle versions.

    Parameters:
      `classpath` - the classpath of plugins to make available to the build under test
    Returns:
      this
    Since:
      2.8
    See Also:
      - `getPluginClasspath()`

  - ### isDebug

    public abstract boolean isDebug()
    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. `false`) by default. It can be enabled by setting the system property `org.gradle.testkit.debug` to `true` for the test process, or by using the `withDebug(boolean)` method.

    When `withEnvironment(Map)` is specified, running with debug is not allowed. Debug mode runs "in process" and we need to fork a separate process to pass environment variables.

    Returns:
      whether the build should be executed in the same process
    Since:
      2.9

  - ### withDebug

    public abstract GradleRunner withDebug(boolean flag)
    Sets whether debugging support is enabled.
    Parameters:
      `flag` - the debug flag
    Returns:
      this
    Since:
      2.9
    See Also:
      - `isDebug()`

  - ### getEnvironment

    @Nullable public abstract Map<String,String> getEnvironment()
    Environment variables for the build. `null` is valid and indicates the build will use the system environment.
    Returns:
      environment variables
    Since:
      5.2

  - ### withEnvironment

    public abstract GradleRunner withEnvironment(@Nullable Map<String,String> environmentVariables)
    Sets the environment variables for the build. `null` is permitted and will make the build use the system environment.

    When environment is specified, running with `isDebug()` is not allowed. Debug mode runs in-process and TestKit must fork a separate process to pass environment variables.

    Parameters:
      `environmentVariables` - the variables to use, `null` is allowed.
    Returns:
      this
    Since:
      5.2

  - ### forwardStdOutput

    public abstract GradleRunner forwardStdOutput(Writer writer)
    Configures the runner to forward standard output from builds to the given writer.

    The output of the build is always available via `BuildResult.getOutput()`. This method can be used to additionally capture the output.

    Calling this method will negate the effect of previously calling `forwardOutput()`.

    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 `System.out` or `System.err` will not be represented in `BuildResult.getOutput()`. This is due to a defect that was fixed in Gradle 2.9.

    Parameters:
      `writer` - the writer that build standard output should be forwarded to
    Returns:
      this
    Since:
      2.9
    See Also:
      - `forwardOutput()`
      - `forwardStdError(Writer)`

  - ### forwardStdError

    public abstract GradleRunner forwardStdError(Writer writer)
    Configures the runner to forward standard error output from builds to the given writer.

    The output of the build is always available via `BuildResult.getOutput()`. This method can be used to additionally capture the error output.

    Calling this method will negate the effect of previously calling `forwardOutput()`.

    The given writer will not be closed by the runner.

    Parameters:
      `writer` - the writer that build standard error output should be forwarded to
    Returns:
      this
    Since:
      2.9
    See Also:
      - `forwardOutput()`
      - `forwardStdOutput(Writer)`

  - ### forwardOutput

    public abstract GradleRunner forwardOutput()
    Forwards the output of executed builds to the `System.out` stream.

    The output of the build is always available via `BuildResult.getOutput()`. This method can be used to additionally forward the output to `System.out` of the process using the runner.

    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 `forwardStdOutput(Writer)` and `forwardStdError(Writer)` directly.

    Calling this method will negate the effect of previously calling `forwardStdOutput(Writer)` and/or `forwardStdError(Writer)`.

    Returns:
      this
    Since:
      2.9
    See Also:
      - `forwardStdOutput(Writer)`
      - `forwardStdError(Writer)`

  - ### build

    public abstract BuildResult build() throws InvalidRunnerConfigurationException, UnexpectedBuildFailure
    Executes a build, expecting it to complete without failure.
    Returns:
      the build result
    Throws:
      `InvalidRunnerConfigurationException` - if the configuration of this runner is invalid (e.g. project directory not set)
      `UnexpectedBuildFailure` - if the build does not succeed

  - ### buildAndFail

    public abstract BuildResult buildAndFail() throws InvalidRunnerConfigurationException, UnexpectedBuildSuccess
    Executes a build, expecting it to complete with failure.
    Returns:
      the build result
    Throws:
      `InvalidRunnerConfigurationException` - if the configuration of this runner is invalid (e.g. project directory not set)
      `UnexpectedBuildSuccess` - if the build succeeds

  - ### run

    @Incubating public abstract BuildResult run() throws InvalidRunnerConfigurationException
    Executes a build, without expecting a particular outcome. The outcome should then be tested by inspecting the returned `BuildResult`.
    Returns:
      the build result
    Throws:
      `InvalidRunnerConfigurationException` - if the configuration of this runner is invalid (e.g. project directory not set)
    Since:
      8.0