api / org.gradle.api.tasks.testing / Test

Test

@NonNullApi @CacheableTask open class Test : AbstractTestTask, JavaForkOptions, PatternFilterable

Executes JUnit (3.8.x, 4.x or 5.x) or TestNG tests. Test are always run in (one or more) separate JVMs. The sample below shows various configuration options.

 apply plugin: 'java' // adds 'test' task test { // enable TestNG support (default is JUnit) useTestNG() // enable JUnit Platform (a.k.a. JUnit 5) support useJUnitPlatform() // set a system property for the test JVM(s) systemProperty 'some.prop', 'value' // explicitly include or exclude tests include 'org/foo/**' exclude 'org/boo/**' // show standard out and standard error of the test JVM(s) on the console testLogging.showStandardStreams = true // set heap size for the test JVM(s) minHeapSize = "128m" maxHeapSize = "512m" // set JVM arguments for the test JVM(s) jvmArgs '-XX:MaxPermSize=256m' // listen to events in the test execution lifecycle beforeTest { descriptor -> logger.lifecycle("Running test: " + descriptor) } // Fail the 'test' task on the first test failure failFast = true // listen to standard out and standard error of the test JVM(s) onOutput { descriptor, event -> logger.lifecycle("Test: " + descriptor + " produced standard out/err: " + event.message ) } } 

The test process can be started in debug mode (see #getDebug()) in an ad-hoc manner by supplying the `--debug-jvm` switch when invoking the build.

 gradle someTestTask --debug-jvm 

Constructors

<init>

Test()

Functions

bootstrapClasspath

open fun bootstrapClasspath(vararg classpath: Any): Test

{@inheritDoc}

copyTo

open fun copyTo(target: ProcessForkOptions): Test
open fun copyTo(target: JavaForkOptions): Test

{@inheritDoc}

environment

open fun environment(environmentVariables: MutableMap<String, *>): Test
open fun environment(name: String, value: Any): Test

{@inheritDoc}

exclude

open fun exclude(vararg excludes: String): Test
open fun exclude(excludes: MutableIterable<String>): Test

Adds exclude patterns for the files in the test classes directory (e.g. '**/*Test.class')).

open fun exclude(excludeSpec: Spec<FileTreeElement>): Test
open fun exclude(excludeSpec: Closure<Any>): Test

{@inheritDoc}

executable

open fun executable(executable: Any): Test

{@inheritDoc}

executeTests

open fun executeTests(): Unit

filter

open fun filter(action: Action<TestFilter>): Unit

Executes the action against the #getFilter().

getAllJvmArgs

open fun getAllJvmArgs(): MutableList<String>

{@inheritDoc}

getBootstrapClasspath

open fun getBootstrapClasspath(): FileCollection

{@inheritDoc}

getCandidateClassFiles

open fun getCandidateClassFiles(): FileTree

Returns the classes files to scan for test classes.

getClasspath

open fun getClasspath(): FileCollection

Returns the classpath to use to execute the tests.

getDebug

open fun getDebug(): Boolean

{@inheritDoc}

getDefaultCharacterEncoding

open fun getDefaultCharacterEncoding(): String

{@inheritDoc}

getEnableAssertions

open fun getEnableAssertions(): Boolean

{@inheritDoc}

getEnvironment

open fun getEnvironment(): MutableMap<String, Any>

{@inheritDoc}

getExcludes

open fun getExcludes(): MutableSet<String>

Returns the exclude patterns for test execution.

getExecutable

open fun getExecutable(): String

{@inheritDoc}

getFailFast

open fun getFailFast(): Boolean

Indicates if this task will fail on the first failed test

getForkEvery

open fun getForkEvery(): Long

Returns the maximum number of test classes to execute in a forked test process. The forked test process will be restarted when this limit is reached. The default value is 0 (no maximum).

getIncludes

open fun getIncludes(): MutableSet<String>

Returns the include patterns for test execution.

getJavaVersion

open fun getJavaVersion(): JavaVersion

Returns the version of Java used to run the tests based on the executable specified by #getExecutable().

