# Test

@NullMarked
@CacheableTask
abstract class Test : AbstractTestTask, JavaForkOptions, PatternFilterable(source)

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.

    plugins {
        id("java-library") // adds 'test' task
    }

    test {
      // discover and execute JUnit4-based tests
      useJUnit()

      // discover and execute TestNG-based tests
      useTestNG()

      // discover and execute JUnit Platform-based tests
      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
      addTestListener(new TestListener() {
         void beforeTest(TestDescriptor descriptor) {
             logger.lifecycle("Running test: " + descriptor)
         }
      })

      // fail the 'test' task on the first test failure
      failFast = true

      // skip an actual test execution
      dryRun = true

      // listen to standard out and standard error of the test JVM(s)
      addTestOutputListener { descriptor, event ->
         logger.lifecycle("Test: " + descriptor + " produced standard out/err: " + event.message )
      }
    }

Content copied to clipboard

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

Content copied to clipboard

## Constructors

Test
Link copied to clipboard
constructor()

## Properties

classpath
Link copied to clipboard
@get:Internal(value = "captured by stableClasspath")
open var classpath: FileCollection
conventionMapping
Link copied to clipboard
open val conventionMapping: @Nullable ConventionMapping
description
Link copied to clipboard
open var description: @Nullable String
enabled
Link copied to clipboard
open var enabled: Boolean
extra
Link copied to clipboard
val ExtensionAware.extra: ExtraPropertiesExtension

The extra properties extension in this object's extension container.

forkEvery
Link copied to clipboard
@get:Internal
open var forkEvery: Long
group
Link copied to clipboard
open var group: @Nullable String
ignoreFailures
Link copied to clipboard
open var ignoreFailures: Boolean
impliesSubProjects
Link copied to clipboard
open var impliesSubProjects: Boolean
javaLauncher
Link copied to clipboard
val javaLauncher: Property<JavaLauncher>
maxParallelForks
Link copied to clipboard
@get:Internal
open var maxParallelForks: Int
modularity
Link copied to clipboard
val modularity: ModularitySpec
reports
Link copied to clipboard
val reports: TestTaskReports
state
Link copied to clipboard
val state: TaskStateInternal
TASK_ACTION
Link copied to clipboard
val TASK_ACTION: String = "action"
TASK_CONSTRUCTOR_ARGS
Link copied to clipboard
val TASK_CONSTRUCTOR_ARGS: String = "constructorArgs"
TASK_DEPENDS_ON
Link copied to clipboard
val TASK_DEPENDS_ON: String = "dependsOn"
TASK_DESCRIPTION
Link copied to clipboard
val TASK_DESCRIPTION: String = "description"
TASK_GROUP
Link copied to clipboard
val TASK_GROUP: String = "group"
TASK_NAME
Link copied to clipboard
val TASK_NAME: String = "name"
TASK_OVERWRITE
Link copied to clipboard
val TASK_OVERWRITE: String = "overwrite"
TASK_TYPE
Link copied to clipboard
val TASK_TYPE: String = "type"
testClassesDirs
Link copied to clipboard
@get:Internal
open var testClassesDirs: FileCollection
testLogging
Link copied to clipboard
val testLogging: TestLoggingContainer
timeout
Link copied to clipboard
val timeout: Property<Duration>

## Functions

acceptServiceReferences
Link copied to clipboard
open fun acceptServiceReferences(serviceReferences: Set<ServiceReferenceSpec>)
addTestListener
Link copied to clipboard
open fun addTestListener(listener: TestListener)
addTestMetadataListener
Link copied to clipboard
open fun addTestMetadataListener(listener: TestMetadataListener)
addTestOutputListener
Link copied to clipboard
open fun addTestOutputListener(listener: TestOutputListener)
afterSuite
Link copied to clipboard
open fun afterSuite(closure: Closure)
afterTest
Link copied to clipboard
open fun afterTest(closure: Closure)
appendParallelSafeAction
Link copied to clipboard
open fun appendParallelSafeAction(action: Action<in Task>)
beforeSuite
Link copied to clipboard
open fun beforeSuite(closure: Closure)
beforeTest
Link copied to clipboard
open fun beforeTest(closure: Closure)
bootstrapClasspath
Link copied to clipboard
open fun bootstrapClasspath(@Nullable classpath: Array<@Nullable Any>): Test
compareTo
Link copied to clipboard
open fun compareTo(otherTask: Task): Int
configure
Link copied to clipboard
open fun configure(closure: Closure): Task
abstract fun configure(cl: Closure): T
configure
Link copied to clipboard
inline fun <T : Any> ExtensionAware.configure(noinline configuration: T.() -> Unit)

