Fork me on GitHub

surefire:test

Full name:

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

Description:

Run tests using Surefire.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: test.
  • 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> String[] 2.4 Additional elements to be appended to the classpath.
User property is: maven.test.additionalClasspath.
<argLine> String 2.1 Arbitrary JVM options to set on the command line.

Since the Version 2.17 using an alternate syntax for argLine, @{...} allows late replacement of properties when the plugin is executed, so properties that have been modified by other plugins will be picked up correctly. See the Frequently Asked Questions page with more details:
http://maven.apache.org/surefire/maven-surefire-plugin/faq.html
http://maven.apache.org/surefire/maven-failsafe-plugin/faq.html
User property is: argLine.
<basedir> File - The base directory of the project being tested. This can be obtained in your integration 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.
User property is: childDelegation.
<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> String[] 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
User property is: maven.test.dependency.excludes.
<classpathDependencyScopeExclude> String 2.6 A dependency scope to exclude from the test classpath. The scope should be one of the scopes defined by org.apache.maven.artifact.Artifact. This includes the following:
  • compile - system, provided, compile
  • runtime - compile, runtime
  • compile+runtime - system, provided, compile, runtime
  • runtime+system - system, 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).
User property is: maven.surefire.debug.
<dependenciesToScan> String[] 2.15 List of dependencies to scan for test classes to include in the test run. The child elements of this element must be <dependency> elements, and the contents of each of these elements must be a string which follows the format:
groupId:artifactId. For example: org.acme:project-a.
Since version 2.22.0 you can scan for test classes from a project dependency of your multi-module project.
User property is: dependenciesToScan.
<disableXmlReport> boolean 2.2 Flag to disable the generation of report files in xml format.
Default value is: false.
User property is: disableXmlReport.
<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.
User property is: enableAssertions.
<encoding> String 3.0.0-M1 The character encoding scheme to be applied while generating test report files (see target/surefire-reports/yourTestName.txt). The report output files (*-out.txt) are still encoded with JVM's encoding used in standard out/err pipes.
Default value is: ${project.reporting.outputEncoding}.
User property is: surefire.encoding.
<environmentVariables> Map 2.1.3 Additional environment variables to set on the command line.
<excludedGroups> String 2.2 (TestNG/JUnit47 provider with JUnit4.8+ only) Excluded groups. Any methods/classes/etc with one of the groups specified in this list will specifically not be run.
For JUnit, this parameter forces the use of the 4.7 provider.
This parameter is ignored if the suiteXmlFiles parameter is specified.
Since version 2.18.1 and JUnit 4.12, the @Category annotation type is automatically inherited from superclasses, see @java.lang.annotation.Inherited. Make sure that test class inheritance still makes sense together with @Category annotation of the JUnit 4.12 or higher appeared in superclass.
User property is: excludedGroups.
<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.
Each exclude item may also contain a comma-separated sub-list of items, which will be treated as multiple  <exclude> entries.
Since 2.19 a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):

<exclude>%regex[pkg.*Slow.*.class], Unstable*</exclude>


Notice that these values are relative to the directory containing generated test classes of the project being tested. This directory is declared by the parameter testClassesDirectory which defaults to the POM property ${project.build.testOutputDirectory}, typically src/test/java unless overridden.
<excludesFile> File - A file containing exclude patterns. Blank lines, or lines starting with # are ignored. If excludes are also specified, these patterns are appended. Example with path, simple and regex excludes:

*/test/*
**/DontRunTest.*
%regex[.*Test.*|.*Not.*]


User property is: surefire.excludesFile.
<failIfNoSpecifiedTests> Boolean 2.12 Set this to "true" to cause a failure if none of the tests specified in -Dtest=... are run. Defaults to "true".
User property is: surefire.failIfNoSpecifiedTests.
<failIfNoTests> Boolean 2.4 Set this to "true" to cause a failure if there are no tests to run. Defaults to "false".
User property is: failIfNoTests.
<forkCount> String 2.14 Option to specify the number of VMs to fork in parallel in order to execute the tests. When terminated with "C", the number part is multiplied with the number of CPU cores. Floating point value are only accepted together with "C". If set to "0", no VM is forked and all tests are executed within the main process.

Example values: "1.5C", "4"

The system properties and the argLine of the forked processes may contain the place holder string ${surefire.forkNumber}, which is replaced with a fixed number for each of the parallel forks, ranging from 1 to the effective value of forkCount times the maximum number of parallel Surefire executions in maven parallel builds, i.e. the effective value of the -T command line argument of maven core.
Default value is: 1.
User property is: forkCount.
<forkMode> String 2.1 DEPRECATED since version 2.14. Use forkCount and reuseForks instead.

