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 Test.getDebug()
) in an ad-hoc manner by supplying the `--debug-jvm` switch when invoking the build.
gradle someTestTask --debug-jvm
Properties
Property | Description |
allJvmArgs |
The full set of arguments to use to launch the JVM for the process. This includes arguments to define system properties, the minimum/maximum heap size, and the bootstrap classpath. |
binResultsDir |
Incubating
The root folder for the test results in internal binary format. |
bootstrapClasspath |
The bootstrap classpath to use for the process. The default bootstrap classpath for the JVM is used when this classpath is empty. |
classpath |
The classpath to use to execute the tests. |
debug |
Determines whether debugging is enabled for the test process. When enabled — |
enableAssertions |
Returns true if assertions are enabled for the process. |
environment |
The environment variables to use for the process. Defaults to the environment of this process. |
excludes |
The exclude patterns for test execution. |
executable |
The name of the executable to use. |
failFast |
Indicates if this task will fail on the first failed test |
forkEvery |
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). |
ignoreFailures |
Specifies whether the build should break when the verifications performed by this task fail. |
includes |
The include patterns for test execution. |
jvmArgs |
The extra arguments to use to launch the JVM for the process. Does not include system properties and the minimum/maximum heap size. |
jvmArgumentProviders |
Command line argument providers for the java process to fork. |
maxHeapSize |
The maximum heap size for the process, if any. |
maxParallelForks |
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. |
minHeapSize |
The minimum heap size for the process, if any. |
options |
Returns test framework specific options. Make sure to call |
reports |
The reports that this task potentially produces. |
scanForTestClasses |
Specifies whether test classes should be detected. When |
systemProperties |
The system properties which will be used for the process. |
testClassesDir |
Deprecated
The root folder for the compiled test sources. |
testClassesDirs |
The directories for the compiled test sources. |
testLogging |
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: |
workingDir |
The working directory for the process. Defaults to the project directory. |
Properties added by the jacoco
plugin
Property | Description |
jacoco |
The |
Methods
Method | Description |
addTestListener(listener) |
Registers a test listener with this task. Consider also the following handy methods for quicker hooking into test execution: |
addTestOutputListener(listener) |
Registers a output listener with this task. Quicker way of hooking into output events is using the |
afterSuite(closure) |
Adds a closure to be notified after a test suite has executed. A |
afterTest(closure) |
Adds a closure to be notified after a test has executed. A |
beforeSuite(closure) |
Adds a closure to be notified before a test suite is executed. A |
beforeTest(closure) |
Adds a closure to be notified before a test is executed. A |
bootstrapClasspath(classpath) |
Adds the given values to the end of the bootstrap classpath for the process. |
copyTo(target) |
Copies these options to the given options. |
copyTo(target) |
Copies these options to the given target options. |
environment(name, value) |
Adds an environment variable to the environment for this process. |
environment(environmentVariables) |
Adds some environment variables to the environment for this process. |
exclude(excludeSpec) |
Adds an exclude spec. This method may be called multiple times to append new specs.The given closure is passed a |
exclude(excludes) |
Adds exclude patterns for the files in the test classes directory (e.g. '**/*Test.class')). |
exclude(excludes) |
Adds exclude patterns for the files in the test classes directory (e.g. '**/*Test.class')). |
exclude(excludeSpec) |
Adds an exclude spec. This method may be called multiple times to append new specs. If excludes are not provided, then no files will be excluded. If excludes are provided, then files must not match any exclude pattern to be processed. |
executable(executable) |
Sets the name of the executable to use. |
include(includeSpec) |
Adds an include spec. This method may be called multiple times to append new specs. The given closure is passed a |
include(includes) |
Adds include patterns for the files in the test classes directory (e.g. '**/*Test.class')). |
include(includes) |
Adds include patterns for the files in the test classes directory (e.g. '**/*Test.class')). |
include(includeSpec) |
Adds an include spec. This method may be called multiple times to append new specs. If includes are not provided, then all files in this container will be included. If includes are provided, then a file must match at least one of the include patterns or specs to be included. |
jvmArgs(arguments) |
Adds some arguments to use to launch the JVM for the process. |
jvmArgs(arguments) |
Adds some arguments to use to launch the JVM for the process. |
onOutput(closure) |
Adds a closure to be notified when output from the test received. A |
options(testFrameworkConfigure) |
Configures test framework specific options. Make sure to call |
removeTestListener(listener) |
Unregisters a test listener with this task. This method will only remove listeners that were added by calling |
removeTestOutputListener(listener) |
Unregisters a test output listener with this task. This method will only remove listeners that were added by calling |
reports(configureAction) |
Configures the reports that this task potentially produces. |
setTestNameIncludePatterns(testNamePattern) |
Incubating
Sets the test name patterns to be included in execution. Classes or method names are supported, wildcard '*' is supported. For more information see the user guide chapter on testing. For more information on supported patterns see |
systemProperties(properties) |
Adds some system properties to use for the process. |
useJUnit() |
Specifies that JUnit should be used to execute the tests. |
useJUnit(testFrameworkConfigure) |
Specifies that JUnit should be used to execute the tests, configuring JUnit specific options. |
useJUnit(testFrameworkConfigure) |
Specifies that JUnit should be used to execute the tests, configuring JUnit specific options. |
useTestNG() |
Specifies that TestNG should be used to execute the tests. |
useTestNG(testFrameworkConfigure) |
Specifies that TestNG should be used to execute the tests, configuring TestNG specific options. |
useTestNG(testFrameworkConfigure) |
Specifies that TestNG should be used to execute the tests, configuring TestNG specific options. |
workingDir(dir) |
Sets the working directory for the process. The supplied argument is evaluated as per |
Script blocks
Block | Description |
options |
Configures test framework specific options. Make sure to call |
Script blocks added by the jacoco
plugin
Block | Description |
jacoco |
Configures the |
Property details
The full set of arguments to use to launch the JVM for the process. This includes arguments to define system properties, the minimum/maximum heap size, and the bootstrap classpath.
File
binResultsDir
Note: This property is incubating and may change in a future version of Gradle.
The root folder for the test results in internal binary format.
- Default:
project.testResultsDir
/binary/task.name
FileCollection
bootstrapClasspath
The bootstrap classpath to use for the process. The default bootstrap classpath for the JVM is used when this classpath is empty.
- Default with
java
plugin: []
FileCollection
classpath
The classpath to use to execute the tests.
- Default with
java
plugin: project.sourceSets.test.runtimeClasspath
boolean
debug
Determines whether debugging is enabled for the test process. When enabled — debug = true
— the process is started in a suspended state, listening on port 5005. You should disable parallel test execution when debugging and you will need to reattach the debugger occasionally if you use a non-zero value for Test.getForkEvery()
.
- Default with
java
plugin: false
boolean
enableAssertions
Returns true if assertions are enabled for the process.
- Default with
java
plugin: true
The environment variables to use for the process. Defaults to the environment of this process.
- Default with
java
plugin: - environment of the current process
String
executable
The name of the executable to use.
- Default with
java
plugin: - java command for the current JVM.
boolean
failFast
Indicates if this task will fail on the first failed test
- Default with
java
plugin: false
long
forkEvery
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).
- Default with
java
plugin: 0
boolean
ignoreFailures
Specifies whether the build should break when the verifications performed by this task fail.
The extra arguments to use to launch the JVM for the process. Does not include system properties and the minimum/maximum heap size.
- Default with
java
plugin: []
List
<CommandLineArgumentProvider
>
jvmArgumentProviders
(read-only)
List
<CommandLineArgumentProvider
>Command line argument providers for the java process to fork.
- Default with
java
plugin: []
int
maxParallelForks
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.
- Default with
java
plugin: 1
TestFrameworkOptions
options
(read-only)
Returns test framework specific options. Make sure to call Test.useJUnit()
, Test.useJUnitPlatform()
or Test.useTestNG()
before using this method.
TestTaskReports
reports
(read-only)
The reports that this task potentially produces.
boolean
scanForTestClasses
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.
- Default with
java
plugin: true
The system properties which will be used for the process.
- Default with
java
plugin: [:]
File
testClassesDir
Note: This property is deprecated and will be removed in the next major version of Gradle.
The root folder for the compiled test sources.
FileCollection
testClassesDirs
The directories for the compiled test sources.
- Default with
java
plugin: project.sourceSets.test.output.classesDirs
TestLoggingContainer
testLogging
(read-only)
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
.
File
workingDir
The working directory for the process. Defaults to the project directory.
- Default with
java
plugin: project.projectDir
JacocoTaskExtension
jacoco
(read-only)
The JacocoTaskExtension
added by the jacoco plugin.
Method details
void
addTestListener
(TestListener
listener)
Registers a test listener with this task. Consider also the following handy methods for quicker hooking into test execution: AbstractTestTask.beforeTest(groovy.lang.Closure)
, AbstractTestTask.afterTest(groovy.lang.Closure)
, AbstractTestTask.beforeSuite(groovy.lang.Closure)
, AbstractTestTask.afterSuite(groovy.lang.Closure)
This listener will NOT be notified of tests executed by other tasks. To get that behavior, use Gradle.addListener(java.lang.Object)
.
void
addTestOutputListener
(TestOutputListener
listener)
Registers a output listener with this task. Quicker way of hooking into output events is using the AbstractTestTask.onOutput(groovy.lang.Closure)
method.
void
afterSuite
(Closure
closure)
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.
void
afterTest
(Closure
closure)
Adds a closure to be notified after a test has executed. A TestDescriptor
and TestResult
instance are passed to the closure as a parameter.
void
beforeSuite
(Closure
closure)
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.
void
beforeTest
(Closure
closure)
Adds a closure to be notified before a test is executed. A TestDescriptor
instance is passed to the closure as a parameter.
Adds the given values to the end of the bootstrap classpath for the process.
Test
copyTo
(JavaForkOptions
target)
Copies these options to the given options.
Test
copyTo
(ProcessForkOptions
target)
Copies these options to the given target options.
Adds an environment variable to the environment for this process.
Adds some environment variables to the environment for this process.
Adds an exclude spec. This method may be called multiple times to append new specs.The given closure is passed a FileTreeElement
as its parameter. The closure should return true or false. Example:
copySpec { from 'source' into 'destination' //an example of excluding files from certain configuration: exclude { it.file in configurations.someConf.files } }
If excludes are not provided, then no files will be excluded. If excludes are provided, then files must not match any exclude pattern to be processed.
Adds exclude patterns for the files in the test classes directory (e.g. '**/*Test.class')).
Adds exclude patterns for the files in the test classes directory (e.g. '**/*Test.class')).
Test
exclude
(Spec
<FileTreeElement
>
excludeSpec)
Spec
<FileTreeElement
>Adds an exclude spec. This method may be called multiple times to append new specs. If excludes are not provided, then no files will be excluded. If excludes are provided, then files must not match any exclude pattern to be processed.
Adds an include spec. This method may be called multiple times to append new specs. The given closure is passed a FileTreeElement
as its parameter. If includes are not provided, then all files in this container will be included. If includes are provided, then a file must match at least one of the include patterns or specs to be included.
Adds include patterns for the files in the test classes directory (e.g. '**/*Test.class')).
Adds include patterns for the files in the test classes directory (e.g. '**/*Test.class')).
Test
include
(Spec
<FileTreeElement
>
includeSpec)
Spec
<FileTreeElement
>Adds an include spec. This method may be called multiple times to append new specs. If includes are not provided, then all files in this container will be included. If includes are provided, then a file must match at least one of the include patterns or specs to be included.
void
onOutput
(Closure
closure)
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) } } }
TestFrameworkOptions
options
(Action
<? super TestFrameworkOptions
>
testFrameworkConfigure)
Action
<? super TestFrameworkOptions
>Configures test framework specific options. Make sure to call Test.useJUnit()
, Test.useJUnitPlatform()
or Test.useTestNG()
before using this method.
void
removeTestListener
(TestListener
listener)
Unregisters a test listener with this task. This method will only remove listeners that were added by calling AbstractTestTask.addTestListener(org.gradle.api.tasks.testing.TestListener)
on this task. If the listener was registered with Gradle using Gradle.addListener(java.lang.Object)
this method will not do anything. Instead, use Gradle.removeListener(java.lang.Object)
.
void
removeTestOutputListener
(TestOutputListener
listener)
Unregisters a test output listener with this task. This method will only remove listeners that were added by calling AbstractTestTask.addTestOutputListener(org.gradle.api.tasks.testing.TestOutputListener)
on this task. If the listener was registered with Gradle using Gradle.addListener(java.lang.Object)
this method will not do anything. Instead, use Gradle.removeListener(java.lang.Object)
.
TestTaskReports
reports
(Action
<? super TestTaskReports
>
configureAction)
Action
<? super TestTaskReports
>Configures the reports that this task potentially produces.
AbstractTestTask
setTestNameIncludePatterns
(List
<String
>
testNamePattern)
List
<String
>Note: This method is incubating and may change in a future version of Gradle.
Sets the test name patterns to be included in execution. Classes or method names are supported, wildcard '*' is supported. For more information see the user guide chapter on testing. For more information on supported patterns see TestFilter
Adds some system properties to use for the process.
void
useJUnit
()
Specifies that JUnit should be used to execute the tests.
To configure JUnit specific options, see Test.useJUnit(groovy.lang.Closure)
.
void
useJUnit
(Closure
testFrameworkConfigure)
Specifies that JUnit should be used to execute the tests, configuring JUnit specific options.
The supplied closure configures an instance of JUnitOptions
, which can be used to configure how JUnit runs.
void
useJUnit
(Action
<? super JUnitOptions
>
testFrameworkConfigure)
Action
<? super JUnitOptions
>Specifies that JUnit should be used to execute the tests, configuring JUnit specific options.
The supplied action configures an instance of JUnitOptions
, which can be used to configure how JUnit runs.
void
useTestNG
()
Specifies that TestNG should be used to execute the tests.
To configure TestNG specific options, see Test.useTestNG(groovy.lang.Closure)
.
void
useTestNG
(Closure
testFrameworkConfigure)
Specifies that TestNG should be used to execute the tests, configuring TestNG specific options.
The supplied closure configures an instance of TestNGOptions
, which can be used to configure how TestNG runs.
void
useTestNG
(Action
<? super TestFrameworkOptions
>
testFrameworkConfigure)
Action
<? super TestFrameworkOptions
>Specifies that TestNG should be used to execute the tests, configuring TestNG specific options.
The supplied action configures an instance of TestNGOptions
, which can be used to configure how TestNG runs.
Sets the working directory for the process. The supplied argument is evaluated as per Project.file(java.lang.Object)
.
Script block details
options
{ }
Configures test framework specific options. Make sure to call Test.useJUnit()
, Test.useJUnitPlatform()
or Test.useTestNG()
before using this method.
- Delegates to:
TestFrameworkOptions
fromoptions
jacoco
{ }
Configures the JacocoTaskExtension
added by the jacoco plugin.
- Delegates to:
JacocoTaskExtension
fromjacoco
- Log in to post comments