surefire:test

Full name:

org.apache.maven.plugins:maven-surefire-plugin:2.9:test

Description:

Run tests using Surefire.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: test.

Required Parameters

Name Type Since Description
testSourceDirectory File 2.2 The test source directory containing test class sources.
Default value is: ${project.build.testSourceDirectory}.

Optional Parameters

Name Type Since Description
additionalClasspathElements List 2.4 Additional elements to be appended to the classpath.
argLine String 2.1 Arbitrary JVM options to set on the command line.
basedir File - The base directory of the project being tested. This can be obtained in your unit test via System.getProperty("basedir").
Default value is: ${basedir}.
childDelegation boolean 2.1 When false it makes tests run using the standard classloader delegation instead of the default Maven isolated classloader. Only used when forking (forkMode is not "none").
Setting it to false helps with some problems caused by conflicts between xml parsers in the classpath and the Java 5 provider parser.
Default value is: false.
classesDirectory File - The directory containing generated classes of the project being tested. This will be included after the test classes in the test classpath.
Default value is: ${project.build.outputDirectory}.
classpathDependencyExcludes List 2.6 List of dependencies to exclude from the test classpath. Each dependency string must follow the format groupId:artifactId. For example: org.acme:project-a
classpathDependencyScopeExclude String 2.6 A dependency scope to exclude from the test classpath. The scope can be one of the following scopes:

  • compile - system, provided, compile
  • runtime - compile, runtime
  • test - system, provided, compile, runtime, test

debugForkedProcess String 2.4 Attach a debugger to the forked JVM. If set to "true", the process will suspend and wait for a debugger to attach on port 5005. If set to some other string, that string will be appended to the argLine, allowing you to configure arbitrary debuggability options (without overwriting the other options specified through the argLine parameter).
disableXmlReport boolean 2.2 Flag to disable the generation of report files in xml format.
Default value is: false.
enableAssertions boolean 2.3.1 By default, Surefire enables JVM assertions for the execution of your test cases. To disable the assertions, set this flag to "false".
Default value is: true.
environmentVariables Map 2.1.3 Additional environment variables to set on the command line.
excludedGroups String 2.2 (TestNG only) Excluded groups. Any methods/classes/etc with one of the groups specified in this list will specifically not be run.
This parameter is ignored if the suiteXmlFiles parameter is specified.
excludes List - A list of <exclude> elements specifying the tests (by pattern) that should be excluded in testing. When not specified and when the test parameter is not specified, the default excludes will be
<excludes>
 <exclude>**/*$*</exclude>
</excludes>
(which excludes all inner classes).
This parameter is ignored if the TestNG suiteXmlFiles parameter is specified.
failIfNoTests Boolean 2.4 Set this to "true" to cause a failure if there are no tests to run. Defaults to "false".
forkMode String 2.1 Option to specify the forking mode. Can be "never", "once" or "always". "none" and "pertest" are also accepted for backwards compatibility. "always" forks for each test-class.
Default value is: once.
forkedProcessTimeoutInSeconds int 2.4 Kill the forked test process after a certain number of seconds. If set to 0, wait forever for the process, never timing out.
groups String 2.2 (TestNG only) Groups for this test. Only classes/methods/etc decorated with one of the groups specified here will be included in test run, if specified.
This parameter is ignored if the suiteXmlFiles parameter is specified.
includes List - A list of <include> elements specifying the tests (by pattern) that should be included in testing. When not specified and when the test parameter is not specified, the default includes will be
<includes>
 <include>**/Test*.java</include>
 <include>**/*Test.java</include>
 <include>**/*TestCase.java</include>
</includes>
This parameter is ignored if the TestNG suiteXmlFiles parameter is specified.
junitArtifactName String 2.3.1 Allows you to specify the name of the JUnit artifact. If not set, junit:junit will be used.
Default value is: junit:junit.
jvm String 2.1 Option to specify the jvm (or path to the java executable) to use with the forking options. For the default, the jvm will be a new instance of the same VM as the one used to run Maven. JVM settings are not inherited from MAVEN_OPTS.
objectFactory String 2.5 (TestNG only) Define the factory class used to create all test instances.
parallel String 2.2 (TestNG only) When you use the parallel attribute, TestNG will try to run all your test methods in separate threads, except for methods that depend on each other, which will be run in the same thread in order to respect their order of execution.