Option to specify the forking mode. Can be never, once, always, perthread.
The none and pertest are also accepted for backwards compatibility.
The always forks for each test-class.
The perthread creates the number of parallel forks specified by threadCount, where each forked JVM is executing one test-class. See also the parameter reuseForks for the lifetime of JVM.
Default value is: once.
User property is: forkMode.
<forkedProcessExitTimeoutInSeconds> int 2.20 Forked process is normally terminated without any significant delay after given tests have completed. If the particular tests started non-daemon Thread(s), the process hangs instead of been properly terminated by System.exit(). Use this parameter in order to determine the timeout of terminating the process. see the documentation: http://maven.apache.org/surefire/maven-surefire-plugin/examples/shutdown.html Turns to default fallback value of 30 seconds if negative integer.
Default value is: 30.
User property is: surefire.exitTimeout.
<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.
User property is: surefire.timeout.
<groups> String 2.2 (TestNG/JUnit47 provider with JUnit4.8+ 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.
For JUnit, this parameter forces the use of the 4.7 provider
This parameter is ignored if the suiteXmlFiles parameter is specified.
Since version 2.18.1 and JUnit 4.12, the @Category annotation type is automatically inherited from superclasses, see @java.lang.annotation.Inherited. Make sure that test class inheritance still makes sense together with @Category annotation of the JUnit 4.12 or higher appeared in superclass.
User property is: groups.
<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>**/*Tests.java</include>
    <include>**/*TestCase.java</include>
</includes>

Each include item may also contain a comma-separated sub-list of items, which will be treated as multiple  <include> entries.
Since 2.19 a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):



<include>%regex[.*[Cat|Dog].*], Basic????, !Unstable*</include> <include>%regex[.*[Cat|Dog].*], !%regex[pkg.*Slow.*.class], pkg/**/*Fast*.java</include>
This parameter is ignored if the TestNG suiteXmlFiles parameter is specified.

Notice that these values are relative to the directory containing generated test classes of the project being tested. This directory is declared by the parameter testClassesDirectory which defaults to the POM property ${project.build.testOutputDirectory}, typically src/test/java unless overridden.
<includesFile> File - A file containing include patterns. Blank lines, or lines starting with # are ignored. If includes are also specified, these patterns are appended. Example with path, simple and regex includes:

*/test/*
**/NotIncludedByDefault.java
%regex[.*Test.*|.*Not.*]


User property is: surefire.includesFile.
<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.
User property is: junitArtifactName.
<junitPlatformArtifactName> String 2.22.0 Allows you to specify the name of the JUnit Platform artifact. If not set, org.junit.platform:junit-platform-engine will be used.
Default value is: org.junit.platform:junit-platform-engine.
User property is: junitPlatformArtifactName.
<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.
User property is: jvm.
<objectFactory> String 2.5 (TestNG only) Define the factory class used to create all test instances.
User property is: objectFactory.
<parallel> String 2.2 (TestNG provider) When you use the parameter parallel, 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 been controlled by threadCount.

Since version 2.16 (JUnit 4.7 provider), the value both is DEPRECATED. Use classesAndMethods instead.

Since version 2.16 (JUnit 4.7 provider), additional vales are available:
suites, suitesAndClasses, suitesAndMethods, classesAndMethods, all.
User property is: parallel.
<parallelOptimized> boolean 2.17 (JUnit 4.7 / provider only) The thread counts do not exceed the number of parallel suite, class runners and average number of methods per class if set to true.
True by default.
Default value is: true.
User property is: parallelOptimized.
<parallelTestsTimeoutForcedInSeconds> double 2.16 Stop executing queued parallel JUnit tests and interrupt currently running tests after a certain number of seconds.
Example values: "3.5", "4"

If set to 0, wait forever, never timing out. Makes sense with specified parallel different from "none".
User property is: surefire.parallel.forcedTimeout.
<parallelTestsTimeoutInSeconds> double 2.16 Stop executing queued parallel JUnit tests after a certain number of seconds.
Example values: "3.5", "4"

