# Test

API Documentation: | `Test`

Executes tests. Supports JUnit (3.8.x or 4.x) or TestNG tests.

### 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 maximum heap size, and the bootstrap classpath.
`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` | Returns true if debugging is enabled for the process. When enabled, the process is started suspended and listening on port 5005.
`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.
`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 maximum heap size.
`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).
`options` | The test options options.
`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.
`systemProperties` | The system properties which will be used for the process.
`testClassesDir` | The root folder for the compiled test sources.
`testReport` | Specifies whether the test report should be generated.
`testReportDir` | The root folder for the test reports.
`testResultsDir` | The root folder for the test results.
`testSrcDirs` | The directories containing the test source.
`workingDir` | The working directory for the process. Defaults to the project directory.

### Property details

#### ``List`<`String`>` `allJvmArgs`

The full set of arguments to use to launch the JVM for the process. This includes arguments to define system properties, the maximum heap size, and the bootstrap classpath.

#### `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`

Returns true if debugging is enabled for the process. When enabled, the process is started suspended and listening on port 5005.

Default with `java` plugin:
  `false`

#### `boolean` `enableAssertions`

Returns true if assertions are enabled for the process.

Default with `java` plugin:
  ``true``

#### ``Map`<`String`, `Object`>` `environment`

The environment variables to use for the process. Defaults to the environment of this process.

Default with `java` plugin:
  environment of the current process

#### ``Set`<`String`>` `excludes`

The exclude patterns for test execution.

Default with `java` plugin:
  []

#### `String` `executable`

The name of the executable to use.

Default with `java` plugin:
  java command for the current JVM.

#### `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.

Default with `java` plugin:
  `false`

#### ``Set`<`String`>` `includes`

The include patterns for test execution.

Default with `java` plugin:
  []

#### ``List`<`String`>` `jvmArgs`

The extra arguments to use to launch the JVM for the process. Does not include system properties and the maximum heap size.

Default with `java` plugin:
  `[]`

#### `String` `maxHeapSize`

The maximum heap size for the process, if any.

Default with `java` plugin:
  `null`

#### `int` `maxParallelForks`

The maximum number of forked test processes to execute in parallel. The default value is 1 (no parallel test execution).

Default with `java` plugin:
  `1`

#### `TestFrameworkOptions` `options` (read-only)

The test options options.

Be sure to call the appropriate `Test.useJUnit()` or `Test.useTestNG()` method before using this method.

#### `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`

#### ``Map`<`String`, `Object`>` `systemProperties`

The system properties which will be used for the process.

Default with `java` plugin:
  `[:]`

#### `File` `testClassesDir`

The root folder for the compiled test sources.

Default with `java` plugin:
  `project.sourceSets.test.classesDir`

#### `boolean` `testReport`

Specifies whether the test report should be generated.

Default with `java` plugin:
  `true`

#### `File` `testReportDir`

The root folder for the test reports.

Default with `java` plugin:
  `project.testReportDir`

#### `File` `testResultsDir`

The root folder for the test results.

Default with `java` plugin:
  `project.testResultsDir`

#### ``List`<`File`>` `testSrcDirs`

The directories containing the test source.

Default with `java` plugin:
  `project.sourceSets.test.java.srcDirs`

#### `File` `workingDir`

The working directory for the process. Defaults to the project directory.

Default with `java` plugin:
  `project.projectDir`

### Script blocks

No script blocks

### Methods

Method | Description
`addTestListener(listener)` | Registers a test listener with this task. This listener will NOT be notified of tests executed by other tasks. To get that behavior, use `Gradle.addListener()`.
`afterSuite(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.
`afterTest(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.
`beforeSuite(closure)` | Adds a closure to be notified before a test suite is executed. A `TestDescriptor` instance is passed to the closure as a parameter.
`beforeTest(closure)` | Adds a closure to be notified before a test is executed. A `TestDescriptor` instance is passed to the closure as a parameter.
`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.
`executable(executable)` | Sets the name of the executable to use.
`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.
`removeTestListener(listener)` | Unregisters a test listener with this task. This method will only remove listeners that were added by calling `Test.addTestListener()` on this task. If the listener was registered with Gradle using `Gradle.addListener()` this method will not do anything. Instead, use `Gradle.removeListener()`.
`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.
`useTestNG()` | Specifies that TestNG should be used to execute the tests.
`useTestNG(testFrameworkConfigure)` | Specifies that TestNG should be used to execute the tests.
`workingDir(dir)` | Sets the working directory for the process. The supplied argument is evaluated as for `Project.file()`.

### Method details

#### `void` `addTestListener`(`TestListener` listener)

Registers a test listener with this task. This listener will NOT be notified of tests executed by other tasks. To get that behavior, use `Gradle.addListener()`.

#### `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.

#### `Test` `bootstrapClasspath`(``Object`...` classpath)

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.

#### `Test` `environment`(`String` name, `Object` value)

Adds an environment variable to the environment for this process.

#### `Test` `environment`(``Map`<`String`, ?>` environmentVariables)

Adds some environment variables to the environment for this process.

#### `Test` `executable`(`Object` executable)

Sets the name of the executable to use.

#### `Test` `jvmArgs`(``Iterable`<?>` arguments)

Adds some arguments to use to launch the JVM for the process.

#### `Test` `jvmArgs`(``Object`...` arguments)

Adds some arguments to use to launch the JVM for the process.

#### `void` `removeTestListener`(`TestListener` listener)

Unregisters a test listener with this task. This method will only remove listeners that were added by calling `Test.addTestListener()` on this task. If the listener was registered with Gradle using `Gradle.addListener()` this method will not do anything. Instead, use `Gradle.removeListener()`.

#### `Test` `systemProperties`(``Map`<`String`, ?>` properties)

Adds some system properties to use for the process.

#### `void` `useJUnit`()

Specifies that JUnit should be used to execute the tests.

#### `void` `useJUnit`(`Closure` testFrameworkConfigure)

Specifies that JUnit should be used to execute the tests.

#### `void` `useTestNG`()

Specifies that TestNG should be used to execute the tests.

#### `void` `useTestNG`(`Closure` testFrameworkConfigure)

Specifies that TestNG should be used to execute the tests.

#### `Test` `workingDir`(`Object` dir)

Sets the working directory for the process. The supplied argument is evaluated as for `Project.file()`.