dev.gradleplugins.runnerkit

Interface GradleRunner

public interface GradleRunner

Method Summary

Modifier and Type	Method and Description
GradleRunner	afterExecute(java.util.function.Consumer<GradleExecutionContext> action) Adds an action to assert the outcome based on the execution context right after the execution.
GradleRunner	beforeExecute(java.util.function.UnaryOperator<GradleRunner> action) Adds an action to modify the Gradle runner before it is executed.
BuildResult	build() Executes a build, expecting it to complete without failure.
BuildResult	buildAndFail() Executes a build, expecting it to complete with failure.
GradleRunner	configure(java.util.function.UnaryOperator<GradleRunner> action) Configures current runner using the specified operator.
static GradleRunner	create(GradleExecutor executor)
GradleRunner	forwardOutput() Forwards the output of executed builds to the System.out stream.
GradleRunner	forwardStandardError(java.io.Writer writer) Configures the runner to forward standard error output from builds to the given writer.
GradleRunner	forwardStandardOutput(java.io.Writer writer) Configures the runner to forward standard output from builds to the given writer.
default GradleRunner	forwardStdError(java.io.Writer writer) Provided method for migration convenience from Gradle TestKit.
default GradleRunner	forwardStdOutput(java.io.Writer writer) Provided method for migration convenience from Gradle TestKit.
java.util.List<java.lang.String>	getAllArguments() The build arguments.
java.util.List<? extends java.io.File>	getPluginClasspath() The injected plugin classpath for the build.
java.io.File	getWorkingDirectory() The directory that the build will be executed in.
GradleRunner	ignoresMissingSettingsFile() Does not create an empty settings file when it's missing before execution.
GradleRunner	inDirectory(java.io.File workingDirectory) Sets the working directory to use.
GradleRunner	inDirectory(java.nio.file.Path workingDirectory) Sets the working directory to use.
GradleRunner	inDirectory(java.util.function.Supplier<?> workingDirectorySupplier) Sets the working directory to use using the supplier.
GradleRunner	publishBuildScans() Publishes build scans to the public enterprise server for each build ran by this executer.
GradleRunner	requireOwnGradleUserHomeDirectory() Configures a unique Gradle user home directory for the test.
GradleRunner	usingBuildScript(java.io.File buildScript) Uses the given build script by adding "--build-file" argument.
GradleRunner	usingInitScript(java.io.File initScript) Uses the given init script by adding "--init-script" argument.
GradleRunner	usingProjectDirectory(java.io.File projectDirectory) Uses the given project directory by adding the "--project-dir" argument.
GradleRunner	usingSettingsFile(java.io.File settingsFile) Uses the given settings file by adding "--settings-file" argument.
GradleRunner	withArgument(java.lang.String arg) Adds an additional command-line argument to use when executing the build.
GradleRunner	withArguments(java.util.List<java.lang.String> args) Sets the additional command-line arguments to use when executing the build.
default GradleRunner	withArguments(java.lang.String... args) Sets the additional command-line arguments to use when executing the build.
GradleRunner	withBuildCacheEnabled() Activates the build cache.
GradleRunner	withDefaultCharacterEncoding(java.nio.charset.Charset defaultCharacterEncoding) Sets the default character encoding to use.
GradleRunner	withDefaultLocale(java.util.Locale defaultLocale) Sets the default locale to use.
default GradleRunner	withEnvironment(java.util.Map<java.lang.String,java.lang.String> environmentVariables) Sets the environment variables to use when executing the build.
GradleRunner	withEnvironmentVariable(java.lang.String key, java.lang.String value) Adds an additional environment variable to use when executing the build.
GradleRunner	withEnvironmentVariables(java.util.Map<java.lang.String,?> environmentVariables) Sets the environment variables to use when executing the build.
GradleRunner	withEnvironmentVars(java.util.Map<java.lang.String,?> environmentVariables) Deprecated.
GradleRunner	withGradleDistribution(java.net.URI distribution) Configures the runner to execute the build using the distribution of Gradle specified.
GradleRunner	withGradleInstallation(java.io.File installation) Configures the runner to execute the build using the installation of Gradle specified.
GradleRunner	withGradleUserHomeDirectory(java.io.File gradleUserHomeDirectory) Sets the Gradle user home dir.
GradleRunner	withGradleVersion(java.lang.String versionNumber) Configures the runner to execute the build with the version of Gradle specified.
GradleRunner	withoutDeprecationChecks() Disable deprecation warning checks.
GradleRunner	withPluginClasspath() Sets the plugin classpath based on the Gradle plugin development plugin conventions.
GradleRunner	withPluginClasspath(java.lang.Iterable<? extends java.io.File> classpath) Sets the injected plugin classpath for the build.
GradleRunner	withRichConsoleEnabled() Forces the rich console output.
GradleRunner	withStacktraceDisabled() Executes the builds without adding the "--stacktrace" argument.
GradleRunner	withTasks(java.util.List<java.lang.String> tasks) Sets the task names to execute.
default GradleRunner	withTasks(java.lang.String... tasks) Sets the task names to execute.
GradleRunner	withUserHomeDirectory(java.io.File userHomeDirectory) Sets the user's home dir to use when running the build.
GradleRunner	withWelcomeMessageEnabled() Renders the welcome message users see upon first invocation of a Gradle distribution with a given Gradle user home directory.