If set to 0, wait forever, never timing out. Makes sense with specified parallel different from "none".
User property is: surefire.parallel.timeout.
<perCoreThreadCount> boolean 2.5 (JUnit 4.7 provider) Indicates that threadCount, threadCountSuites, threadCountClasses, threadCountMethods are per cpu core.
Default value is: true.
User property is: perCoreThreadCount.
<printSummary> boolean - Option to print summary of test suites or just print the test cases that have errors.
Default value is: true.
User property is: surefire.printSummary.
<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.
User property is: maven.test.redirectTestOutputToFile.
<remoteRepositories> List 2.2 The remote plugin repositories declared in the POM.
Default value is: ${project.pluginArtifactRepositories}.
<reportFormat> String - Selects the formatting for the test report to be generated. Can be set as "brief" or "plain". Only applies to the output format of the output files (target/surefire-reports/testName.txt)
Default value is: brief.
User property is: surefire.reportFormat.
<reportNameSuffix> String - Add custom text into report filename: TEST-testClassName-reportNameSuffix.xml, testClassName-reportNameSuffix.txt and testClassName-reportNameSuffix-output.txt. File TEST-testClassName-reportNameSuffix.xml has changed attributes 'testsuite'--'name' and 'testcase'--'classname' - reportNameSuffix is added to the attribute value.
User property is: surefire.reportNameSuffix.
<reportsDirectory> File - Base directory where all reports are written to.
Default value is: ${project.build.directory}/surefire-reports.
<rerunFailingTestsCount> int - (JUnit 4+ providers) The number of times each failing test will be rerun. If set larger than 0, rerun failing tests immediately after they fail. If a failing test passes in any of those reruns, it will be marked as pass and reported as a "flake". However, all the failing attempts will be recorded.
Default value is: 0.
User property is: surefire.rerunFailingTestsCount.
<reuseForks> boolean 2.13 Indicates if forked VMs can be reused. If set to "false", a new VM is forked for each test class to be executed. If set to "true", up to forkCount VMs will be forked and then reused to execute all tests.
Default value is: true.
User property is: reuseForks.
<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), failedfirst, balanced 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.

Failed first will run tests that failed on previous run first, as well as new tests for this run.

Balanced is only relevant with parallel=classes, and will try to optimize the run-order of the tests reducing the overall execution time. Initially a statistics file is created and every next test run will reorder classes.

Note that the statistics are stored in a file named .surefire-XXXXXXXXX beside pom.xml and should not be checked into version control. The "XXXXX" is the SHA1 checksum of the entire surefire configuration, so different configurations will have different statistics files, meaning if you change any configuration settings you will re-run once before new statistics data can be established.
Default value is: filesystem.
User property is: surefire.runOrder.
<shutdown> String 2.19 After the plugin process is shutdown by sending SIGTERM signal (CTRL+C), SHUTDOWN command is received by every forked JVM.
By default (shutdown=testset) forked JVM would not continue with new test which means that the current test may still continue to run.
The parameter can be configured with other two values exit and kill.
Using exit forked JVM executes System.exit(1) after the plugin process has received SIGTERM signal.
Using kill the JVM executes Runtime.halt(1) and kills itself.
Default value is: testset.
User property is: surefire.shutdown.
<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.
User property is: maven.test.skip.
<skipAfterFailureCount> int 2.19 Set to error/failure count in order to skip remaining tests. Due to race conditions in parallel/forked execution this may not be fully guaranteed.
Enable with system property -Dsurefire.skipAfterFailureCount=1 or any number greater than zero. Defaults to "0".
See the prerequisites and limitations in documentation:
http://maven.apache.org/plugins/maven-surefire-plugin/examples/skip-after-failure.html
Default value is: 0.
User property is: surefire.skipAfterFailureCount.
<skipExec> boolean 2.3 Deprecated. Use skipTests instead.
User property is: maven.test.skip.exec.
<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.
User property is: skipTests.
<suiteXmlFiles> File[] 2.2 (TestNG) List of <suiteXmlFile> elements specifying TestNG suite xml file locations. Note that suiteXmlFiles is incompatible with several other parameters of this plugin, like includes and excludes.
This parameter is ignored if the test parameter is specified (allowing you to run a single test instead of an entire suite).
User property is: surefire.suiteXmlFiles.
<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.
<tempDir> String 2.20 Relative path to temporary-surefire-boot directory containing internal Surefire temporary files.
The temporary-surefire-boot directory is project.build.directory on most platforms or system default temporary-directory specified by the system property java.io.tmpdir on Windows (see SUREFIRE-1400).
It is deleted after the test set has completed.
Default value is: surefire.
User property is: tempDir.
<test> String - Specify this parameter to run individual tests by file name, overriding the parameter includes and excludes. 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". The test patterns prefixed with a ! will be excluded.
This parameter overrides the parameter includes, excludes, and the TestNG parameter suiteXmlFiles.
Since 2.7.3, you can execute a limited number of methods in the test by adding #myMethod or #my*ethod. For example, -Dtest=MyTest#myMethod. This is supported for junit 4.x and TestNg.