(JUnit 4.7 provider) Supports values "classes"/"methods"/"both" to run in separate threads, as controlled by threadCount.
perCoreThreadCount boolean 2.5 (JUnit 4.7 provider) Indicates that threadCount is per cpu core.
Default value is: true.
printSummary boolean - Option to print summary of test suites or just print the test cases that have errors.
Default value is: true.
properties Properties 2.4 List of properties for configuring all TestNG related configurations. This is the new preferred method of configuring TestNG.
redirectTestOutputToFile boolean 2.3 Set this to "true" to redirect the unit test standard output to a file (found in reportsDirectory/testName-output.txt).
Default value is: false.
remoteRepositories List 2.2 The remote plugin repositories declared in the POM.
reportFormat String - Selects the formatting for the test report to be generated. Can be set as "brief" or "plain".
Default value is: brief.
reportsDirectory File - Base directory where all reports are written to.
Default value is: ${project.build.directory}/surefire-reports.
runOrder String 2.7 Defines the order the tests will be run in. Supported values are "alphabetical", "reversealphabetical", "random", "hourly" (alphabetical on even hours, reverse alphabetical on odd hours) and "filesystem".

Odd/Even for hourly is determined at the time the of scanning the classpath, meaning it could change during a multi-module build.
Default value is: filesystem.
skip boolean - Set this to "true" to bypass unit tests entirely. Its use is NOT RECOMMENDED, especially if you enable it using the "maven.test.skip" property, because maven.test.skip disables both running the tests and compiling the tests. Consider using the skipTests parameter instead.
Default value is: false.
skipExec boolean 2.3 Deprecated. Use skipTests instead.
skipTests boolean 2.4 Set this to "true" to skip running tests, but still compile them. Its use is NOT RECOMMENDED, but quite convenient on occasion.
Default value is: false.
suiteXmlFiles File[] 2.2 (TestNG only) List of <suiteXmlFile> elements specifying TestNG suite xml file locations. Note that suiteXmlFiles is incompatible with several other parameters of this plugin, like includes/excludes.
This parameter is ignored if the test parameter is specified (allowing you to run a single test instead of an entire suite).
systemProperties Properties - Deprecated. Use systemPropertyVariables instead.
systemPropertiesFile File 2.8.2 List of System properties, loaded from a file, to pass to the JUnit tests.
systemPropertyVariables Map 2.5 List of System properties to pass to the JUnit tests.
test String - Specify this parameter to run individual tests by file name, overriding the includes/excludes parameters. Each pattern you specify here will be used to create an include pattern formatted like **/${test}.java, so you can just type "-Dtest=MyTest" to run a single test called "foo/MyTest.java".
This parameter overrides the includes/excludes parameters, and the TestNG suiteXmlFiles parameter.

