public interface GradleRunner
| 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.
|
static GradleRunner create(GradleExecutor executor)
GradleRunner withGradleVersion(java.lang.String versionNumber)
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:
"gradle.user.home""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).
versionNumber - the version number (e.g. "2.9")withGradleInstallation(File),
withGradleDistribution(URI)GradleRunner withGradleInstallation(java.io.File installation)
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.
installation - a valid Gradle installationwithGradleVersion(String),
withGradleDistribution(URI)GradleRunner withGradleDistribution(java.net.URI distribution)
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:
"gradle.user.home""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.
distribution - a URI pointing at a valid Gradle distribution zip filewithGradleVersion(String),
withGradleInstallation(File)java.util.List<? extends java.io.File> getPluginClasspath()
The returned list is immutable.
Returns an empty list if no classpath was provided with withPluginClasspath(Iterable).
GradleRunner withPluginClasspath() throws InvalidPluginMetadataException
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.
InvalidPluginMetadataExceptionwithPluginClasspath(Iterable),
getPluginClasspath()GradleRunner withPluginClasspath(java.lang.Iterable<? extends java.io.File> classpath)
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.
classpath - the classpath of plugins to make available to the build under testgetPluginClasspath()GradleRunner inDirectory(java.io.File workingDirectory)
workingDirectory - the working directory to use, must not be nullGradleRunner instance configured with the specified working directory, never nullGradleRunner inDirectory(java.nio.file.Path workingDirectory)
workingDirectory - the working directory to use, must not be nullGradleRunner instance configured with the specified working directory, never nullGradleRunner inDirectory(java.util.function.Supplier<?> workingDirectorySupplier)
workingDirectorySupplier - a working directory supplier to use, must not be nullGradleRunner instance configured with the specified working directory, never nulljava.io.File getWorkingDirectory()
throws InvalidRunnerConfigurationException
This is analogous to the current directory when executing Gradle from the command line.
InvalidRunnerConfigurationException - if the working directory is not configuredGradleRunner withStacktraceDisabled()
"--stacktrace" argument.GradleRunner instance configured without stacktrace, never null.GradleRunner withBuildCacheEnabled()
GradleRunner instance configured with build cache, never null.default GradleRunner withTasks(java.lang.String... tasks)
tasks - the tasks to executeGradleRunner instance with the specified tasks to execute, never null.GradleRunner withTasks(java.util.List<java.lang.String> tasks)
tasks - the tasks to executeGradleRunner instance with the specified tasks to execute, never null.default GradleRunner withArguments(java.lang.String... args)
args - the new arguments to use, the old ones are discardedGradleRunner instance configured with the specified arguments, never null.GradleRunner withArguments(java.util.List<java.lang.String> args)
args - the new arguments to use, the old ones are discardedGradleRunner instance configured with the specified arguments, never null.GradleRunner withArgument(java.lang.String arg)
arg - a new arguments to append to the old onesGradleRunner instance configured with the specified argument, never null.java.util.List<java.lang.String> getAllArguments()
Effectively, the command line arguments to Gradle. This includes all tasks, flags, properties etc.
The returned list is immutable.
GradleRunner usingSettingsFile(java.io.File settingsFile)
"--settings-file" argument.settingsFile - the settings file to useGradleRunner instance configured with the specified settings file, never null.GradleRunner ignoresMissingSettingsFile()
GradleRunner instance configured to ignore default behavior when settings file is missing, never null.GradleRunner usingBuildScript(java.io.File buildScript)
"--build-file" argument.buildScript - the build script file to useGradleRunner instance configured with the specified build script file, never null.GradleRunner usingInitScript(java.io.File initScript)
"--init-script" argument.initScript - the init script file to useGradleRunner instance configured with the specified init script file, never null.GradleRunner usingProjectDirectory(java.io.File projectDirectory)
"--project-dir" argument.projectDirectory - the project directory to useGradleRunner instance configured with the specified project directory, never null.GradleRunner withoutDeprecationChecks()
GradleRunner without deprecation checking enabled, never null..GradleRunner withDefaultCharacterEncoding(java.nio.charset.Charset defaultCharacterEncoding)
defaultCharacterEncoding - the default character encoding to useGradleRunner instance configured with the specified character encoding, never null.GradleRunner withDefaultLocale(java.util.Locale defaultLocale)
defaultLocale - the default locale to useGradleRunner instance configured with the specified locale, never null.GradleRunner withWelcomeMessageEnabled()
GradleRunner instance configured with the welcome message on first invocation, never null.GradleRunner publishBuildScans()
GradleRunner instance configured to publish build scans for each builds executed, never null.GradleRunner withUserHomeDirectory(java.io.File userHomeDirectory)
userHomeDirectory - the user home directory to useGradleRunner instance configured with the specified user home directory, never null.GradleRunner withGradleUserHomeDirectory(java.io.File gradleUserHomeDirectory)
Note: does not affect the daemon base dir.
gradleUserHomeDirectory - the Gradle user home directory to useGradleRunner instance configured with the specified Gradle user home directory, never null.GradleRunner requireOwnGradleUserHomeDirectory()
getWorkingDirectory() directory.
Note: does not affect the daemon base dir.
GradleRunner instance configured with a unique Gradle user home directory, neverl null.GradleRunner withEnvironmentVariables(java.util.Map<java.lang.String,?> environmentVariables)
environmentVariables - the environment variables to useGradleRunner instance configured with the specified environment variables, never null.GradleRunner withEnvironmentVariable(java.lang.String key, java.lang.String value)
key - the environment variable keyvalue - the environment variable valueGradleRunner instance configured with the specified additional environment variable, never null.@Deprecated GradleRunner withEnvironmentVars(java.util.Map<java.lang.String,?> environmentVariables)
Convenience method to allow migration from, older, Gradle Executer API.
environmentVariables - the environment variables to useGradleRunner instance configured with the specified environment variables, never null.withEnvironmentVariables(Map)default GradleRunner withEnvironment(java.util.Map<java.lang.String,java.lang.String> environmentVariables)
Convenience method to allow migration from Gradle Test Kit API.
environmentVariables - the environment variables to useGradleRunner instance configured with the specified environment variables, never null.GradleRunner withRichConsoleEnabled()
GradleRunner instance configured with the rich console enabled, never null.GradleRunner configure(java.util.function.UnaryOperator<GradleRunner> action)
GradleRunner instance returned by the configuration action, never null.GradleRunner forwardStandardOutput(java.io.Writer 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.
writer - the writer that build standard output should be forwarded toforwardStandardError(Writer)default GradleRunner forwardStdOutput(java.io.Writer writer)
writer - the writer that build standard output should be forwarded toforwardStandardOutput(Writer)GradleRunner forwardStandardError(java.io.Writer 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.
writer - the writer that build standard error output should be forwarded toforwardStandardOutput(Writer)default GradleRunner forwardStdError(java.io.Writer writer)
writer - the writer that build standard error output should be forwarded toforwardStandardError(Writer)GradleRunner forwardOutput()
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.
forwardStandardOutput(Writer),
forwardStandardError(Writer)GradleRunner beforeExecute(java.util.function.UnaryOperator<GradleRunner> action)
action - the action that will configure the runner further before execution.GradleRunner configured with the specified additional action, never null.GradleRunner afterExecute(java.util.function.Consumer<GradleExecutionContext> action)
action - the action that will assert based on the execution context after execution.GradleRunner configured with the specified additional action, never null.BuildResult build() throws InvalidRunnerConfigurationException, UnexpectedBuildFailure
InvalidRunnerConfigurationException - if the configuration of this runner is invalid (e.g. project directory not set)UnexpectedBuildFailure - if the build does not succeedBuildResult buildAndFail() throws InvalidRunnerConfigurationException, UnexpectedBuildSuccess
InvalidRunnerConfigurationException - if the configuration of this runner is invalid (e.g. project directory not set)UnexpectedBuildSuccess - if the build succeeds