Since 2.19 a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):

"-Dtest=???Test, !Unstable*, pkg/**/Ci*leTest.java, *Test#test*One+testTwo?????, #fast*+slowTest"
or e.g.

"-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]"

The Parameterized JUnit runner describes test methods using an index in brackets, so the non-regex method pattern would become: #testMethod[*]. If using @Parameters(name="{index}: fib({0})={1}") and selecting the index e.g. 5 in pattern, the non-regex method pattern would become #testMethod[5:*].
User property is: test.
<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.
User property is: maven.test.failure.ignore.
<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.
User property is: testNGArtifactName.
<threadCount> int 2.2 (TestNG/JUnit 4.7 provider) 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.
User property is: threadCount.
<threadCountClasses> int 2.16 (JUnit 4.7 provider) This attribute allows you to specify the concurrency in test classes, i.e.:
  • number of concurrent classes if threadCount is 0 or unspecified
  • limited classes concurrency if useUnlimitedThreads is set to true
  • if threadCount and certain thread-count parameters are > 0 for parallel, the concurrency is computed from ratio. For instance parallel=all and the ratio between threadCountSuites:threadCountClasses:threadCountMethods is 2:3:5, there is 30% of threadCount in concurrent classes.
  • as in the previous case but without this leaf thread-count. Example: parallel=suitesAndClasses, threadCount=16, threadCountSuites=5, threadCountClasses is unspecified leaf, the number of concurrent classes is varying from >= 11 to 14 or 15. The threadCountSuites become given number of threads.
Only makes sense to use in conjunction with the parallel parameter. The default value 0 behaves same as unspecified one.
Default value is: 0.
User property is: threadCountClasses.
<threadCountMethods> int 2.16 (JUnit 4.7 provider) This attribute allows you to specify the concurrency in test methods, i.e.:
  • number of concurrent methods if threadCount is 0 or unspecified
  • limited concurrency of methods if useUnlimitedThreads is set to true
  • if threadCount and certain thread-count parameters are > 0 for parallel, the concurrency is computed from ratio. For instance parallel=all and the ratio between threadCountSuites:threadCountClasses:threadCountMethods is 2:3:5, there is 50% of threadCount which appears in concurrent methods.
  • as in the previous case but without this leaf thread-count. Example: parallel=all, threadCount=16, threadCountSuites=2, threadCountClasses=3, but threadCountMethods is unspecified leaf, the number of concurrent methods is varying from >= 11 to 14 or 15. The threadCountSuites and threadCountClasses become given number of threads.
Only makes sense to use in conjunction with the parallel parameter. The default value 0 behaves same as unspecified one.
Default value is: 0.
User property is: threadCountMethods.
<threadCountSuites> int 2.16 (JUnit 4.7 provider) This attribute allows you to specify the concurrency in test suites, i.e.:
  • number of concurrent suites if threadCount is 0 or unspecified
  • limited suites concurrency if useUnlimitedThreads is set to true
  • if threadCount and certain thread-count parameters are > 0 for parallel, the concurrency is computed from ratio. For instance parallel=all and the ratio between threadCountSuites:threadCountClasses:threadCountMethods is 2:3:5, there is 20% of threadCount which appeared in concurrent suites.
Only makes sense to use in conjunction with the parallel parameter. The default value 0 behaves same as unspecified one.
Default value is: 0.
User property is: threadCountSuites.
<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.
User property is: trimStackTrace.
<useFile> boolean - Option to generate a file test report or just output the test report to the console.
Default value is: true.
User property is: surefire.useFile.
<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 the 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.
User property is: surefire.useManifestOnlyJar.
<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.
User property is: surefire.useSystemClassLoader.
<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.
User property is: useUnlimitedThreads.
<workingDirectory> File 2.1.3 Command line working directory.
User property is: basedir.

Parameter Details

<additionalClasspathElements>

Additional elements to be appended to the classpath.
  • Type: java.lang.String[]
  • Since: 2.4
  • Required: No
  • User Property: maven.test.additionalClasspath

<argLine>

Arbitrary JVM options to set on the command line.

