org.gradle.testkit.runner

## Class GradleRunner

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

-     @Incubating
      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.

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

  Since:
    2.6

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `GradleRunner()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and 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 List<String>` | `getArguments()` The build arguments.
    `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 GradleRunner` | `withArguments(List<String> arguments)` Sets the build arguments.
    `abstract GradleRunner` | `withArguments(String... arguments)` Sets the build arguments.
    `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 Test Kit's working storage needs.

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

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

- - ### Constructor Detail

    - #### GradleRunner

          public GradleRunner()

  - ### Method Detail

    - #### 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

    - #### withTestKitDir

          public abstract GradleRunner withTestKitDir(File testKitDir)

      Sets the directory to use for Test Kit'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 unique to the current operating system user will be created and used within the JVM's temporary directory as advertised by the `java.io.tmpdir` system property. 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.

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

      Parameters:
        `testKitDir` - the test kit 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 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).

      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(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 “Test Kit” Gradle User Guide chapter for more information and usage examples.

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

    - #### 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