Overview  Package   Class  Deprecated  Index  Help 
Groovy Documentation
FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.gradle.api.tasks.testing
[Java] Class Test

java.lang.Object
  org.gradle.api.internal.ConventionTask
      org.gradle.api.tasks.testing.Test
All Implemented Interfaces:
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
Test(ListenerManager listenerManager, StyledTextOutputFactory textOutputFactory, FileResolver fileResolver, Factory processBuilderFactory, ActorFactory actorFactory, Instantiator instantiator, ProgressLoggerFactory progressLoggerFactory)

 
Method Summary
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}
void disableTestReport()

Disables the HTML test report.
void enableTestReport()

Enables the HTML test report.
Test environment(Map 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 excludes)

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

{@inheritDoc}
Test exclude(Closure excludeSpec)

{@inheritDoc}
Test executable(Object executable)

{@inheritDoc}
void executeTests()

void filter(Action action)

Executes the action against the getFilter().
List 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 getEnvironment()

{@inheritDoc}
Set getExcludes()

Returns the exclude patterns for test execution.
String getExecutable()

{@inheritDoc}
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 getIncludes()

Returns the include patterns for test execution.
List getJvmArgs()

{@inheritDoc}
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.

TestTaskReports getReports()

The reports that this task potentially produces.
Map 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.

File getTestReportDir()

Returns the root folder for the test reports.
File getTestResultsDir()

Returns the root folder for the test results in XML format.
List getTestSrcDirs()

Returns the directories containing the test source.
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 includes)

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

{@inheritDoc}
Test include(Closure includeSpec)

{@inheritDoc}
boolean isScanForTestClasses()

Specifies whether test classes should be detected.

boolean isTestReport()

Specifies whether the test HTML report should be generated.
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 environmentVariables)

{@inheritDoc}
Test setExcludes(Iterable 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 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 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 setTestReport(boolean testReport)

Sets whether the test HTML report should be generated.
void setTestReportDir(File testReportDir)

Sets the root folder for the test reports.
void setTestResultsDir(File testResultsDir)

Sets the root folder for the test results.
void setTestSrcDirs(List testSrcDir)

void setWorkingDir(Object dir)

{@inheritDoc}
Test systemProperties(Map 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

Test

@Inject
public Test(ListenerManager listenerManager, StyledTextOutputFactory textOutputFactory, FileResolver fileResolver, Factory processBuilderFactory, ActorFactory actorFactory, Instantiator instantiator, ProgressLoggerFactory progressLoggerFactory)

 
Method Detail

addTestListener

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.

addTestOutputListener

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.

afterSuite

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.

afterTest

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.

beforeSuite

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.

beforeTest

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.

bootstrapClasspath

public Test bootstrapClasspath(Object... classpath)
{@inheritDoc}

copyTo

public Test copyTo(ProcessForkOptions target)
{@inheritDoc}

copyTo

public Test copyTo(JavaForkOptions target)
{@inheritDoc}

disableTestReport

@SuppressWarnings("UnusedDeclaration")
@Deprecated
public void disableTestReport()
Disables the HTML test report.
deprecated:
Replaced by getReports().getHtml().setEnabled()

enableTestReport

@SuppressWarnings("UnusedDeclaration")
@Deprecated
public void enableTestReport()
Enables the HTML test report.
deprecated:
Replaced by getReports().getHtml().setEnabled()

environment

public Test environment(Map environmentVariables)
{@inheritDoc}

environment

public Test environment(String name, Object value)
{@inheritDoc}

exclude

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)

exclude

public Test exclude(Iterable excludes)
Adds exclude patterns for the files in the test classes directory (e.g. '**F;*Test.class')).
See Also:
setExcludes(Iterable)

exclude

public Test exclude(Spec excludeSpec)
{@inheritDoc}

exclude

public Test exclude(Closure excludeSpec)
{@inheritDoc}

executable

public Test executable(Object executable)
{@inheritDoc}

executeTests

@TaskAction
public void executeTests()

filter

@Incubating
public void filter(Action action)
Executes the action against the getFilter().
Parameters:
action - configuration of the test filter
Since:
1.10

getAllJvmArgs

public List getAllJvmArgs()
{@inheritDoc}

getBinResultsDir

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

getBootstrapClasspath

@Input
public FileCollection getBootstrapClasspath()
{@inheritDoc}

getCandidateClassFiles

@InputFiles
@Input
public FileTree getCandidateClassFiles()
Returns the classes files to scan for test classes.
Returns:
The candidate class files.

getClasspath

@InputFiles
public FileCollection getClasspath()
Returns the classpath to use to execute the tests.

getDebug

public boolean getDebug()
{@inheritDoc}

getDefaultCharacterEncoding

public String getDefaultCharacterEncoding()
{@inheritDoc}

getEnableAssertions

@Input
public boolean getEnableAssertions()
{@inheritDoc}

getEnvironment

public Map getEnvironment()
{@inheritDoc}

getExcludes

public Set getExcludes()
Returns the exclude patterns for test execution.
See Also:
exclude(String...)

getExecutable

@Input
public String getExecutable()
{@inheritDoc}

getFilter

@Incubating
@Nested
public TestFilter getFilter()
Allows filtering tests for execution.
Returns:
filter object
Since:
1.10

getForkEvery

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.

getIgnoreFailures

@Input
public boolean getIgnoreFailures()
{@inheritDoc}

getIncludes

public Set getIncludes()
Returns the include patterns for test execution.
See Also:
include(String...)

getJvmArgs

