Package dev.gradleplugins.runnerkit

Interface GradleRunner

  • public interface GradleRunner

    • Method Detail

      • 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)

      • 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.