Since the Version 2.17 using an alternate syntax for argLine, @{...} allows late replacement of properties when the plugin is executed, so properties that have been modified by other plugins will be picked up correctly. See the Frequently Asked Questions page with more details:
http://maven.apache.org/surefire/maven-surefire-plugin/faq.html
http://maven.apache.org/surefire/maven-failsafe-plugin/faq.html
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • User Property: argLine

<basedir>

The base directory of the project being tested. This can be obtained in your integration 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
  • User Property: 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.lang.String[]
  • Since: 2.6
  • Required: No
  • User Property: maven.test.dependency.excludes

<classpathDependencyScopeExclude>

A dependency scope to exclude from the test classpath. The scope should be one of the scopes defined by org.apache.maven.artifact.Artifact. This includes the following:
  • compile - system, provided, compile
  • runtime - compile, runtime
  • compile+runtime - system, provided, compile, runtime
  • runtime+system - system, 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
  • User Property: maven.surefire.debug

<dependenciesToScan>

List of dependencies to scan for test classes to include in the test run. The child elements of this element must be <dependency> elements, and the contents of each of these elements must be a string which follows the format:
groupId:artifactId. For example: org.acme:project-a.
Since version 2.22.0 you can scan for test classes from a project dependency of your multi-module project.
  • Type: java.lang.String[]
  • Since: 2.15
  • Required: No
  • User Property: dependenciesToScan

<disableXmlReport>

Flag to disable the generation of report files in xml format.
  • Type: boolean
  • Since: 2.2
  • Required: No
  • User Property: 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
  • User Property: enableAssertions
  • Default: true

<encoding>

The character encoding scheme to be applied while generating test report files (see target/surefire-reports/yourTestName.txt). The report output files (*-out.txt) are still encoded with JVM's encoding used in standard out/err pipes.
  • Type: java.lang.String
  • Since: 3.0.0-M1
  • Required: No
  • User Property: surefire.encoding
  • Default: ${project.reporting.outputEncoding}

<environmentVariables>

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

<excludedGroups>

(TestNG/JUnit47 provider with JUnit4.8+ only) Excluded groups. Any methods/classes/etc with one of the groups specified in this list will specifically not be run.
For JUnit, this parameter forces the use of the 4.7 provider.
This parameter is ignored if the suiteXmlFiles parameter is specified.
Since version 2.18.1 and JUnit 4.12, the @Category annotation type is automatically inherited from superclasses, see @java.lang.annotation.Inherited. Make sure that test class inheritance still makes sense together with @Category annotation of the JUnit 4.12 or higher appeared in superclass.
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • User Property: 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.
Each exclude item may also contain a comma-separated sub-list of items, which will be treated as multiple  <exclude> entries.
Since 2.19 a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):

<exclude>%regex[pkg.*Slow.*.class], Unstable*</exclude>


Notice that these values are relative to the directory containing generated test classes of the project being tested. This directory is declared by the parameter testClassesDirectory which defaults to the POM property ${project.build.testOutputDirectory}, typically src/test/java unless overridden.
  • Type: java.util.List
  • Required: No

<excludesFile>

A file containing exclude patterns. Blank lines, or lines starting with # are ignored. If excludes are also specified, these patterns are appended. Example with path, simple and regex excludes:

*/test/*
**/DontRunTest.*
%regex[.*Test.*|.*Not.*]

  • Type: java.io.File
  • Required: No
  • User Property: surefire.excludesFile

<failIfNoSpecifiedTests>

Set this to "true" to cause a failure if none of the tests specified in -Dtest=... are run. Defaults to "true".
  • Type: java.lang.Boolean
  • Since: 2.12
  • Required: No
  • User Property: surefire.failIfNoSpecifiedTests

<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
  • User Property: failIfNoTests

<forkCount>

Option to specify the number of VMs to fork in parallel in order to execute the tests. When terminated with "C", the number part is multiplied with the number of CPU cores. Floating point value are only accepted together with "C". If set to "0", no VM is forked and all tests are executed within the main process.

Example values: "1.5C", "4"

The system properties and the argLine of the forked processes may contain the place holder string ${surefire.forkNumber}, which is replaced with a fixed number for each of the parallel forks, ranging from 1 to the effective value of forkCount times the maximum number of parallel Surefire executions in maven parallel builds, i.e. the effective value of the -T command line argument of maven core.
  • Type: java.lang.String
  • Since: 2.14
  • Required: No
  • User Property: forkCount
  • Default: 1

<forkMode>

DEPRECATED since version 2.14. Use forkCount and reuseForks instead.

