Package: org.gradle.api.tasks.testing

## [Java] Class Test

- org.gradle.api.tasks.testing.Test

- All Implemented Interfaces and Traits:
    JavaForkOptions, PatternFilterable, Reporting, VerificationTask

      public class Test
      extends ConventionTask

  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 getDebug()) in an ad-hoc manner by supplying the `--debug-jvm` switch when invoking the build.

       gradle someTestTask --debug-jvm

- - ### Constructor Summary

    Constructors
    Constructor and description
    `Test ()`

  - ### Methods Summary

    Methods
    Type | Name and description
    --- | ---
    `void` | `addTestListener(TestListener listener)` Registers a test listener with this task.
    `void` | `addTestOutputListener(TestOutputListener listener)` Registers a output listener with this task.
    `void` | `afterSuite(Closure closure)`
    `void` | `afterTest(Closure closure)` Adds a closure to be notified after a test has executed.
    `void` | `beforeSuite(Closure closure)`
    `void` | `beforeTest(Closure closure)` Adds a closure to be notified before a test is executed.
    `Test` | `bootstrapClasspath(Object... classpath)` {@inheritDoc}
    `Test` | `copyTo(ProcessForkOptions target)` {@inheritDoc}
    `Test` | `copyTo(JavaForkOptions target)` {@inheritDoc}
    `Test` | `environment(Map<String, ?> environmentVariables)` {@inheritDoc}
    `Test` | `environment(String name, Object value)` {@inheritDoc}
    `Test` | `exclude(String... excludes)` Adds exclude patterns for the files in the test classes directory (e.g. '**F;*Test.class')).
    `Test` | `exclude(Iterable<String> excludes)` Adds exclude patterns for the files in the test classes directory (e.g. '**F;*Test.class')).
    `Test` | `exclude(Spec<FileTreeElement> excludeSpec)` {@inheritDoc}
    `Test` | `exclude(Closure excludeSpec)` {@inheritDoc}
    `Test` | `executable(Object executable)` {@inheritDoc}
    `void` | `executeTests()`
    `void` | `filter(Action<TestFilter> action)` Executes the action against the getFilter().
    `protected ActorFactory` | `getActorFactory()`
    `List<String>` | `getAllJvmArgs()` {@inheritDoc}
    `File` | `getBinResultsDir()` Returns the root folder for the test results in internal binary format.
    `FileCollection` | `getBootstrapClasspath()` {@inheritDoc}
    `FileTree` | `getCandidateClassFiles()` Returns the classes files to scan for test classes.
    `FileCollection` | `getClasspath()` Returns the classpath to use to execute the tests.
    `boolean` | `getDebug()` {@inheritDoc}
    `String` | `getDefaultCharacterEncoding()` {@inheritDoc}
    `boolean` | `getEnableAssertions()` {@inheritDoc}
    `Map<String, Object>` | `getEnvironment()` {@inheritDoc}
    `Set<String>` | `getExcludes()` Returns the exclude patterns for test execution.
    `String` | `getExecutable()` {@inheritDoc}
    `protected FileResolver` | `getFileResolver()`
    `TestFilter` | `getFilter()` Allows filtering tests for execution.
    `long` | `getForkEvery()` Returns the maximum number of test classes to execute in a forked test process.
    `boolean` | `getIgnoreFailures()` {@inheritDoc}
    `Set<String>` | `getIncludes()` Returns the include patterns for test execution.
    `protected Instantiator` | `getInstantiator()`
    `List<String>` | `getJvmArgs()` {@inheritDoc}
    `protected ListenerManager` | `getListenerManager()`
    `String` | `getMaxHeapSize()` {@inheritDoc}
    `int` | `getMaxParallelForks()` Returns the maximum number of forked test processes to execute in parallel.
    `String` | `getMinHeapSize()` {@inheritDoc}
    `TestFrameworkOptions` | `getOptions()` Returns test framework specific options.
    `protected Factory<WorkerProcessBuilder>` | `getProcessBuilderFactory()`
    `protected ProgressLoggerFactory` | `getProgressLoggerFactory()`
    `TestTaskReports` | `getReports()` The reports that this task potentially produces.
    `Map<String, Object>` | `getSystemProperties()` {@inheritDoc}
    `File` | `getTestClassesDir()` Returns the root folder for the compiled test sources.
    `TestFramework` | `getTestFramework()`
    `TestLoggingContainer` | `getTestLogging()` Allows to set options related to which test events are logged to the console, and on which detail level.
    `List<File>` | `getTestSrcDirs()` Returns the directories containing the test source.
    `protected StyledTextOutputFactory` | `getTextOutputFactory()`
    `File` | `getWorkingDir()` {@inheritDoc}
    `Test` | `include(String... includes)` Adds include patterns for the files in the test classes directory (e.g. '**F;*Test.class')).
    `Test` | `include(Iterable<String> includes)` Adds include patterns for the files in the test classes directory (e.g. '**F;*Test.class')).
    `Test` | `include(Spec<FileTreeElement> includeSpec)` {@inheritDoc}
    `Test` | `include(Closure includeSpec)` {@inheritDoc}
    `boolean` | `isScanForTestClasses()` Specifies whether test classes should be detected.
    `Test` | `jvmArgs(Iterable<?> arguments)` {@inheritDoc}
    `Test` | `jvmArgs(Object... arguments)` {@inheritDoc}
    `void` | `onOutput(Closure closure)` Adds a closure to be notified when output from the test received.
    `TestFrameworkOptions` | `options(Closure testFrameworkConfigure)` Configures test framework specific options.
    `void` | `removeTestListener(TestListener listener)` Unregisters a test listener with this task.
    `void` | `removeTestOutputListener(TestOutputListener listener)` Unregisters a test output listener with this task.
    `TestTaskReports` | `reports(Closure closure)` Configures the reports that this task potentially produces.
    `void` | `setAllJvmArgs(Iterable<?> arguments)` {@inheritDoc}
    `void` | `setBinResultsDir(File binResultsDir)` Sets the root folder for the test results in internal binary format.
    `void` | `setBootstrapClasspath(FileCollection classpath)` {@inheritDoc}
    `void` | `setClasspath(FileCollection classpath)`
    `void` | `setDebug(boolean enabled)` {@inheritDoc}
    `void` | `setDefaultCharacterEncoding(String defaultCharacterEncoding)` {@inheritDoc}
    `void` | `setEnableAssertions(boolean enabled)` {@inheritDoc}
    `void` | `setEnvironment(Map<String, ?> environmentVariables)` {@inheritDoc}
    `Test` | `setExcludes(Iterable<String> excludes)` Sets the exclude patterns for test execution.
    `void` | `setExecutable(Object executable)` {@inheritDoc}
    `void` | `setForkEvery(Long forkEvery)` Sets the maximum number of test classes to execute in a forked test process.
    `void` | `setIgnoreFailures(boolean ignoreFailures)` {@inheritDoc}
    `Test` | `setIncludes(Iterable<String> includes)` Sets the include patterns for test execution.
    `void` | `setJvmArgs(Iterable<?> arguments)` {@inheritDoc}
    `void` | `setMaxHeapSize(String heapSize)` {@inheritDoc}
    `void` | `setMaxParallelForks(int maxParallelForks)` Sets the maximum number of forked test processes to execute in parallel.
    `void` | `setMinHeapSize(String heapSize)` {@inheritDoc}
    `void` | `setScanForTestClasses(boolean scanForTestClasses)`
    `void` | `setSystemProperties(Map<String, ?> properties)` {@inheritDoc}
    `void` | `setTestClassesDir(File testClassesDir)` Sets the root folder for the compiled test sources.
    `Test` | `setTestNameIncludePattern(String testNamePattern)` Sets the test name patterns to be included in execution.
    `void` | `setTestSrcDirs(List<File> testSrcDir)`
    `void` | `setWorkingDir(Object dir)` {@inheritDoc}
    `Test` | `systemProperties(Map<String, ?> properties)` {@inheritDoc}
    `Test` | `systemProperty(String name, Object value)` {@inheritDoc}
    `TestFramework` | `testFramework(Closure testFrameworkConfigure)`
    `void` | `testLogging(Closure closure)` Allows configuring the logging of the test execution, for example log eagerly the standard output, etc.
    `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, configuring JUnit specific options.
    `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, configuring TestNG specific options.
    `Test` | `workingDir(Object dir)` {@inheritDoc}