since 2.7.3 You can execute a limited number of method in the test with adding #myMethod or #my*ethod. Si type "-Dtest=MyTest#myMethod" supported for junit 4.x and testNg
testClassesDirectory File - The directory containing generated test classes of the project being tested. This will be included at the beginning of the test classpath. *
Default value is: ${project.build.testOutputDirectory}.
testFailureIgnore boolean - Set this to "true" to ignore a failure during testing. Its use is NOT RECOMMENDED, but quite convenient on occasion.
Default value is: false.
testNGArtifactName String 2.3.1 Allows you to specify the name of the TestNG artifact. If not set, org.testng:testng will be used.
Default value is: org.testng:testng.
threadCount int 2.2 (TestNG/JUnit 4.7 provider only) The attribute thread-count allows you to specify how many threads should be allocated for this execution. Only makes sense to use in conjunction with the parallel parameter.
trimStackTrace boolean 2.2 Whether to trim the stack trace in the reports to just the lines within the test, or show the full trace.
Default value is: true.
useFile boolean - Option to generate a file test report or just output the test report to the console.
Default value is: true.
useManifestOnlyJar boolean 2.4.3 By default, Surefire forks your tests using a manifest-only JAR; set this parameter to "false" to force it to launch your tests with a plain old Java classpath. (See http://maven.apache.org/plugins/maven-surefire-plugin/examples/class-loading.html for a more detailed explanation of manifest-only JARs and their benefits.)

Beware, setting this to "false" may cause your tests to fail on Windows if your classpath is too long.
Default value is: true.
useSystemClassLoader boolean 2.3 Option to pass dependencies to the system's classloader instead of using an isolated class loader when forking. Prevents problems with JDKs which implement the service provider lookup mechanism by using the system's classloader.
Default value is: true.
useUnlimitedThreads boolean 2.5 (JUnit 4.7 provider) Indicates that the thread pool will be unlimited. The parallel parameter and the actual number of classes/methods will decide. Setting this to "true" effectively disables perCoreThreadCount and threadCount. Defaults to "false".
Default value is: false.
workingDirectory File 2.1.3 Command line working directory.

Parameter Details

additionalClasspathElements:

Additional elements to be appended to the classpath.
  • Type: java.util.List
  • Since: 2.4
  • Required: No

argLine:

Arbitrary JVM options to set on the command line.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • Expression: ${argLine}

basedir:

The base directory of the project being tested. This can be obtained in your unit test via System.getProperty("basedir").
  • Type: java.io.File
  • Required: No
  • Default: ${basedir}

childDelegation:

When false it makes tests run using the standard classloader delegation instead of the default Maven isolated classloader. Only used when forking (forkMode is not "none").
Setting it to false helps with some problems caused by conflicts between xml parsers in the classpath and the Java 5 provider parser.
  • Type: boolean
  • Since: 2.1
  • Required: No
  • Expression: ${childDelegation}
  • Default: false

classesDirectory:

The directory containing generated classes of the project being tested. This will be included after the test classes in the test classpath.
  • Type: java.io.File
  • Required: No
  • Default: ${project.build.outputDirectory}

classpathDependencyExcludes:

List of dependencies to exclude from the test classpath. Each dependency string must follow the format groupId:artifactId. For example: org.acme:project-a
  • Type: java.util.List
  • Since: 2.6
  • Required: No

classpathDependencyScopeExclude:

A dependency scope to exclude from the test classpath. The scope can be one of the following scopes:

  • compile - system, provided, compile
  • runtime - compile, runtime
  • test - system, provided, compile, runtime, test
  • Type: java.lang.String
  • Since: 2.6
  • Required: No

debugForkedProcess:

Attach a debugger to the forked JVM. If set to "true", the process will suspend and wait for a debugger to attach on port 5005. If set to some other string, that string will be appended to the argLine, allowing you to configure arbitrary debuggability options (without overwriting the other options specified through the argLine parameter).
  • Type: java.lang.String
  • Since: 2.4
  • Required: No
  • Expression: ${maven.surefire.debug}

disableXmlReport:

Flag to disable the generation of report files in xml format.
  • Type: boolean
  • Since: 2.2
  • Required: No
  • Expression: ${disableXmlReport}
  • Default: false

enableAssertions:

By default, Surefire enables JVM assertions for the execution of your test cases. To disable the assertions, set this flag to "false".
  • Type: boolean
  • Since: 2.3.1
  • Required: No
  • Expression: ${enableAssertions}
  • Default: true

environmentVariables:

Additional environment variables to set on the command line.
  • Type: java.util.Map
  • Since: 2.1.3
  • Required: No

excludedGroups:

(TestNG only) Excluded groups. Any methods/classes/etc with one of the groups specified in this list will specifically not be run.
This parameter is ignored if the suiteXmlFiles parameter is specified.
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • Expression: ${excludedGroups}

excludes:

A list of <exclude> elements specifying the tests (by pattern) that should be excluded in testing. When not specified and when the test parameter is not specified, the default excludes will be
<excludes>
 <exclude>**/*$*</exclude>
</excludes>
(which excludes all inner classes).
This parameter is ignored if the TestNG suiteXmlFiles parameter is specified.
  • Type: java.util.List
  • Required: No

failIfNoTests:

Set this to "true" to cause a failure if there are no tests to run. Defaults to "false".
  • Type: java.lang.Boolean
  • Since: 2.4
  • Required: No
  • Expression: ${failIfNoTests}

forkMode:

Option to specify the forking mode. Can be "never", "once" or "always". "none" and "pertest" are also accepted for backwards compatibility. "always" forks for each test-class.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • Expression: ${forkMode}
  • Default: once

forkedProcessTimeoutInSeconds:

Kill the forked test process after a certain number of seconds. If set to 0, wait forever for the process, never timing out.
  • Type: int
  • Since: 2.4
  • Required: No
  • Expression: ${surefire.timeout}

groups:

(TestNG only) Groups for this test. Only classes/methods/etc decorated with one of the groups specified here will be included in test run, if specified.
This parameter is ignored if the suiteXmlFiles parameter is specified.
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • Expression: ${groups}

includes:

A list of <include> elements specifying the tests (by pattern) that should be included in testing. When not specified and when the test parameter is not specified, the default includes will be
<includes>
 <include>**/Test*.java</include>
 <include>**/*Test.java</include>
 <include>**/*TestCase.java</include>
</includes>
This parameter is ignored if the TestNG suiteXmlFiles parameter is specified.
  • Type: java.util.List
  • Required: No

junitArtifactName:

Allows you to specify the name of the JUnit artifact. If not set, junit:junit will be used.
  • Type: java.lang.String
  • Since: 2.3.1
  • Required: No
  • Expression: ${junitArtifactName}
  • Default: junit:junit

jvm:

Option to specify the jvm (or path to the java executable) to use with the forking options. For the default, the jvm will be a new instance of the same VM as the one used to run Maven. JVM settings are not inherited from MAVEN_OPTS.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • Expression: ${jvm}

objectFactory:

(TestNG only) Define the factory class used to create all test instances.
  • Type: java.lang.String
  • Since: 2.5
  • Required: No
  • Expression: ${objectFactory}

parallel:

(TestNG only) When you use the parallel attribute, TestNG will try to run all your test methods in separate threads, except for methods that depend on each other, which will be run in the same thread in order to respect their order of execution.

(JUnit 4.7 provider) Supports values "classes"/"methods"/"both" to run in separate threads, as controlled by threadCount.
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • Expression: ${parallel}

perCoreThreadCount:

(JUnit 4.7 provider) Indicates that threadCount is per cpu core.
  • Type: boolean
  • Since: 2.5
  • Required: No
  • Expression: ${perCoreThreadCount}
  • Default: true

printSummary:

Option to print summary of test suites or just print the test cases that have errors.
  • Type: boolean
  • Required: No
  • Expression: ${surefire.printSummary}
  • Default: true

properties:

List of properties for configuring all TestNG related configurations. This is the new preferred method of configuring TestNG.
  • Type: java.util.Properties
  • Since: 2.4
  • Required: No

redirectTestOutputToFile:

Set this to "true" to redirect the unit test standard output to a file (found in reportsDirectory/testName-output.txt).
  • Type: boolean
  • Since: 2.3
  • Required: No
  • Expression: ${maven.test.redirectTestOutputToFile}
  • Default: false

remoteRepositories:

The remote plugin repositories declared in the POM.
  • Type: java.util.List
  • Since: 2.2
  • Required: No
  • Expression: ${project.pluginArtifactRepositories}

reportFormat:

Selects the formatting for the test report to be generated. Can be set as "brief" or "plain".
  • Type: java.lang.String
  • Required: No
  • Expression: ${surefire.reportFormat}
  • Default: brief

reportsDirectory:

Base directory where all reports are written to.
  • Type: java.io.File
  • Required: No
  • Default: ${project.build.directory}/surefire-reports

runOrder:

Defines the order the tests will be run in. Supported values are "alphabetical", "reversealphabetical", "random", "hourly" (alphabetical on even hours, reverse alphabetical on odd hours) and "filesystem".

Odd/Even for hourly is determined at the time the of scanning the classpath, meaning it could change during a multi-module build.
  • Type: java.lang.String
  • Since: 2.7
  • Required: No
  • Default: filesystem

skip:

Set this to "true" to bypass unit tests entirely. Its use is NOT RECOMMENDED, especially if you enable it using the "maven.test.skip" property, because maven.test.skip disables both running the tests and compiling the tests. Consider using the skipTests parameter instead.
  • Type: boolean
  • Required: No
  • Expression: ${maven.test.skip}
  • Default: false

skipExec:

Deprecated. Use skipTests instead.
This old parameter is just like skipTests, but bound to the old property "maven.test.skip.exec".
  • Type: boolean
  • Since: 2.3
  • Required: No
  • Expression: ${maven.test.skip.exec}

skipTests:

Set this to "true" to skip running tests, but still compile them. Its use is NOT RECOMMENDED, but quite convenient on occasion.
  • Type: boolean
  • Since: 2.4
  • Required: No
  • Expression: ${skipTests}
  • Default: false

suiteXmlFiles:

(TestNG only) List of <suiteXmlFile> elements specifying TestNG suite xml file locations. Note that suiteXmlFiles is incompatible with several other parameters of this plugin, like includes/excludes.
This parameter is ignored if the test parameter is specified (allowing you to run a single test instead of an entire suite).
  • Type: java.io.File[]
  • Since: 2.2
  • Required: No

systemProperties:

Deprecated. Use systemPropertyVariables instead.
List of System properties to pass to the JUnit tests.
  • Type: java.util.Properties
  • Required: No

systemPropertiesFile:

List of System properties, loaded from a file, to pass to the JUnit tests.
  • Type: java.io.File
  • Since: 2.8.2
  • Required: No

systemPropertyVariables:

List of System properties to pass to the JUnit tests.
  • Type: java.util.Map
  • Since: 2.5
  • Required: No

test:

Specify this parameter to run individual tests by file name, overriding the includes/excludes parameters. Each pattern you specify here will be used to create an include pattern formatted like **/${test}.java, so you can just type "-Dtest=MyTest" to run a single test called "foo/MyTest.java".
This parameter overrides the includes/excludes parameters, and the TestNG suiteXmlFiles parameter.

since 2.7.3 You can execute a limited number of method in the test with adding #myMethod or #my*ethod. Si type "-Dtest=MyTest#myMethod" supported for junit 4.x and testNg
  • Type: java.lang.String
  • Required: No
  • Expression: ${test}

testClassesDirectory:

The directory containing generated test classes of the project being tested. This will be included at the beginning of the test classpath. *
  • Type: java.io.File
  • Required: No
  • Default: ${project.build.testOutputDirectory}

testFailureIgnore:

Set this to "true" to ignore a failure during testing. Its use is NOT RECOMMENDED, but quite convenient on occasion.
  • Type: boolean
  • Required: No
  • Expression: ${maven.test.failure.ignore}
  • Default: false

testNGArtifactName:

Allows you to specify the name of the TestNG artifact. If not set, org.testng:testng will be used.
  • Type: java.lang.String
  • Since: 2.3.1
  • Required: No
  • Expression: ${testNGArtifactName}
  • Default: org.testng:testng

testSourceDirectory:

The test source directory containing test class sources.
  • Type: java.io.File
  • Since: 2.2
  • Required: Yes
  • Default: ${project.build.testSourceDirectory}

threadCount:

(TestNG/JUnit 4.7 provider only) The attribute thread-count allows you to specify how many threads should be allocated for this execution. Only makes sense to use in conjunction with the parallel parameter.
  • Type: int
  • Since: 2.2
  • Required: No
  • Expression: ${threadCount}

trimStackTrace:

Whether to trim the stack trace in the reports to just the lines within the test, or show the full trace.
  • Type: boolean
  • Since: 2.2
  • Required: No
  • Expression: ${trimStackTrace}
  • Default: true

useFile:

Option to generate a file test report or just output the test report to the console.
  • Type: boolean
  • Required: No
  • Expression: ${surefire.useFile}
  • Default: true

useManifestOnlyJar:

By default, Surefire forks your tests using a manifest-only JAR; set this parameter to "false" to force it to launch your tests with a plain old Java classpath. (See http://maven.apache.org/plugins/maven-surefire-plugin/examples/class-loading.html for a more detailed explanation of manifest-only JARs and their benefits.)

Beware, setting this to "false" may cause your tests to fail on Windows if your classpath is too long.
  • Type: boolean
  • Since: 2.4.3
  • Required: No
  • Expression: ${surefire.useManifestOnlyJar}
  • Default: true

useSystemClassLoader:

Option to pass dependencies to the system's classloader instead of using an isolated class loader when forking. Prevents problems with JDKs which implement the service provider lookup mechanism by using the system's classloader.
  • Type: boolean
  • Since: 2.3
  • Required: No
  • Expression: ${surefire.useSystemClassLoader}
  • Default: true

useUnlimitedThreads:

(JUnit 4.7 provider) Indicates that the thread pool will be unlimited. The parallel parameter and the actual number of classes/methods will decide. Setting this to "true" effectively disables perCoreThreadCount and threadCount. Defaults to "false".
  • Type: boolean
  • Since: 2.5
  • Required: No
  • Expression: ${useUnlimitedThreads}
  • Default: false

workingDirectory:

Command line working directory.
  • Type: java.io.File
  • Since: 2.1.3
  • Required: No
  • Expression: ${basedir}