Option to specify the forking mode. Can be never, once, always, perthread.
The none and pertest are also accepted for backwards compatibility.
The always forks for each test-class.
The perthread creates the number of parallel forks specified by threadCount, where each forked JVM is executing one test-class. See also the parameter reuseForks for the lifetime of JVM.
  • Type: java.lang.String
  • Since: 2.1
  • Required: No
  • User Property: forkMode
  • Default: once

<forkedProcessExitTimeoutInSeconds>

Forked process is normally terminated without any significant delay after given tests have completed. If the particular tests started non-daemon Thread(s), the process hangs instead of been properly terminated by System.exit(). Use this parameter in order to determine the timeout of terminating the process. see the documentation: http://maven.apache.org/surefire/maven-surefire-plugin/examples/shutdown.html Turns to default fallback value of 30 seconds if negative integer.
  • Type: int
  • Since: 2.20
  • Required: No
  • User Property: surefire.exitTimeout
  • Default: 30

<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
  • User Property: surefire.timeout

<groups>

(TestNG/JUnit47 provider with JUnit4.8+ 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.
For JUnit, this parameter forces the use of the 4.7 provider
This parameter is ignored if the suiteXmlFiles parameter is specified.
Since version 2.18.1 and JUnit 4.12, the @Category annotation type is automatically inherited from superclasses, see @java.lang.annotation.Inherited. Make sure that test class inheritance still makes sense together with @Category annotation of the JUnit 4.12 or higher appeared in superclass.
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • User Property: 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>**/*Tests.java</include>
    <include>**/*TestCase.java</include>
</includes>

Each include item may also contain a comma-separated sub-list of items, which will be treated as multiple  <include> entries.
Since 2.19 a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):



<include>%regex[.*[Cat|Dog].*], Basic????, !Unstable*</include> <include>%regex[.*[Cat|Dog].*], !%regex[pkg.*Slow.*.class], pkg/**/*Fast*.java</include>
This parameter is ignored if the TestNG suiteXmlFiles parameter is specified.

Notice that these values are relative to the directory containing generated test classes of the project being tested. This directory is declared by the parameter testClassesDirectory which defaults to the POM property ${project.build.testOutputDirectory}, typically src/test/java unless overridden.
  • Type: java.util.List
  • Required: No

<includesFile>

A file containing include patterns. Blank lines, or lines starting with # are ignored. If includes are also specified, these patterns are appended. Example with path, simple and regex includes:

*/test/*
**/NotIncludedByDefault.java
%regex[.*Test.*|.*Not.*]

  • Type: java.io.File
  • Required: No
  • User Property: surefire.includesFile

<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
  • User Property: junitArtifactName
  • Default: junit:junit

<junitPlatformArtifactName>

Allows you to specify the name of the JUnit Platform artifact. If not set, org.junit.platform:junit-platform-engine will be used.
  • Type: java.lang.String
  • Since: 2.22.0
  • Required: No
  • User Property: junitPlatformArtifactName
  • Default: org.junit.platform:junit-platform-engine

<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
  • User Property: jvm

<objectFactory>

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

<parallel>

(TestNG provider) When you use the parameter parallel, 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 been controlled by threadCount.

Since version 2.16 (JUnit 4.7 provider), the value both is DEPRECATED. Use classesAndMethods instead.

Since version 2.16 (JUnit 4.7 provider), additional vales are available:
suites, suitesAndClasses, suitesAndMethods, classesAndMethods, all.
  • Type: java.lang.String
  • Since: 2.2
  • Required: No
  • User Property: parallel

<parallelOptimized>

(JUnit 4.7 / provider only) The thread counts do not exceed the number of parallel suite, class runners and average number of methods per class if set to true.
True by default.
  • Type: boolean
  • Since: 2.17
  • Required: No
  • User Property: parallelOptimized
  • Default: true

<parallelTestsTimeoutForcedInSeconds>

Stop executing queued parallel JUnit tests and interrupt currently running tests after a certain number of seconds.
Example values: "3.5", "4"

If set to 0, wait forever, never timing out. Makes sense with specified parallel different from "none".
  • Type: double
  • Since: 2.16
  • Required: No
  • User Property: surefire.parallel.forcedTimeout

<parallelTestsTimeoutInSeconds>

Stop executing queued parallel JUnit tests after a certain number of seconds.
Example values: "3.5", "4"

If set to 0, wait forever, never timing out. Makes sense with specified parallel different from "none".
  • Type: double
  • Since: 2.16
  • Required: No
  • User Property: surefire.parallel.timeout

<perCoreThreadCount>