- - ### Constructor Detail

    - #### public Test()

  - ### Method Detail

    - #### public void addTestListener(TestListener listener)

      Registers a test listener with this task. Consider also the following handy methods for quicker hooking into test execution: beforeTest(groovy.lang.Closure), afterTest(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 Gradle.addListener.

      Parameters:
        `listener` - The listener to add.

    - #### public void addTestOutputListener(TestOutputListener listener)

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

      Parameters:
        `listener` - The listener to add.

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

      Parameters:
        `closure` - The closure to call.

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

      Parameters:
        `closure` - The closure to call.

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

      Parameters:
        `closure` - The closure to call.

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

      Parameters:
        `closure` - The closure to call.

    - #### public Test bootstrapClasspath(Object... classpath)

      {@inheritDoc}

    - #### public Test copyTo(ProcessForkOptions target)

      {@inheritDoc}

    - #### public Test copyTo(JavaForkOptions target)

      {@inheritDoc}

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

      {@inheritDoc}

    - #### public Test environment(String name, Object value)

      {@inheritDoc}

    - #### public Test exclude(String... excludes)

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

      See Also:
        setExcludes(Iterable)

    - #### public Test exclude(Iterable<String> excludes)

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

      See Also:
        setExcludes(Iterable)

    - #### public Test exclude(Spec<FileTreeElement> excludeSpec)

      {@inheritDoc}

    - #### public Test exclude(Closure excludeSpec)

      {@inheritDoc}

    - #### public Test executable(Object executable)

      {@inheritDoc}

    - #### @TaskAction public void executeTests()

    - #### @Incubating public void filter(Action<TestFilter> action)

      Executes the action against the getFilter().

      Parameters:
        `action` - configuration of the test filter
      Since:
        1.10

    - #### @Inject protected ActorFactory getActorFactory()

    - #### public List<String> getAllJvmArgs()

      {@inheritDoc}

    - #### @OutputDirectory @Incubating public File getBinResultsDir()

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

      Returns:
        the test result directory, containing the test results in binary format.

    - #### @Input public FileCollection getBootstrapClasspath()

      {@inheritDoc}

    - #### @InputFiles @Input public FileTree getCandidateClassFiles()

      Returns the classes files to scan for test classes.

      Returns:
        The candidate class files.

    - #### @InputFiles public FileCollection getClasspath()

      Returns the classpath to use to execute the tests.

    - #### public boolean getDebug()

      {@inheritDoc}

    - #### public String getDefaultCharacterEncoding()

      {@inheritDoc}

    - #### @Input public boolean getEnableAssertions()

      {@inheritDoc}

    - #### public Map<String, Object> getEnvironment()

      {@inheritDoc}

    - #### public Set<String> getExcludes()

      Returns the exclude patterns for test execution.

      See Also:
        exclude(String...)

    - #### @Input public String getExecutable()

      {@inheritDoc}

    - #### @Inject protected FileResolver getFileResolver()

    - #### @Incubating @Nested public TestFilter getFilter()

      Allows filtering tests for execution.

      Returns:
        filter object
      Since:
        1.10

    - #### public long getForkEvery()

      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).

      Returns:
        The maximum number of test classes. Returns 0 when there is no maximum.

    - #### @Input public boolean getIgnoreFailures()

      {@inheritDoc}

    - #### public Set<String> getIncludes()

      Returns the include patterns for test execution.

      See Also:
        include(String...)

    - #### @Inject protected Instantiator getInstantiator()

    - #### @Input public List<String> getJvmArgs()

      {@inheritDoc}

    - #### @Inject protected ListenerManager getListenerManager()

    - #### public String getMaxHeapSize()

      {@inheritDoc}

    - #### public int getMaxParallelForks()

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

      Returns:
        The maximum number of forked test processes.

    - #### public String getMinHeapSize()

      {@inheritDoc}

    - #### @Nested public TestFrameworkOptions getOptions()

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

      Returns:
        The test framework options.

    - #### @Inject protected Factory<WorkerProcessBuilder> getProcessBuilderFactory()

    - #### @Inject protected ProgressLoggerFactory getProgressLoggerFactory()

    - #### public TestTaskReports getReports()

      The reports that this task potentially produces.

      Returns:
        The reports that this task potentially produces

    - #### @Input public Map<String, Object> getSystemProperties()

      {@inheritDoc}

    - #### public File getTestClassesDir()

      Returns the root folder for the compiled test sources.

      Returns:
        All test class directories to be used.

    - #### public TestFramework getTestFramework()

    - #### public TestLoggingContainer getTestLogging()

      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.
      Returns:
        this

    - #### @InputFiles public List<File> getTestSrcDirs()

      Returns the directories containing the test source.

    - #### @Inject protected StyledTextOutputFactory getTextOutputFactory()

    - #### @Input public File getWorkingDir()

      {@inheritDoc}

    - #### public Test include(String... includes)

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

      See Also:
        setIncludes(Iterable)

    - #### public Test include(Iterable<String> includes)

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

      See Also:
        setIncludes(Iterable)

    - #### public Test include(Spec<FileTreeElement> includeSpec)

      {@inheritDoc}

    - #### public Test include(Closure includeSpec)

      {@inheritDoc}

    - #### @Input public boolean isScanForTestClasses()

      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.

    - #### public Test jvmArgs(Iterable<?> arguments)

      {@inheritDoc}

    - #### public Test jvmArgs(Object... arguments)

      {@inheritDoc}

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

      Parameters:
        `closure` - The closure to call.

    - #### public TestFrameworkOptions options(Closure testFrameworkConfigure)

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

      Returns:
        The test framework options.

    - #### public void removeTestListener(TestListener listener)

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

      Parameters:
        `listener` - The listener to remove.

    - #### public void removeTestOutputListener(TestOutputListener listener)

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

      Parameters:
        `listener` - The listener to remove.

    - #### public TestTaskReports reports(Closure closure)

      Configures the reports that this task potentially produces.

      Parameters:
        `closure` - The configuration
      Returns:
        The reports that this task potentially produces

    - #### public void setAllJvmArgs(Iterable<?> arguments)

      {@inheritDoc}

    - #### @Incubating public void setBinResultsDir(File binResultsDir)

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

      Parameters:
        `binResultsDir` - The root folder

    - #### public void setBootstrapClasspath(FileCollection classpath)

      {@inheritDoc}

    - #### public void setClasspath(FileCollection classpath)

    - #### @Option(option = "debug-jvm", description = "Enable debugging for the test process. The process is started suspended and listening on port 5005. [INCUBATING]") public void setDebug(boolean enabled)

      {@inheritDoc}

    - #### public void setDefaultCharacterEncoding(String defaultCharacterEncoding)

      {@inheritDoc}

    - #### public void setEnableAssertions(boolean enabled)

      {@inheritDoc}

    - #### public void setEnvironment(Map<String, ?> environmentVariables)

      {@inheritDoc}

    - #### public Test setExcludes(Iterable<String> excludes)

      Sets the exclude patterns for test execution.

      Parameters:
        `excludes` - The patterns list
      See Also:
        exclude(String...)

    - #### public void setExecutable(Object executable)

      {@inheritDoc}

    - #### public void setForkEvery(Long forkEvery)

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

      Parameters:
        `forkEvery` - The maximum number of test classes. Use null or 0 to specify no maximum.

    - #### public void setIgnoreFailures(boolean ignoreFailures)

      {@inheritDoc}

    - #### public Test setIncludes(Iterable<String> includes)

      Sets the include patterns for test execution.

      Parameters:
        `includes` - The patterns list
      See Also:
        include(String...)

    - #### public void setJvmArgs(Iterable<?> arguments)

      {@inheritDoc}

    - #### public void setMaxHeapSize(String heapSize)

      {@inheritDoc}

    - #### public void setMaxParallelForks(int maxParallelForks)

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

      Parameters:
        `maxParallelForks` - The maximum number of forked test processes.

    - #### public void setMinHeapSize(String heapSize)

      {@inheritDoc}

    - #### public void setScanForTestClasses(boolean scanForTestClasses)

    - #### public void setSystemProperties(Map<String, ?> properties)

      {@inheritDoc}

    - #### public void setTestClassesDir(File testClassesDir)

      Sets the root folder for the compiled test sources.

      Parameters:
        `testClassesDir` - The root folder

    - #### @Option(option = "tests", description = "Sets test class or method name to be included, '*' is supported.") @Incubating public Test setTestNameIncludePattern(String testNamePattern)

      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

    - #### public void setTestSrcDirs(List<File> testSrcDir)

    - #### public void setWorkingDir(Object dir)

      {@inheritDoc}

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

      {@inheritDoc}

    - #### public Test systemProperty(String name, Object value)

      {@inheritDoc}

    - #### public TestFramework testFramework(Closure testFrameworkConfigure)

    - #### public void testLogging(Closure closure)

      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 }

      Parameters:
        `closure` - configure closure

    - #### public void useJUnit()

      Specifies that JUnit should be used to execute the tests.

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

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

      Parameters:
        `testFrameworkConfigure` - A closure used to configure the JUnit options.

    - #### public void useTestNG()

      Specifies that TestNG should be used to execute the tests.

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

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

      Parameters:
        `testFrameworkConfigure` - A closure used to configure the TestNG options.

    - #### public Test workingDir(Object dir)

      {@inheritDoc}