getJvmArgs

open fun getJvmArgs(): MutableList<String>

{@inheritDoc}

getJvmArgumentProviders

open fun getJvmArgumentProviders(): MutableList<CommandLineArgumentProvider>

{@inheritDoc}

getMaxHeapSize

open fun getMaxHeapSize(): String

{@inheritDoc}

getMaxParallelForks

open fun getMaxParallelForks(): Int

Returns the maximum number of forked test processes to execute in parallel. The default value is 1 (no parallel test execution). It cannot exceed the value of max-workers for the current build.

getMinHeapSize

open fun getMinHeapSize(): String

{@inheritDoc}

getOptions

open fun getOptions(): TestFrameworkOptions

Returns test framework specific options. Make sure to call #useJUnit(), #useJUnitPlatform() or #useTestNG() before using this method.

getSystemProperties

open fun getSystemProperties(): MutableMap<String, Any>

{@inheritDoc}

getTestClassesDir

open fun getTestClassesDir(): File

Returns the root folder for the compiled test sources.

getTestClassesDirs

open fun getTestClassesDirs(): FileCollection

Returns the directories for the compiled test sources.

getTestFramework

open fun getTestFramework(): TestFramework

getWorkingDir

open fun getWorkingDir(): File

{@inheritDoc}

include

open fun include(vararg includes: String): Test
open fun include(includes: MutableIterable<String>): Test

Adds include patterns for the files in the test classes directory (e.g. '**/*Test.class')).

open fun include(includeSpec: Spec<FileTreeElement>): Test
open fun include(includeSpec: Closure<Any>): Test

{@inheritDoc}

isScanForTestClasses

open fun isScanForTestClasses(): Boolean

Specifies whether test classes should be detected. When true the classes which match the include and exclude patterns are scanned for test classes, and any found are executed. When false the classes which match the include and exclude patterns are executed.

jvmArgs

open fun jvmArgs(arguments: MutableIterable<*>): Test
open fun jvmArgs(vararg arguments: Any): Test

{@inheritDoc}

options

open fun options(testFrameworkConfigure: Closure<Any>): TestFrameworkOptions
open fun options(testFrameworkConfigure: Action<in TestFrameworkOptions>): TestFrameworkOptions

Configures test framework specific options. Make sure to call #useJUnit(), #useJUnitPlatform() or #useTestNG() before using this method.

setAllJvmArgs

open fun setAllJvmArgs(arguments: MutableList<String>): Unit
open fun setAllJvmArgs(arguments: MutableIterable<*>): Unit

{@inheritDoc}

setBootstrapClasspath

open fun setBootstrapClasspath(classpath: FileCollection): Unit

{@inheritDoc}

setClasspath

open fun setClasspath(classpath: FileCollection): Unit

setDebug

open fun setDebug(enabled: Boolean): Unit

{@inheritDoc}

setDefaultCharacterEncoding

open fun setDefaultCharacterEncoding(defaultCharacterEncoding: String): Unit

{@inheritDoc}

setEnableAssertions

open fun setEnableAssertions(enabled: Boolean): Unit

{@inheritDoc}

setEnvironment

open fun setEnvironment(environmentVariables: MutableMap<String, *>): Unit

{@inheritDoc}

setExcludes

open fun setExcludes(excludes: MutableIterable<String>): Test

Sets the exclude patterns for test execution.

setExecutable

open fun setExecutable(executable: String): Unit
open fun setExecutable(executable: Any): Unit

{@inheritDoc}

setFailFast

open fun setFailFast(failFast: Boolean): Unit

Enables fail fast behavior causing the task to fail on the first failed test.

setForkEvery

open fun setForkEvery(forkEvery: Long): Unit

Sets the maximum number of test classes to execute in a forked test process. Use null or 0 to use no maximum.

setIncludes

open fun setIncludes(includes: MutableIterable<String>): Test

Sets the include patterns for test execution.

setJvmArgs

open fun setJvmArgs(arguments: MutableList<String>): Unit
open fun setJvmArgs(arguments: MutableIterable<*>): Unit

