surefire:test

Run tests using Surefire.

Mojo Attributes:

  • Requires a Maven 2.0 project to execute.
  • Requires dependency resolution of artifacts in scope: test
  • Automatically executes within the lifecycle phase: test

Required Parameters

Name Type Description
basedir File The base directory of the project being tested. This can be obtained in your unit test by System.getProperty("basedir").
classesDirectory File The directory containing generated classes of the project being tested.
testClassesDirectory File The directory containing generated test classes of the project being tested.
testSourceDirectory File The test source directory containing test class sources.

Optional Parameters

Name Type Description
argLine String Arbitrary options to set on the command line.
artifactFactory ArtifactFactory Creates the artifact
artifactResolver ArtifactResolver Resolves the artifacts needed.
childDelegation boolean 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.
disableXmlReport boolean Flag to disable the generation of report files in xml format. Default value is false.
environmentVariables Map Additional environments to set on the command line.
excludedGroups String Excluded groups. Any methods/classes/etc with one of the groups specified in this list will specifically not be run.
excludes List List of patterns (separated by commas) used to specify the tests that should be excluded in testing. When not specified and when the test parameter is not specified, the default excludes will be **/Abstract*Test.java **/Abstract*TestCase.java **/*$*
forkMode String Option to specify the forking mode. Can be "never", "once" or "always". "none" and "pertest" are also accepted for backwards compatibility. Default value is once.
groups String Groups for this test. Only classes/methods/etc decorated with one of the groups specified here will be included in test run, if specified.
includes List List of patterns (separated by commas) used to specify the tests that should be included in testing. When not specified and when the test parameter is not specified, the default includes will be **/Test*.java **/*Test.java **/*TestCase.java
jvm String Option to specify the jvm (or path to the java executable) to use with the forking options. For the default, the jvm will be the same as the one used to run Maven.
metadataSource ArtifactMetadataSource For retrieval of artifact's metadata.
parallel boolean 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. Default value is false.
printSummary boolean Option to print summary of test suites or just print the test cases that has errors. Default value is true.
redirectTestOutputToFile boolean When forking, 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 The plugin remote 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.
skip boolean Set this to 'true' to bypass unit tests entirely. Its use is NOT RECOMMENDED, but quite convenient on occasion.
skipExec boolean Set this to 'true' to bypass unit tests execution, but still compile them. Its use is NOT RECOMMENDED, but quite convenient on occasion.
suiteXmlFiles File List of TestNG suite xml file locations, seperated by commas. It should be noted that if suiteXmlFiles is specified, no other tests will be run, ignoring other parameters, like includes and excludes.
systemProperties Properties List of System properties to pass to the JUnit tests.
test String Specify this parameter(can be a comma separated list) if you want to use the test pattern matching notation, Ant pattern matching, to select tests to run. The Ant pattern will be used to create an include pattern formatted like **/${test}.java When used, the includes and excludes patterns parameters are ignored.
testFailureIgnore boolean Set this to true to ignore a failure during testing. Its use is NOT RECOMMENDED, but quite convenient on occasion.
threadCount int 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 parallel. Default value is 5.
trimStackTrace boolean 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.
workingDirectory File Command line working directory.

Parameter Details

argLine Arbitrary options to set on the command line.
  • Type: java.lang.String
  • Required: No
  • Expression: ${argLine}
artifactFactory Creates the artifact
  • Type: org.apache.maven.artifact.factory.ArtifactFactory
  • Required: No
artifactResolver Resolves the artifacts needed.
  • Type: org.apache.maven.artifact.resolver.ArtifactResolver
  • Required: No