@Input
public List getJvmArgs()
{@inheritDoc}

getMaxHeapSize

public String getMaxHeapSize()
{@inheritDoc}

getMaxParallelForks

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.

getMinHeapSize

public String getMinHeapSize()
{@inheritDoc}

getOptions

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

getReports

public TestTaskReports getReports()
The reports that this task potentially produces.
Returns:
The reports that this task potentially produces

getSystemProperties

@Input
public Map getSystemProperties()
{@inheritDoc}

getTestClassesDir

public File getTestClassesDir()
Returns the root folder for the compiled test sources.
Returns:
All test class directories to be used.

getTestFramework

public TestFramework getTestFramework()

getTestLogging

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

getTestReportDir

@Deprecated
public File getTestReportDir()
Returns the root folder for the test reports.
deprecated:
Replaced by getReports().getHtml().getDestination()
Returns:
the test report directory, containing the test report mostly in HTML form.

getTestResultsDir

@Deprecated
public File getTestResultsDir()
Returns the root folder for the test results in XML format.
deprecated:
Replaced by getReports().getJunitXml().getDestination()
Returns:
the test result directory, containing the test results in XML format.

getTestSrcDirs

@InputFiles
public List getTestSrcDirs()
Returns the directories containing the test source.

getWorkingDir

@Input
public File getWorkingDir()
{@inheritDoc}

include

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)

include

public Test include(Iterable includes)
Adds include patterns for the files in the test classes directory (e.g. '**F;*Test.class')).
See Also:
setIncludes(Iterable)

include

public Test include(Spec includeSpec)
{@inheritDoc}

include

public Test include(Closure includeSpec)
{@inheritDoc}

isScanForTestClasses

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

isTestReport

@Deprecated
public boolean isTestReport()
Specifies whether the test HTML report should be generated.
deprecated:
Replaced by getReports().getHtml().isEnabled()

jvmArgs

public Test jvmArgs(Iterable arguments)
{@inheritDoc}

jvmArgs

public Test jvmArgs(Object... arguments)
{@inheritDoc}

onOutput

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.

options

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.

removeTestListener

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.

removeTestOutputListener

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.

reports

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

setAllJvmArgs

public void setAllJvmArgs(Iterable arguments)
{@inheritDoc}

setBinResultsDir

@Incubating
public void setBinResultsDir(File binResultsDir)
Sets the root folder for the test results in internal binary format.
Parameters:
binResultsDir - The root folder

setBootstrapClasspath

public void setBootstrapClasspath(FileCollection classpath)
{@inheritDoc}

setClasspath

public void setClasspath(FileCollection classpath)

setDebug

@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}

setDefaultCharacterEncoding

public void setDefaultCharacterEncoding(String defaultCharacterEncoding)
{@inheritDoc}

setEnableAssertions

public void setEnableAssertions(boolean enabled)
{@inheritDoc}

setEnvironment

public void setEnvironment(Map environmentVariables)
{@inheritDoc}

setExcludes

public Test setExcludes(Iterable excludes)
Sets the exclude patterns for test execution.
Parameters:
excludes - The patterns list
See Also:
exclude(String...)

setExecutable

public void setExecutable(Object executable)
{@inheritDoc}

setForkEvery

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.

setIgnoreFailures

public void setIgnoreFailures(boolean ignoreFailures)
{@inheritDoc}

setIncludes

public Test setIncludes(Iterable includes)
Sets the include patterns for test execution.
Parameters:
includes - The patterns list
See Also:
include(String...)

setJvmArgs

public void setJvmArgs(Iterable arguments)
{@inheritDoc}

setMaxHeapSize

public void setMaxHeapSize(String heapSize)
{@inheritDoc}

setMaxParallelForks

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.

setMinHeapSize

public void setMinHeapSize(String heapSize)
{@inheritDoc}

setScanForTestClasses

public void setScanForTestClasses(boolean scanForTestClasses)

setSystemProperties

public void setSystemProperties(Map properties)
{@inheritDoc}

setTestClassesDir

public void setTestClassesDir(File testClassesDir)
Sets the root folder for the compiled test sources.
Parameters:
testClassesDir - The root folder

setTestNameIncludePattern

@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

setTestReport

@Deprecated
public void setTestReport(boolean testReport)
Sets whether the test HTML report should be generated.
deprecated:
Replaced by getReports().getHtml().setEnabled()

setTestReportDir

@Deprecated
public void setTestReportDir(File testReportDir)
Sets the root folder for the test reports.
deprecated:
Replaced by getReports().getHtml().setDestination()
Parameters:
testReportDir - The root folder

setTestResultsDir

@Deprecated
public void setTestResultsDir(File testResultsDir)
Sets the root folder for the test results.
deprecated:
Replaced by getReports().getJunitXml().setDestination()
Parameters:
testResultsDir - The root folder

setTestSrcDirs

public void setTestSrcDirs(List testSrcDir)

setWorkingDir

public void setWorkingDir(Object dir)
{@inheritDoc}

systemProperties

public Test systemProperties(Map properties)
{@inheritDoc}

systemProperty

public Test systemProperty(String name, Object value)
{@inheritDoc}

testFramework

public TestFramework testFramework(Closure testFrameworkConfigure)

testLogging

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

useJUnit

public void useJUnit()
Specifies that JUnit should be used to execute the tests.

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

useJUnit

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.

useTestNG

public void useTestNG()
Specifies that TestNG should be used to execute the tests.

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

useTestNG

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.

workingDir

public Test workingDir(Object dir)
{@inheritDoc}

 

Gradle API 1.12