{@inheritDoc}

setMaxHeapSize

open fun setMaxHeapSize(heapSize: String): Unit

{@inheritDoc}

setMaxParallelForks

open fun setMaxParallelForks(maxParallelForks: Int): Unit

Sets the maximum number of forked test processes to execute in parallel. Set to 1 to disable parallel test execution.

setMinHeapSize

open fun setMinHeapSize(heapSize: String): Unit

{@inheritDoc}

setScanForTestClasses

open fun setScanForTestClasses(scanForTestClasses: Boolean): Unit

setSystemProperties

open fun setSystemProperties(properties: MutableMap<String, *>): Unit

{@inheritDoc}

setTestClassesDir

open fun setTestClassesDir(testClassesDir: File): Unit

Sets the root folder for the compiled test sources.

setTestClassesDirs

open fun setTestClassesDirs(testClassesDirs: FileCollection): Unit

Sets the directories to scan for compiled test sources. Typically, this would be configured to use the output of a source set:

 apply plugin: 'java' sourceSets { integrationTest { compileClasspath += main.output runtimeClasspath += main.output } } task integrationTest(type: Test) { // Runs tests from src/integrationTest testClassesDirs = sourceSets.integrationTest.output.classesDirs classpath = sourceSets.integrationTest.runtimeClasspath } 

setTestNameIncludePatterns

open fun setTestNameIncludePatterns(testNamePattern: MutableList<String>): Test

{@inheritDoc}

setWorkingDir

open fun setWorkingDir(dir: File): Unit
open fun setWorkingDir(dir: Any): Unit

{@inheritDoc}

systemProperties

open fun systemProperties(properties: MutableMap<String, *>): Test

{@inheritDoc}

systemProperty

open fun systemProperty(name: String, value: Any): Test

{@inheritDoc}

testFramework

open fun testFramework(testFrameworkConfigure: Closure<Any>): TestFramework

useJUnit

open fun useJUnit(): Unit

Specifies that JUnit should be used to execute the tests.

To configure JUnit specific options, see #useJUnit(groovy.lang.Closure).

open fun useJUnit(testFrameworkConfigure: Closure<Any>): Unit

Specifies that JUnit should be used to execute the tests, configuring JUnit specific options.

The supplied closure configures an instance of , which can be used to configure how JUnit runs.

open fun useJUnit(testFrameworkConfigure: Action<in JUnitOptions>): Unit

Specifies that JUnit should be used to execute the tests, configuring JUnit specific options.

The supplied action configures an instance of , which can be used to configure how JUnit runs.

useJUnitPlatform

open fun useJUnitPlatform(): Unit

Specifies that JUnit Platform (a.k.a. JUnit 5) should be used to execute the tests.

To configure JUnit platform specific options, see #useJUnitPlatform(Action).

open fun useJUnitPlatform(testFrameworkConfigure: Action<in JUnitPlatformOptions>): Unit

Specifies that JUnit Platform (a.k.a. JUnit 5) should be used to execute the tests, configuring JUnit platform specific options.

The supplied action configures an instance of , which can be used to configure how JUnit platform runs.

useTestNG

open fun useTestNG(): Unit

Specifies that TestNG should be used to execute the tests.

To configure TestNG specific options, see #useTestNG(Closure).

open fun useTestNG(testFrameworkConfigure: Closure<Any>): Unit

Specifies that TestNG should be used to execute the tests, configuring TestNG specific options.

The supplied closure configures an instance of , which can be used to configure how TestNG runs.

open fun useTestNG(testFrameworkConfigure: Action<in TestFrameworkOptions>): Unit

Specifies that TestNG should be used to execute the tests, configuring TestNG specific options.

The supplied action configures an instance of , which can be used to configure how TestNG runs.

workingDir

open fun workingDir(dir: Any): Test

{@inheritDoc}

Inherited Functions

addTestListener

open fun addTestListener(listener: TestListener): Unit

Registers a test listener with this task. Consider also the following handy methods for quicker hooking into test execution: #beforeTest(groovy.lang.Closure), , #beforeSuite(groovy.lang.Closure), #afterSuite(groovy.lang.Closure)

This listener will NOT be notified of tests executed by other tasks. To get that behavior, use org.gradle.api.invocation.Gradle#addListener(Object).

addTestOutputListener

open fun addTestOutputListener(listener: TestOutputListener): Unit

Registers a output listener with this task. Quicker way of hooking into output events is using the #onOutput(groovy.lang.Closure) method.

afterSuite

open fun afterSuite(closure: Closure<Any>): Unit

Adds a closure to be notified after a test suite has executed. A TestDescriptor and TestResult instance are passed to the closure as a parameter.

This method is also called after all test suites are executed. The provided descriptor will have a null parent suite.

afterTest

open fun afterTest(closure: Closure<Any>): Unit

Adds a closure to be notified after a test has executed. A TestDescriptor and TestResult instance are passed to the closure as a parameter.

beforeSuite

open fun beforeSuite(closure: Closure<Any>): Unit

Adds a closure to be notified before a test suite is executed. A TestDescriptor instance is passed to the closure as a parameter.

This method is also called before any test suites are executed. The provided descriptor will have a null parent suite.

beforeTest

open fun beforeTest(closure: Closure<Any>): Unit

Adds a closure to be notified before a test is executed. A TestDescriptor instance is passed to the closure as a parameter.

getBinResultsDir

open fun getBinResultsDir(): File

Returns the root folder for the test results in internal binary format.

getBinaryResultsDirectory

open fun getBinaryResultsDirectory(): DirectoryProperty

Returns the root directory property for the test results in internal binary format.

getFilter

open fun getFilter(): TestFilter

Allows filtering tests for execution.

getIgnoreFailures

open fun getIgnoreFailures(): Boolean

{@inheritDoc}

getReports

open fun getReports(): TestTaskReports

The reports that this task potentially produces.

getTestLogging

open fun getTestLogging(): TestLoggingContainer

Allows to set options related to which test events are logged to the console, and on which detail level. For example, to show more information about exceptions use:

 apply plugin: 'java' test.testLogging { exceptionFormat "full" } 
For further information see TestLoggingContainer.

onOutput

open fun onOutput(closure: Closure<Any>): Unit

Adds a closure to be notified when output from the test received. A TestDescriptor and TestOutputEvent instance are passed to the closure as a parameter.

 apply plugin: 'java' test { onOutput { descriptor, event -> if (event.destination == TestOutputEvent.Destination.StdErr) { logger.error("Test: " + descriptor + ", error: " + event.message) } } } 

removeTestListener

open fun removeTestListener(listener: TestListener): Unit

Unregisters a test listener with this task. This method will only remove listeners that were added by calling #addTestListener(TestListener) on this task. If the listener was registered with Gradle using org.gradle.api.invocation.Gradle#addListener(Object) this method will not do anything. Instead, use .

removeTestOutputListener

open fun removeTestOutputListener(listener: TestOutputListener): Unit

Unregisters a test output listener with this task. This method will only remove listeners that were added by calling #addTestOutputListener(TestOutputListener) on this task. If the listener was registered with Gradle using org.gradle.api.invocation.Gradle#addListener(Object) this method will not do anything. Instead, use .

reports

open fun reports(closure: Closure<Any>): TestTaskReports
open fun reports(configureAction: Action<in TestTaskReports>): TestTaskReports

Configures the reports that this task potentially produces.

setBinResultsDir

open fun setBinResultsDir(binResultsDir: File): Unit

Sets the root folder for the test results in internal binary format.

setIgnoreFailures

open fun setIgnoreFailures(ignoreFailures: Boolean): Unit

{@inheritDoc}

testLogging

open fun testLogging(closure: Closure<Any>): Unit
open fun testLogging(action: Action<in TestLoggingContainer>): Unit

Allows configuring the logging of the test execution, for example log eagerly the standard output, etc.

 apply plugin: 'java' // makes the standard streams (err and out) visible at console when running tests test.testLogging { showStandardStreams = true }