Method Detail

create

static GradleRunner create(GradleExecutor executor)

withGradleVersion

GradleRunner withGradleVersion(java.lang.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

See Also:

withGradleInstallation(File), withGradleDistribution(URI)

withGradleInstallation

GradleRunner withGradleInstallation(java.io.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

See Also:

withGradleVersion(String), withGradleDistribution(URI)

withGradleDistribution

GradleRunner withGradleDistribution(java.net.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

See Also:

withGradleVersion(String), withGradleInstallation(File)

getPluginClasspath

java.util.List<? extends java.io.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

withPluginClasspath

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

See Also:

withPluginClasspath(Iterable), getPluginClasspath()

withPluginClasspath

GradleRunner withPluginClasspath(java.lang.Iterable<? extends java.io.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

See Also:

getPluginClasspath()

inDirectory

GradleRunner inDirectory(java.io.File workingDirectory)

Sets the working directory to use.

Parameters:

workingDirectory - the working directory to use, must not be null

Returns:

a new GradleRunner instance configured with the specified working directory, never null

inDirectory

GradleRunner inDirectory(java.nio.file.Path workingDirectory)

Sets the working directory to use.

Parameters:

workingDirectory - the working directory to use, must not be null

Returns:

a new GradleRunner instance configured with the specified working directory, never null

inDirectory

GradleRunner inDirectory(java.util.function.Supplier<?> workingDirectorySupplier)

Sets the working directory to use using the supplier.

Parameters:

workingDirectorySupplier - a working directory supplier to use, must not be null

Returns:

a new GradleRunner instance configured with the specified working directory, never null

getWorkingDirectory

java.io.File getWorkingDirectory()
                          throws InvalidRunnerConfigurationException

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

Throws:

InvalidRunnerConfigurationException - if the working directory is not configured

withStacktraceDisabled

GradleRunner withStacktraceDisabled()

Executes the builds without adding the "--stacktrace" argument.

Returns:

a new GradleRunner instance configured without stacktrace, never null.

withBuildCacheEnabled

GradleRunner withBuildCacheEnabled()

Activates the build cache. Defaults to disabled.

Returns:

a GradleRunner instance configured with build cache, never null.

withTasks

default GradleRunner withTasks(java.lang.String... tasks)

Sets the task names to execute. Defaults to an empty list.

Parameters:

tasks - the tasks to execute

Returns:

a new GradleRunner instance with the specified tasks to execute, never null.

withTasks

GradleRunner withTasks(java.util.List<java.lang.String> tasks)

Sets the task names to execute. Defaults to an empty list.

Parameters:

tasks - the tasks to execute

Returns:

a new GradleRunner instance with the specified tasks to execute, never null.

withArguments

default GradleRunner withArguments(java.lang.String... args)

Sets the additional command-line arguments to use when executing the build. Defaults to an empty list.

Parameters:

args - the new arguments to use, the old ones are discarded

Returns:

a GradleRunner instance configured with the specified arguments, never null.

withArguments

GradleRunner withArguments(java.util.List<java.lang.String> args)

Sets the additional command-line arguments to use when executing the build. Defaults to an empty list.

Parameters:

args - the new arguments to use, the old ones are discarded

Returns:

a new GradleRunner instance configured with the specified arguments, never null.

withArgument

GradleRunner withArgument(java.lang.String arg)

Adds an additional command-line argument to use when executing the build.

Parameters:

arg - a new arguments to append to the old ones

Returns:

a new GradleRunner instance configured with the specified argument, never null.

getAllArguments

java.util.List<java.lang.String> getAllArguments()

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

usingSettingsFile

GradleRunner usingSettingsFile(java.io.File settingsFile)

Uses the given settings file by adding "--settings-file" argument.

Parameters:

settingsFile - the settings file to use

Returns:

a new GradleRunner instance configured with the specified settings file, never null.

ignoresMissingSettingsFile

GradleRunner ignoresMissingSettingsFile()

Does not create an empty settings file when it's missing before execution.

Returns:

a new GradleRunner instance configured to ignore default behavior when settings file is missing, never null.

usingBuildScript

GradleRunner usingBuildScript(java.io.File buildScript)

Uses the given build script by adding "--build-file" argument.

Parameters:

buildScript - the build script file to use

Returns:

a new GradleRunner instance configured with the specified build script file, never null.

usingInitScript

GradleRunner usingInitScript(java.io.File initScript)

Uses the given init script by adding "--init-script" argument.

Parameters:

initScript - the init script file to use

Returns:

a new GradleRunner instance configured with the specified init script file, never null.

usingProjectDirectory

GradleRunner usingProjectDirectory(java.io.File projectDirectory)

Uses the given project directory by adding the "--project-dir" argument.

Parameters:

projectDirectory - the project directory to use

Returns:

a new GradleRunner instance configured with the specified project directory, never null.

withoutDeprecationChecks

GradleRunner withoutDeprecationChecks()

Disable deprecation warning checks.

Returns:

a new GradleRunner without deprecation checking enabled, never null..

withDefaultCharacterEncoding

GradleRunner withDefaultCharacterEncoding(java.nio.charset.Charset defaultCharacterEncoding)

Sets the default character encoding to use.

Parameters:

defaultCharacterEncoding - the default character encoding to use

Returns:

a GradleRunner instance configured with the specified character encoding, never null.

withDefaultLocale

GradleRunner withDefaultLocale(java.util.Locale defaultLocale)

Sets the default locale to use.

Parameters:

defaultLocale - the default locale to use

Returns:

a new GradleRunner instance configured with the specified locale, never null.

withWelcomeMessageEnabled

GradleRunner withWelcomeMessageEnabled()

Renders the welcome message users see upon first invocation of a Gradle distribution with a given Gradle user home directory. By default the message is never rendered.

Returns:

a new GradleRunner instance configured with the welcome message on first invocation, never null.

publishBuildScans

GradleRunner publishBuildScans()

Publishes build scans to the public enterprise server for each build ran by this executer. Calling this method implicitly accept the Gradle terms and services.

Returns:

a new GradleRunner instance configured to publish build scans for each builds executed, never null.

withUserHomeDirectory

GradleRunner withUserHomeDirectory(java.io.File userHomeDirectory)

Sets the user's home dir to use when running the build. Implementations are not 100% accurate.

Parameters:

userHomeDirectory - the user home directory to use

Returns:

a new GradleRunner instance configured with the specified user home directory, never null.

withGradleUserHomeDirectory

GradleRunner withGradleUserHomeDirectory(java.io.File gradleUserHomeDirectory)

Sets the Gradle user home dir. Setting to null requests that the executer use the real default Gradle user home dir rather than the default used for testing.

Note: does not affect the daemon base dir.

Parameters:

gradleUserHomeDirectory - the Gradle user home directory to use

Returns:

a new GradleRunner instance configured with the specified Gradle user home directory, never null.

requireOwnGradleUserHomeDirectory

GradleRunner requireOwnGradleUserHomeDirectory()

Configures a unique Gradle user home directory for the test. The Gradle user home directory used will be underneath the getWorkingDirectory() directory.

Note: does not affect the daemon base dir.

Returns:

a new GradleRunner instance configured with a unique Gradle user home directory, neverl null.

withEnvironmentVariables

GradleRunner withEnvironmentVariables(java.util.Map<java.lang.String,?> environmentVariables)

Sets the environment variables to use when executing the build. Defaults to the environment of this process.

Parameters:

environmentVariables - the environment variables to use

Returns:

a new GradleRunner instance configured with the specified environment variables, never null.

withEnvironmentVariable

GradleRunner withEnvironmentVariable(java.lang.String key,
                                     java.lang.String value)

Adds an additional environment variable to use when executing the build.

Parameters:

key - the environment variable key

value - the environment variable value

Returns:

a new GradleRunner instance configured with the specified additional environment variable, never null.

withEnvironmentVars

@Deprecated
GradleRunner withEnvironmentVars(java.util.Map<java.lang.String,?> environmentVariables)

Deprecated.

Sets the environment variables to use when executing the build. Defaults to the environment of this process.

Convenience method to allow migration from, older, Gradle Executer API.

Parameters:

environmentVariables - the environment variables to use

Returns:

a new GradleRunner instance configured with the specified environment variables, never null.

See Also:

withEnvironmentVariables(Map)

withEnvironment

default GradleRunner withEnvironment(java.util.Map<java.lang.String,java.lang.String> environmentVariables)

Sets the environment variables to use when executing the build. Defaults to the environment of this process.

Convenience method to allow migration from Gradle Test Kit API.

Parameters:

environmentVariables - the environment variables to use

Returns:

a new GradleRunner instance configured with the specified environment variables, never null.

withRichConsoleEnabled

GradleRunner withRichConsoleEnabled()

Forces the rich console output.

Returns:

a new GradleRunner instance configured with the rich console enabled, never null.

configure

GradleRunner configure(java.util.function.UnaryOperator<GradleRunner> action)

Configures current runner using the specified operator.

Returns:

a the GradleRunner instance returned by the configuration action, never null.

forwardStandardOutput

GradleRunner forwardStandardOutput(java.io.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.

The given writer will not be closed by the runner.

When executing builds with Gradle versions earlier than 2.9 in debug mode and using a tooling API-based executer, 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

See Also:

forwardStandardError(Writer)

forwardStdOutput

default GradleRunner forwardStdOutput(java.io.Writer writer)

Provided method for migration convenience from Gradle TestKit.

Parameters:

writer - the writer that build standard output should be forwarded to

Returns:

this

See Also:

forwardStandardOutput(Writer)

forwardStandardError

GradleRunner forwardStandardError(java.io.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.

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

See Also:

forwardStandardOutput(Writer)

forwardStdError

default GradleRunner forwardStdError(java.io.Writer writer)

Provided method for migration convenience from Gradle TestKit.

Parameters:

writer - the writer that build standard error output should be forwarded to

Returns:

this

See Also:

forwardStandardError(Writer)

forwardOutput

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 forwardStandardOutput(Writer) and forwardStandardError(Writer) directly.

Calling this method will negate the effect of previously calling forwardStandardOutput(Writer) and/or forwardStandardError(Writer).

Forwarding the output is the process using the runner is the default behavior for all executor. This method is provided for convenience when migrating from Gradle TestKit.

Returns:

this

Since:

2.9

See Also:

forwardStandardOutput(Writer), forwardStandardError(Writer)

beforeExecute

GradleRunner beforeExecute(java.util.function.UnaryOperator<GradleRunner> action)

Adds an action to modify the Gradle runner before it is executed. The modification to the Gradle runner only affects the current run.

Parameters:

action - the action that will configure the runner further before execution.

Returns:

a new GradleRunner configured with the specified additional action, never null.

afterExecute

GradleRunner afterExecute(java.util.function.Consumer<GradleExecutionContext> action)

Adds an action to assert the outcome based on the execution context right after the execution.

Parameters:

action - the action that will assert based on the execution context after execution.

Returns:

a new GradleRunner configured with the specified additional action, never null.

build

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

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