(JUnit 4.7 provider) Indicates that threadCount, threadCountSuites, threadCountClasses, threadCountMethods are per cpu core.
  • Type: boolean
  • Since: 2.5
  • Required: No
  • User Property: perCoreThreadCount
  • Default: true

<printSummary>

Option to print summary of test suites or just print the test cases that have errors.
  • Type: boolean
  • Required: No
  • User Property: 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
  • User Property: maven.test.redirectTestOutputToFile
  • Default: false

<remoteRepositories>

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

<reportFormat>

Selects the formatting for the test report to be generated. Can be set as "brief" or "plain". Only applies to the output format of the output files (target/surefire-reports/testName.txt)
  • Type: java.lang.String
  • Required: No
  • User Property: surefire.reportFormat
  • Default: brief

<reportNameSuffix>

Add custom text into report filename: TEST-testClassName-reportNameSuffix.xml, testClassName-reportNameSuffix.txt and testClassName-reportNameSuffix-output.txt. File TEST-testClassName-reportNameSuffix.xml has changed attributes 'testsuite'--'name' and 'testcase'--'classname' - reportNameSuffix is added to the attribute value.
  • Type: java.lang.String
  • Required: No
  • User Property: surefire.reportNameSuffix

<reportsDirectory>

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

<rerunFailingTestsCount>

(JUnit 4+ providers) The number of times each failing test will be rerun. If set larger than 0, rerun failing tests immediately after they fail. If a failing test passes in any of those reruns, it will be marked as pass and reported as a "flake". However, all the failing attempts will be recorded.
  • Type: int
  • Required: No
  • User Property: surefire.rerunFailingTestsCount
  • Default: 0

<reuseForks>

Indicates if forked VMs can be reused. If set to "false", a new VM is forked for each test class to be executed. If set to "true", up to forkCount VMs will be forked and then reused to execute all tests.
  • Type: boolean
  • Since: 2.13
  • Required: No
  • User Property: reuseForks
  • Default: true

<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), failedfirst, balanced 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.

Failed first will run tests that failed on previous run first, as well as new tests for this run.

Balanced is only relevant with parallel=classes, and will try to optimize the run-order of the tests reducing the overall execution time. Initially a statistics file is created and every next test run will reorder classes.

Note that the statistics are stored in a file named .surefire-XXXXXXXXX beside pom.xml and should not be checked into version control. The "XXXXX" is the SHA1 checksum of the entire surefire configuration, so different configurations will have different statistics files, meaning if you change any configuration settings you will re-run once before new statistics data can be established.
  • Type: java.lang.String
  • Since: 2.7
  • Required: No
  • User Property: surefire.runOrder
  • Default: filesystem

<shutdown>

After the plugin process is shutdown by sending SIGTERM signal (CTRL+C), SHUTDOWN command is received by every forked JVM.
By default (shutdown=testset) forked JVM would not continue with new test which means that the current test may still continue to run.
The parameter can be configured with other two values exit and kill.
Using exit forked JVM executes System.exit(1) after the plugin process has received SIGTERM signal.
Using kill the JVM executes Runtime.halt(1) and kills itself.
  • Type: java.lang.String
  • Since: 2.19
  • Required: No
  • User Property: surefire.shutdown
  • Default: testset

<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
  • User Property: maven.test.skip
  • Default: false

<skipAfterFailureCount>

Set to error/failure count in order to skip remaining tests. Due to race conditions in parallel/forked execution this may not be fully guaranteed.
Enable with system property -Dsurefire.skipAfterFailureCount=1 or any number greater than zero. Defaults to "0".
See the prerequisites and limitations in documentation:
http://maven.apache.org/plugins/maven-surefire-plugin/examples/skip-after-failure.html
  • Type: int
  • Since: 2.19
  • Required: No
  • User Property: surefire.skipAfterFailureCount
  • Default: 0

<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
  • User Property: 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
  • User Property: skipTests
  • Default: false

<suiteXmlFiles>

(TestNG) List of <suiteXmlFile> elements specifying TestNG suite xml file locations. Note that suiteXmlFiles is incompatible with several other parameters of this plugin, like includes and 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
  • User Property: surefire.suiteXmlFiles

<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

<tempDir>

Relative path to temporary-surefire-boot directory containing internal Surefire temporary files.
The temporary-surefire-boot directory is project.build.directory on most platforms or system default temporary-directory specified by the system property java.io.tmpdir on Windows (see SUREFIRE-1400).
It is deleted after the test set has completed.
  • Type: java.lang.String
  • Since: 2.20
  • Required: No
  • User Property: tempDir
  • Default: surefire