Executes the given configuration block against the extension of the specified type.

conventionMapping
Link copied to clipboard
open fun conventionMapping(property: String, mapping: Callable<out Any>): Task
copyTo
Link copied to clipboard
open fun copyTo(target: JavaForkOptions): Test
open fun copyTo(target: ProcessForkOptions): Test
debugOptions
Link copied to clipboard
open fun debugOptions(action: Action<JavaDebugOptions>)
dependsOn
Link copied to clipboard
open fun dependsOn(paths: Array<Any>): Task
doFirst
Link copied to clipboard
open fun doFirst(action: Action<in Task>): Task
doLast
Link copied to clipboard
open fun doLast(action: Action<in Task>): Task
doNotTrackState
Link copied to clipboard
open fun doNotTrackState(reasonNotToTrackState: String)
doNotTrackStateIf
Link copied to clipboard
open fun doNotTrackStateIf(reason: String, spec: Spec<in TaskInternal>)
environment
Link copied to clipboard
open fun environment(environmentVariables: Map<String, out Any>): Test
open fun environment(name: String, value: Any): Test
environment
Link copied to clipboard
inline fun Test.environment(vararg environmentVariables: Pair<String, Any>): Test

Kotlin extension function for org.gradle.api.tasks.testing.Test.environment.

inline fun ProcessForkOptions.environment(vararg environmentVariables: Pair<String, Any>): ProcessForkOptions

Kotlin extension function for org.gradle.process.ProcessForkOptions.environment.