basedir The base directory of the project being tested. This can be obtained in your unit test by System.getProperty("basedir").
  • Type: java.io.File
  • Required: Yes
  • Expression: ${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
  • Required: No
  • Expression: ${childDelegation}
  • Default: false
classesDirectory The directory containing generated classes of the project being tested.
  • Type: java.io.File
  • Required: Yes
  • Expression: ${project.build.outputDirectory}
disableXmlReport Flag to disable the generation of report files in xml format.
  • Type: boolean
  • Required: No
  • Expression: ${disableXmlReport}
  • Default: false
environmentVariables Additional environments to set on the command line.
  • Type: java.util.Map
  • Required: No
excludedGroups Excluded groups. Any methods/classes/etc with one of the groups specified in this list will specifically not be run.
  • Type: java.lang.String
  • Required: No
  • Expression: ${excludedGroups}
excludes List of patterns (separated by commas) used to specify the tests that should be excluded in testing. When not specified and when the test parameter is not specified, the default excludes will be **/Abstract*Test.java **/Abstract*TestCase.java **/*$*
  • Type: java.util.List
  • Required: No
forkMode Option to specify the forking mode. Can be "never", "once" or "always". "none" and "pertest" are also accepted for backwards compatibility.
  • Type: java.lang.String
  • Required: No
  • Expression: ${forkMode}
  • Default: once
groups Groups for this test. Only classes/methods/etc decorated with one of the groups specified here will be included in test run, if specified.
  • Type: java.lang.String
  • Required: No
  • Expression: ${groups}
includes List of patterns (separated by commas) used to specify the tests that should be included in testing. When not specified and when the test parameter is not specified, the default includes will be **/Test*.java **/*Test.java **/*TestCase.java
  • Type: java.util.List
  • Required: No
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 the same as the one used to run Maven.
  • Type: java.lang.String
  • Required: No
  • Expression: ${jvm}
metadataSource For retrieval of artifact's metadata.
  • Type: org.apache.maven.artifact.metadata.ArtifactMetadataSource
  • Required: No
parallel 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.
  • Type: boolean
  • Required: No
  • Expression: ${parallel}
  • Default: false
printSummary Option to print summary of test suites or just print the test cases that has errors.
  • Type: boolean
  • Required: No
  • Expression: ${surefire.printSummary}
  • Default: true
redirectTestOutputToFile When forking, set this to true to redirect the unit test standard output to a file (found in reportsDirectory/testName-output.txt).
  • Type: boolean
  • Required: No
  • Expression: ${maven.test.redirectTestOutputToFile}
  • Default: false
remoteRepositories The plugin remote repositories declared in the pom.
  • Type: java.util.List
  • 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
  • Expression: ${project.build.directory}/surefire-reports
skip Set this to 'true' to bypass unit tests entirely. Its use is NOT RECOMMENDED, but quite convenient on occasion.
  • Type: boolean
  • Required: No
  • Expression: ${maven.test.skip}
skipExec Set this to 'true' to bypass unit tests execution, but still compile them. Its use is NOT RECOMMENDED, but quite convenient on occasion.
  • Type: boolean
  • Required: No
  • Expression: ${maven.test.skip.exec}
suiteXmlFiles List of TestNG suite xml file locations, seperated by commas. It should be noted that if suiteXmlFiles is specified, no other tests will be run, ignoring other parameters, like includes and excludes.
  • Type: java.io.File
  • Required: No
systemProperties List of System properties to pass to the JUnit tests.
  • Type: java.util.Properties
  • Required: No
test Specify this parameter(can be a comma separated list) if you want to use the test pattern matching notation, Ant pattern matching, to select tests to run. The Ant pattern will be used to create an include pattern formatted like **/${test}.java When used, the includes and excludes patterns parameters are ignored.
  • Type: java.lang.String
  • Required: No
  • Expression: ${test}
testClassesDirectory The directory containing generated test classes of the project being tested.
  • Type: java.io.File
  • Required: Yes
  • Expression: ${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}
testSourceDirectory The test source directory containing test class sources.
  • Type: java.io.File
  • Required: Yes
  • Expression: ${project.build.testSourceDirectory}
threadCount 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 parallel.
  • Type: int
  • Required: No
  • Expression: ${threadCount}
  • Default: 5
trimStackTrace Whether to trim the stack trace in the reports to just the lines within the test, or show the full trace.
  • Type: boolean
  • 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
workingDirectory Command line working directory.
  • Type: java.io.File
  • Required: No