# Test

API Documentation: | `Test`

Executes JUnit (3.8.x or 4.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()

      // 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)
      }

      // 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` | 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 minimum/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).
`minHeapSize` | The minimum heap size for the process, if any.
`options` | Returns test framework specific options. Make sure to call `Test.useJUnit()` or `Test.useTestNG()` before using this method.
`reports` | The reports that this task potentially produces.
`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.
`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:
`testSrcDirs` | The directories containing the test source.
`workingDir` | The working directory for the process. Defaults to the project directory.

#### Properties added by the `jacoco` plugin

Property | Description
`jacoco` | The `JacocoTaskExtension` added by the jacoco plugin.

### Methods

Method | Description
`addTestListener(listener)` | Registers a test listener with this task. Consider also the following handy methods for quicker hooking into test execution: `Test.beforeTest()`, `Test.afterTest()`, `Test.beforeSuite()`, `Test.afterSuite()`
`addTestOutputListener(listener)` | Registers a output listener with this task. Quicker way of hooking into output events is using the `Test.onOutput()` method.
`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.
`exclude(excludeSpec)` | 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:
`exclude(excludes)` | Adds exclude patterns for the files in the test classes directory (e.g. '**null*Test.class')).
`exclude(excludes)` | Adds exclude patterns for the files in the test classes directory (e.g. '**null*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 `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.
`include(includes)` | Adds include patterns for the files in the test classes directory (e.g. '**null*Test.class')).
`include(includes)` | Adds include patterns for the files in the test classes directory (e.g. '**null*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 `TestDescriptor` and `TestOutputEvent` instance are passed to the closure as a parameter.
`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()`.
`removeTestOutputListener(listener)` | Unregisters a test output listener with this task. This method will only remove listeners that were added by calling `Test.addTestOutputListener()` 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, 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.
`workingDir(dir)` | Sets the working directory for the process. The supplied argument is evaluated as per `Project.file()`.

### Script blocks

Block | Description
`options` | Configures test framework specific options. Make sure to call `Test.useJUnit()` or `Test.useTestNG()` before using this method.
`reports` | Configures the reports that this task potentially produces.
`testLogging` | Allows configuring the logging of the test execution, for example log eagerly the standard output, etc.

#### Script blocks added by the `jacoco` plugin

Block | Description
`jacoco` | Configures the `JacocoTaskExtension` added by the jacoco plugin.

### 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 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 with `java` plugin:
  ``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`

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 minimum/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`

#### `String` `minHeapSize`

The minimum heap size for the process, if any.

Default with `java` plugin:
  `null`

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

Returns test framework specific options. Make sure to call `Test.useJUnit()` or `Test.useTestNG()` before using this method.

#### `TestTaskReports` `reports` (read-only)

The reports that this task potentially produces.

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

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

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

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

#### `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: `Test.beforeTest()`, `Test.afterTest()`, `Test.beforeSuite()`, `Test.afterSuite()`

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

#### `void` `addTestOutputListener`(`TestOutputListener` listener)

Registers a output listener with this task. Quicker way of hooking into output events is using the `Test.onOutput()` 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.

#### `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` `exclude`(`Closure` excludeSpec)

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.

#### `Test` `exclude`(``Iterable`<`String`>` excludes)

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

#### `Test` `exclude`(``String`...` excludes)

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

#### `Test` `exclude`(``Spec`<`FileTreeElement`>` 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.

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

Sets the name of the executable to use.

#### `Test` `include`(`Closure` includeSpec)

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.

#### `Test` `include`(``Iterable`<`String`>` includes)

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

#### `Test` `include`(``String`...` includes)

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

#### `Test` `include`(``Spec`<`FileTreeElement`>` 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.

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

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

#### `void` `removeTestOutputListener`(`TestOutputListener` listener)

Unregisters a test output listener with this task. This method will only remove listeners that were added by calling `Test.addTestOutputListener()` 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.

To configure JUnit specific options, see `Test.useJUnit()`.

#### `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` `useTestNG`()

Specifies that TestNG should be used to execute the tests.

To configure TestNG specific options, see `Test.useTestNG()`.

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

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

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

### Script block details

#### `options` { }

Configures test framework specific options. Make sure to call `Test.useJUnit()` or `Test.useTestNG()` before using this method.

Delegates to:
  `TestFrameworkOptions` from `options`

#### `reports` { }

Configures the reports that this task potentially produces.

Delegates to:
  `TestTaskReports` from `reports`

#### `testLogging` { }

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 }

Delegates to:
  `TestLoggingContainer` from `testLogging`

#### `jacoco` { }

Configures the `JacocoTaskExtension` added by the jacoco plugin.

Delegates to:
  `JacocoTaskExtension` from `jacoco`