<test>

Specify this parameter to run individual tests by file name, overriding the parameter includes and excludes. 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". The test patterns prefixed with a ! will be excluded.
This parameter overrides the parameter includes, excludes, and the TestNG parameter suiteXmlFiles.
Since 2.7.3, you can execute a limited number of methods in the test by adding #myMethod or #my*ethod. For example, -Dtest=MyTest#myMethod. This is supported for junit 4.x and TestNg.

Since 2.19 a complex syntax is supported in one parameter (JUnit 4, JUnit 4.7+, TestNG):

"-Dtest=???Test, !Unstable*, pkg/**/Ci*leTest.java, *Test#test*One+testTwo?????, #fast*+slowTest"
or e.g.

"-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]"

The Parameterized JUnit runner describes test methods using an index in brackets, so the non-regex method pattern would become: #testMethod[*]. If using @Parameters(name="{index}: fib({0})={1}") and selecting the index e.g. 5 in pattern, the non-regex method pattern would become #testMethod[5:*].
  • Type: java.lang.String
  • Required: No
  • User Property: 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
  • User Property: 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
  • User Property: 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) 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
  • User Property: threadCount

<threadCountClasses>

(JUnit 4.7 provider) This attribute allows you to specify the concurrency in test classes, i.e.:
  • number of concurrent classes if threadCount is 0 or unspecified
  • limited classes concurrency if useUnlimitedThreads is set to true
  • if threadCount and certain thread-count parameters are > 0 for parallel, the concurrency is computed from ratio. For instance parallel=all and the ratio between threadCountSuites:threadCountClasses:threadCountMethods is 2:3:5, there is 30% of threadCount in concurrent classes.
  • as in the previous case but without this leaf thread-count. Example: parallel=suitesAndClasses, threadCount=16, threadCountSuites=5, threadCountClasses is unspecified leaf, the number of concurrent classes is varying from >= 11 to 14 or 15. The threadCountSuites become given number of threads.
Only makes sense to use in conjunction with the parallel parameter. The default value 0 behaves same as unspecified one.
  • Type: int
  • Since: 2.16
  • Required: No
  • User Property: threadCountClasses
  • Default: 0

<threadCountMethods>

(JUnit 4.7 provider) This attribute allows you to specify the concurrency in test methods, i.e.:
  • number of concurrent methods if threadCount is 0 or unspecified
  • limited concurrency of methods if useUnlimitedThreads is set to true
  • if threadCount and certain thread-count parameters are > 0 for parallel, the concurrency is computed from ratio. For instance parallel=all and the ratio between threadCountSuites:threadCountClasses:threadCountMethods is 2:3:5, there is 50% of threadCount which appears in concurrent methods.
  • as in the previous case but without this leaf thread-count. Example: parallel=all, threadCount=16, threadCountSuites=2, threadCountClasses=3, but threadCountMethods is unspecified leaf, the number of concurrent methods is varying from >= 11 to 14 or 15. The threadCountSuites and threadCountClasses become given number of threads.
Only makes sense to use in conjunction with the parallel parameter. The default value 0 behaves same as unspecified one.
  • Type: int
  • Since: 2.16
  • Required: No
  • User Property: threadCountMethods
  • Default: 0

<threadCountSuites>

(JUnit 4.7 provider) This attribute allows you to specify the concurrency in test suites, i.e.:
  • number of concurrent suites if threadCount is 0 or unspecified
  • limited suites concurrency if useUnlimitedThreads is set to true
  • if threadCount and certain thread-count parameters are > 0 for parallel, the concurrency is computed from ratio. For instance parallel=all and the ratio between threadCountSuites:threadCountClasses:threadCountMethods is 2:3:5, there is 20% of threadCount which appeared in concurrent suites.
Only makes sense to use in conjunction with the parallel parameter. The default value 0 behaves same as unspecified one.
  • Type: int
  • Since: 2.16
  • Required: No
  • User Property: threadCountSuites
  • Default: 0

<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
  • User Property: trimStackTrace
  • Default: true

<useFile>

Option to generate a file test report or just output the test report to the console.
  • Type: boolean
  • Required: No
  • User Property: 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 the 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
  • User Property: 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
  • User Property: 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
  • User Property: useUnlimitedThreads
  • Default: false

<workingDirectory>

Command line working directory.
  • Type: java.io.File
  • Since: 2.1.3
  • Required: No
  • User Property: basedir