exclude
Link copied to clipboard
open fun exclude(excludeSpec: Closure): Test
open fun exclude(excludeSpec: Spec<FileTreeElement>): Test
open fun exclude(excludes: Iterable<String>): Test
open fun exclude(excludes: Array<String>): Test
Adds exclude patterns for the files in the test classes directory (e.g.
executable
Link copied to clipboard
open fun executable(executable: Any): Test
executeTests
Link copied to clipboard
open fun executeTests()
filter
Link copied to clipboard
open fun filter(action: Action<TestFilter>)
Executes the action against the getFilter.
finalizedBy
Link copied to clipboard
open fun finalizedBy(paths: Array<Any>): Task
getActions
Link copied to clipboard
open fun getActions(): List<Action<in Task>>
getAllJvmArgs
Link copied to clipboard
open fun getAllJvmArgs(): List<String>
getAnt
Link copied to clipboard
open fun getAnt(): AntBuilder
getAsDynamicObject
Link copied to clipboard
open fun getAsDynamicObject(): DynamicObject
getBinaryResultsDirectory
Link copied to clipboard
abstract fun getBinaryResultsDirectory(): DirectoryProperty
getBootstrapClasspath
Link copied to clipboard
open fun getBootstrapClasspath(): FileCollection
getCandidateClassFiles
Link copied to clipboard
@InputFiles
@SkipWhenEmpty
@IgnoreEmptyDirectories
@PathSensitive(value = PathSensitivity.RELATIVE)
open fun getCandidateClassFiles(): FileTree
Returns the classes files to scan for test classes.
getDebug
Link copied to clipboard
open fun getDebug(): Boolean
getDebugOptions
Link copied to clipboard
open fun getDebugOptions(): JavaDebugOptions
getDefaultCharacterEncoding
Link copied to clipboard
@Nullable
open fun getDefaultCharacterEncoding(): @Nullable String
getDependsOn
Link copied to clipboard
open fun getDependsOn(): Set<Any>
getDestroyables
Link copied to clipboard
open fun getDestroyables(): TaskDestroyables
getDidWork
Link copied to clipboard
open fun getDidWork(): Boolean
getDryRun
Link copied to clipboard
@Incubating
@Input
abstract fun getDryRun(): Property<Boolean>
Indicates if this task will skip individual test execution.
getEnableAssertions
Link copied to clipboard
open fun getEnableAssertions(): Boolean
getEnvironment
Link copied to clipboard
@Internal
open fun getEnvironment(): Map<String, Any>
getExcludes
Link copied to clipboard
@Internal
open fun getExcludes(): Set<String>
Returns the exclude patterns for test execution.
getExecutable
Link copied to clipboard
@Internal
open fun getExecutable(): String
getExtensions
Link copied to clipboard
open fun getExtensions(): ExtensionContainer
getFailFast
Link copied to clipboard
open fun getFailFast(): Boolean
Indicates if this task will fail on the first failed test
getFailOnNoDiscoveredTests
Link copied to clipboard
abstract fun getFailOnNoDiscoveredTests(): Property<Boolean>
getFilter
Link copied to clipboard
open fun getFilter(): TestFilter
getFinalizedBy
Link copied to clipboard
open fun getFinalizedBy(): TaskDependency
getIdentityPath
Link copied to clipboard
open fun getIdentityPath(): Path
getIncludes
Link copied to clipboard
@Internal
open fun getIncludes(): Set<String>
Returns the include patterns for test execution.
getInputs
Link copied to clipboard
open fun getInputs(): TaskInputsInternal
abstract fun getInputs(): TaskInputs
getJavaVersion
Link copied to clipboard
@Input
open fun getJavaVersion(): JavaVersion
Returns the version of Java used to run the tests based on the JavaLauncher specified by getJavaLauncher, or the executable specified by getExecutable if the `JavaLauncher` is not present.
getJvmArgs
Link copied to clipboard
open fun getJvmArgs(): List<String>
getJvmArgumentProviders
Link copied to clipboard
open fun getJvmArgumentProviders(): List<CommandLineArgumentProvider>
getLifecycleDependencies
Link copied to clipboard
open fun getLifecycleDependencies(): TaskDependencyInternal
abstract fun getLifecycleDependencies(): TaskDependency
getLocalState
Link copied to clipboard
open fun getLocalState(): TaskLocalState
getLogger
Link copied to clipboard
open fun getLogger(): Logger
getLogging
Link copied to clipboard
open fun getLogging(): LoggingManager
getMaxHeapSize
Link copied to clipboard
@Nullable
open fun getMaxHeapSize(): @Nullable String
getMinHeapSize
Link copied to clipboard
@Nullable
open fun getMinHeapSize(): @Nullable String
getMustRunAfter
Link copied to clipboard
open fun getMustRunAfter(): TaskDependency
getName
Link copied to clipboard
open fun getName(): String
getOnlyIf
Link copied to clipboard
open fun getOnlyIf(): Spec<in TaskInternal>
getOptions
Link copied to clipboard
open fun getOptions(): TestFrameworkOptions
Returns test framework specific options.
getOutputs
Link copied to clipboard
open fun getOutputs(): TaskOutputsInternal
abstract fun getOutputs(): TaskOutputs
getPath
Link copied to clipboard
open fun getPath(): String
getProject
Link copied to clipboard
open fun getProject(): Project
getReasonNotToTrackState
Link copied to clipboard
open fun getReasonNotToTrackState(): Optional<String>
getReasonsNotToTrackState
Link copied to clipboard
open fun getReasonsNotToTrackState(): Set<String>
getReasonTaskIsIncompatibleWithConfigurationCache
Link copied to clipboard
open fun getReasonTaskIsIncompatibleWithConfigurationCache(): Optional<String>
getReports
Link copied to clipboard
abstract fun getReports(): T
getRequiredServices
Link copied to clipboard
open fun getRequiredServices(): TaskRequiredServices
getSharedResources
Link copied to clipboard
open fun getSharedResources(): List<ResourceLock>
abstract fun getSharedResources(): List<out ResourceLock>
getShouldRunAfter
Link copied to clipboard
open fun getShouldRunAfter(): TaskDependency
getStandardOutputCapture
Link copied to clipboard
open fun getStandardOutputCapture(): StandardOutputCapture
getState
Link copied to clipboard
abstract fun getState(): TaskState
getSystemProperties
Link copied to clipboard
open fun getSystemProperties(): Map<String, @Nullable Any>
getTaskActions
Link copied to clipboard
open fun getTaskActions(): List<InputChangesAwareTaskAction>
getTaskDependencies
Link copied to clipboard
open fun getTaskDependencies(): TaskDependencyInternal
abstract fun getTaskDependencies(): TaskDependency
getTaskIdentity
Link copied to clipboard
open fun getTaskIdentity(): TaskIdentity<out Any>
getTemporaryDir
Link copied to clipboard
open fun getTemporaryDir(): File
getTemporaryDirFactory
Link copied to clipboard
open fun getTemporaryDirFactory(): Factory<File>
getTestDefinitionDirs
Link copied to clipboard
@Incubating
@InputFiles
@SkipWhenEmpty
@IgnoreEmptyDirectories
@PathSensitive(value = PathSensitivity.RELATIVE)
abstract fun getTestDefinitionDirs(): ConfigurableFileCollection
Returns directories to scan for non-class-based test definition files.
getTestFramework
Link copied to clipboard
@Internal
open fun getTestFramework(): TestFramework
getTestFrameworkProperty
Link copied to clipboard
open fun getTestFrameworkProperty(): Property<TestFramework>
Returns the configured TestFramework.
getWorkingDir
Link copied to clipboard
@Internal
open fun getWorkingDir(): File
hasProperty
Link copied to clipboard
open fun hasProperty(propertyName: String): Boolean
hasTaskActions
Link copied to clipboard
open fun hasTaskActions(): Boolean
include
Link copied to clipboard
open fun include(includeSpec: Closure): Test
open fun include(includeSpec: Spec<FileTreeElement>): Test
open fun include(includes: Iterable<String>): Test
open fun include(includes: Array<String>): Test
Adds include patterns for the files in the test classes directory (e.g.
injectIntoNewInstance
Link copied to clipboard
open fun <T : Task?> injectIntoNewInstance(project: ProjectInternal, identity: TaskIdentity<T>, factory: Callable<T>): T
isCompatibleWithConfigurationCache
Link copied to clipboard
open fun isCompatibleWithConfigurationCache(): Boolean
isEnabled
Link copied to clipboard
open fun isEnabled(): Boolean
isHasCustomActions
Link copied to clipboard
open fun isHasCustomActions(): Boolean
isScanForTestClasses
Link copied to clipboard
@Input
open fun isScanForTestClasses(): Boolean
Specifies whether test classes should be detected.
jvmArgs
Link copied to clipboard
open fun jvmArgs(arguments: Iterable<out Any>): Test
open fun jvmArgs(arguments: Array<Any>): Test
mustRunAfter
Link copied to clipboard
open fun mustRunAfter(paths: Array<Any>): Task
notCompatibleWithConfigurationCache
Link copied to clipboard
open fun notCompatibleWithConfigurationCache(reason: String)
onlyIf
Link copied to clipboard
open fun onlyIf(spec: Spec<in Task>)
onOutput
Link copied to clipboard
open fun onOutput(closure: Closure)
options
Link copied to clipboard
open fun options(@DelegatesTo(value = TestFrameworkOptions::class) testFrameworkConfigure: Closure): TestFrameworkOptions
open fun options(testFrameworkConfigure: Action<in TestFrameworkOptions>): TestFrameworkOptions
Configures test framework specific options.
prependParallelSafeAction
Link copied to clipboard
open fun prependParallelSafeAction(action: Action<in Task>)
property
Link copied to clipboard
open fun property(propertyName: String): Any
removeTestListener
Link copied to clipboard
open fun removeTestListener(listener: TestListener)
removeTestMetadataListener
Link copied to clipboard
open fun removeTestMetadataListener(listener: TestMetadataListener)
removeTestOutputListener
Link copied to clipboard
open fun removeTestOutputListener(listener: TestOutputListener)
reports
Link copied to clipboard
abstract fun reports(closure: Closure): T
open fun reports(closure: Closure): TestTaskReports
restoreOnlyIf
Link copied to clipboard
open fun restoreOnlyIf(onlyIf: Spec<in TaskInternal>)
restoreTaskActions
Link copied to clipboard
open fun restoreTaskActions(taskActions: List<InputChangesAwareTaskAction>)
setActions
Link copied to clipboard
open fun setActions(replacements: List<Action<in Task>>)
setAllJvmArgs
Link copied to clipboard
open fun setAllJvmArgs(arguments: Iterable<out Any>)
open fun setAllJvmArgs(arguments: List<String>)
setBootstrapClasspath
Link copied to clipboard
open fun setBootstrapClasspath(classpath: FileCollection)
setDebug
Link copied to clipboard
open fun setDebug(enabled: Boolean)
setDefaultCharacterEncoding
Link copied to clipboard
open fun setDefaultCharacterEncoding(@Nullable defaultCharacterEncoding: @Nullable String)
setDependsOn
Link copied to clipboard
open fun setDependsOn(dependsOn: Iterable<out Any>)
setDidWork
Link copied to clipboard
open fun setDidWork(didWork: Boolean)
setEnableAssertions
Link copied to clipboard
open fun setEnableAssertions(enabled: Boolean)
setEnvironment
Link copied to clipboard
open fun setEnvironment(environmentVariables: Map<String, out Any>)
setEnvironment
Link copied to clipboard
inline fun ProcessForkOptions.setEnvironment(vararg environmentVariables: Pair<String, Any>)

Kotlin extension function for org.gradle.process.ProcessForkOptions.setEnvironment.

setExcludes
Link copied to clipboard
open fun setExcludes(excludes: Iterable<String>): Test
Sets the exclude patterns for test execution.
setExecutable
Link copied to clipboard
open fun setExecutable(executable: Any)
open fun setExecutable(executable: String)
setFailFast
Link copied to clipboard
open fun setFailFast(failFast: Boolean)
Enables fail fast behavior causing the task to fail on the first failed test.
setFinalizedBy
Link copied to clipboard
open fun setFinalizedBy(finalizedByTasks: Iterable<out Any>)
setIncludes
Link copied to clipboard
open fun setIncludes(includes: Iterable<String>): Test
Sets the include patterns for test execution.
setJvmArgs
Link copied to clipboard
open fun setJvmArgs(arguments: Iterable<out Any>)
open fun setJvmArgs(arguments: List<String>)
setMaxHeapSize
Link copied to clipboard
open fun setMaxHeapSize(@Nullable heapSize: @Nullable String)
setMinHeapSize
Link copied to clipboard
open fun setMinHeapSize(@Nullable heapSize: @Nullable String)
setMustRunAfter
Link copied to clipboard
open fun setMustRunAfter(mustRunAfterTasks: Iterable<out Any>)
setOnlyIf
Link copied to clipboard
open fun setOnlyIf(spec: Spec<in Task>)
setProperty
Link copied to clipboard
open fun setProperty(name: String, value: Any)
setScanForTestClasses
Link copied to clipboard
open fun setScanForTestClasses(scanForTestClasses: Boolean)
setShouldRunAfter
Link copied to clipboard
open fun setShouldRunAfter(shouldRunAfterTasks: Iterable<out Any>)
setSystemProperties
Link copied to clipboard
open fun setSystemProperties(properties: Map<String, out @Nullable Any>)
setSystemProperties
Link copied to clipboard
inline fun JavaForkOptions.setSystemProperties(vararg properties: Pair<String, Any>)

Kotlin extension function for org.gradle.process.JavaForkOptions.setSystemProperties.

setTestNameIncludePatterns
Link copied to clipboard
open fun setTestNameIncludePatterns(testNamePattern: List<String>): Test
setWorkingDir
Link copied to clipboard
open fun setWorkingDir(dir: File)
open fun setWorkingDir(dir: Any)
shouldRunAfter
Link copied to clipboard
open fun shouldRunAfter(paths: Array<Any>): TaskDependency
systemProperties
Link copied to clipboard
open fun systemProperties(properties: Map<String, out @Nullable Any>): Test
systemProperties
Link copied to clipboard
inline fun Test.systemProperties(vararg properties: Pair<String, Any>): Test

Kotlin extension function for org.gradle.api.tasks.testing.Test.systemProperties.

inline fun JavaForkOptions.systemProperties(vararg properties: Pair<String, Any>): JavaForkOptions

Kotlin extension function for org.gradle.process.JavaForkOptions.systemProperties.

systemProperty
Link copied to clipboard
open fun systemProperty(name: String, @Nullable value: @Nullable Any): Test
testFramework
Link copied to clipboard
open fun testFramework(@Nullable testFrameworkConfigure: @Nullable Closure): TestFramework
Do not call this method.
testLogging
Link copied to clipboard
open fun testLogging(closure: Closure)
the
Link copied to clipboard
inline fun <T : Any> ExtensionAware.the(): T

Returns the extension of the specified type.

fun <T : Any> ExtensionAware.the(extensionType: KClass<T>): T

Returns the extension of the specified extensionType.

useJUnit
Link copied to clipboard
open fun useJUnit()
Specifies that JUnit4 should be used to discover and execute the tests.
open fun useJUnit(@Nullable @DelegatesTo(value = JUnitOptions::class) testFrameworkConfigure: @Nullable Closure)
open fun useJUnit(testFrameworkConfigure: Action<in JUnitOptions>)
Specifies that JUnit4 should be used to discover and execute the tests with additional configuration.
useJUnitPlatform
Link copied to clipboard
open fun useJUnitPlatform()
Specifies that JUnit Platform should be used to discover and execute the tests.
open fun useJUnitPlatform(testFrameworkConfigure: Action<in JUnitPlatformOptions>)
Specifies that JUnit Platform should be used to discover and execute the tests with additional configuration.
usesService
Link copied to clipboard
open fun usesService(service: Provider<out BuildService<out Any>>)
useTestNG
Link copied to clipboard
open fun useTestNG()
Specifies that TestNG should be used to discover and execute the tests.
open fun useTestNG(@DelegatesTo(value = TestNGOptions::class) testFrameworkConfigure: Closure)
open fun useTestNG(testFrameworkConfigure: Action<in TestNGOptions>)
Specifies that TestNG should be used to discover and execute the tests with additional configuration.
workingDir
Link copied to clipboard
open fun workingDir(dir: Any): Test