------
 Maven 2 Surefire Plugin 
 ------
 Johnny R. Ruiz III <jruiz@exist.com>
 Allan Ramirez <aramirez@apache.org>
 Brett Porter <brett@apache.org>
 ------
 September 20, 2005

How to Use

* Using different testing providers

  Tests in your tes source directory can be any combination of the following:

   * Test NG

   * JUnit

   * POJO

  Which providers are available is controlled simply by the inclusion of the appropriate
  dependencies (ie, junit:junit for JUnit, org.testng:testng 4.7+ for Test NG). Since this is
  required to compile the test classes anyway, no additional configuration is required.

  Note that any normal Surefire integration works identically no matter which providers are
  in use - so you can still produce a Cobertura report and a Surefire results report on your
  project web site for your Test NG tests, for example.

  The POJO provider above allows you to write tests that do not depend on JUnit. They behave in
  the same way, running all <<<test*>>> methods that are public in the class, but the API
  dependency is not required. To perform assertions, the JDK 1.4 <<<assert>>> keyword can be
  used, or you can use <<<org.apache.maven.surefire.assertion.Assert>>>.

  All of the providers support the following configuration. However, there are additional
  options available if you are running TestNG tests (including if you are using TestNG to
  execute your JUnit tests, which occurs by default if both are present in Surefire).

  See {{{testng.html} Test NG Configuration}} for more information.

* Skipping Tests

 To skip running the tests for a particular project, you configure the skip parameter:

-----
<project>
  ...
  <build>
    ...
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <configuration>
        <skip>true</skip>
      </configuration>
    </plugin>
    ...
  </build>
  ...
</project>
-----

 Alternatively, you can execute the following on the command line to skip tests:

-----
mvn -Dmaven.test.skip=true install
-----

* Using System Properties

 To add a System property, use the following configuration:

-----
<project>
  ...
  <build>
    ...
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <configuration>
        <systemProperties>
          <property>
            <name>propertyName</name>
            <value>propertyValue</value>
          </property>
        </systemProperties>
      </configuration>
    </plugin>
    ...
  </build>
  ...
</project>
-----

* Forking

 If you need to run your tests in a new JVM process you can use the <<<forkMode>>> option to start a new
 JVM process once for all your tests, or start a new JVM process for each of your tests. You can also set
 any arbitrary options like <<<-enableassertions>>> or any other JVM options. Here's an example of what
 this might look like:

-----
<project>
  ...
  <build>
    ...
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <configuration>
        <forkMode>pertest</forkMode>
        <argLine>-enableassertions</argLine>
      </configuration>
    </plugin>
    ...
  </build>
  ...
</project>
-----

 <<Note:>> You do not need to manually enable assertions if you are using them in your unit tests - Surefire enables
 them on your test classes automatically under JDK 1.4+.

 The default setting is <<<once>>>. It can also be set to <<<never>>> to run in process for a small performance improvement.

* Class Loading Issues

 By default, Surefire loads classes using the default Java mechanism. However, it can be set to use "child first" classloading, like 
 a web application - meaning your dependencies take precedence over those in the JDK.
 If you find this is necessary, you can do so by setting the <<<childDelegation>>> flag to <<<true>>>:

----
<project>
  ...
  <build>
    ...

    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <childDelegation>true</childDelegation>
        </configuration>       

      </plugin>
  ...
  </build>
  ...
</project>
----

* Tests Inclusion and Exclusion

** Inclusions
  
  By default, the surefire plugin will automatically include all test classes with the following wildcard patterns:

   * <"**/Test*.java"> - includes all of its subdirectory and all java filename that starts with "Test".

   * <"**/*Test.java"> - includes all of its subdirectory and all java filename that ends with "Test".

   * <"**/*TestCase.java"> - includes all of its subdirectory and all java filename that ends with "TestCase".

  If your test classes does not go with the naming convention, then configure surefire plugin and include your test.

+---+
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <includes>
            <include>Sample.java</include>
          </includes>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+---+  

** Exclusions

  There are certain times that some tests are causing the build to fail. If the bad test classes are only few 
  we may exclude them to continue the build. Exclusions can be done by the following:

+---+
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <configuration>
          <excludes>
            <exclude>**/TestCircle.java</exclude>
            <exclude>**/TestSquare.java</exclude>
          </excludes>
        </configuration>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+---+

* Running a single test

  During development, you may run a single test class repeatedly. To run this through Maven, you must use the <<<test>>> parameter.
  For example:

+---+
mvn -Dtest=TestCircle test
+---+
  
 There are other parameters that you can configure like testFailureIgnore, reportsDirectory, and so on.
 For full documentation, click {{{index.html}here}}.