  ------
  Usage
  ------
  Brett Porter
  Allan Ramirez
  Stephen Connolly
  ------
  2011-06-27
  ------
  
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Usage

#{if}(${project.artifactId}=="maven-surefire-plugin")
  Best practice is to define the version of the Surefire Plugin that you want to use in either your <<<pom.xml>>>
  or a parent <<<pom.xml>>>:

+---+
<project>
  [...]
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>${project.groupId}</groupId>
          <artifactId>${project.artifactId}</artifactId>
          <version>${project.version}</version>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
  [...]
</project>
+---+

#{else}
  To use the ${thisPlugin} Plugin, you need to add the following configuration to
  your <<<pom.xml>>>:

+---+
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>${project.groupId}</groupId>
        <artifactId>${project.artifactId}</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <goals>
              <goal>integration-test</goal>
              <goal>verify</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

#{end}
#{if}(${project.artifactId}=="maven-surefire-plugin")
  The ${thisPlugin} Plugin can be invoked by calling the <<<test>>> phase of the
  build lifecycle.

+---+
mvn test
+---+

#{else}
  The ${thisPlugin} Plugin can be invoked by calling the <<<verify>>> phase of the
  build lifecycle.

+---+
mvn verify
+---+
#{end}

* Using Different Testing Providers

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

   * TestNG

   * JUnit (3.8, 4.x or 5.x)

   * POJO

  Which providers are available is controlled simply by the inclusion of the
  appropriate dependencies (i.e., <<<junit:junit>>> or <<<junit:junit-dep>>> for JUnit4, <<junit-jupiter-engine>> or
  <<junit-vintage-engine>> for JUnit5 and <<<org.testng:testng>>> 4.7+ for TestNG). 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 TestNG tests,
  for example.

  The POJO provider above allows you to write tests that do not depend on either of
  JUnit and TestNG. It behaves 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.
  See {{{./examples/pojo-test.html} Using POJO Tests}} for more information.

  All of the providers support the Surefire Plugin parameter configurations.
  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 {{{./examples/testng.html} Using TestNG}} for more information.

#{if}(${project.artifactId}=="maven-failsafe-plugin")
* Using jetty and ${project.artifactId}

  You need to bind one of <<<jetty:start>>>, <<<jetty:run>>>, <<<jetty:run-exploded>>> or <<<jetty:run-war>>>
  to the <<<pre-integration-test>>> phase with <<<daemon>>> set to true, bind
  <<<failsafe:integration-test>>> to the <<<integration-test>>> phase, bind <<<jetty:stop>>>
  to the <<<post-integration-test>>> phase and finally bind <<<failsafe:verify>>> to
  the <<<verify>>> phase.  Here is an example:

+---+
<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <groupId>${project.groupId}</groupId>
        <artifactId>${project.artifactId}</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>integration-test</id>
            <goals>
              <goal>integration-test</goal>
            </goals>
          </execution>
          <execution>
            <id>verify</id>
            <goals>
              <goal>verify</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.eclipse.jetty</groupId>
        <artifactId>jetty-maven-plugin</artifactId>
        <version>9.2.2.v20140723</version>
        [...]
        <configuration>
          [...]
          <scanIntervalSeconds>10</scanIntervalSeconds>
          <stopPort>8005</stopPort>
          <stopKey>STOP</stopKey>
          [...]
        </configuration>
        [...]
        <executions>
          [...]
          <execution>
            <id>start-jetty</id>
            <phase>pre-integration-test</phase>
            <goals>
              <goal>start</goal>
            </goals>
            <configuration>
              <scanIntervalSeconds>0</scanIntervalSeconds>
              <daemon>true</daemon>
            </configuration>
          </execution>
          <execution>
            <id>stop-jetty</id>
            <phase>post-integration-test</phase>
            <goals>
              <goal>stop</goal>
            </goals>
          </execution>
          [...]
        </executions>
        [...]
      </plugin>
      [...]
    </plugins>
    [...]
  </build>
  [...]
</project>
+---+

  You then invoke Maven with a phase of <<<verify>>> or later in order to run
  the integration tests.  <<DO NOT>> directly invoke any of the phases
  <<<pre-integration-test>>>, <<<integration-test>>>, or <<<post-integration-test>>> as
  these are too long to type and they will likely leave a jetty container running.

+---+
mvn verify
+---+

  Note: during test development, you will likely run a jetty instance in the background.
  to help running the integration tests, it can be handy to bind <<<jetty:stop>>> to
  the <<<pre-integration-test>>> phase before <<<jetty:run>>> to flush out any
  running jetty instance before starting the integration test jetty instance, e.g.

+---+
<project>
  [...]
  <build>
    [...]
    <plugins>
      [...]
      <plugin>
        <groupId>org.eclipse.jetty</groupId>
        <artifactId>jetty-maven-plugin</artifactId>
        <version>9.2.2.v20140723</version>
        [...]
        <executions>
          [...]
          <execution>
            <id>start-jetty</id>
            <phase>pre-integration-test</phase>
            <goals>
              <!-- stop any previous instance to free up the port -->
              <goal>stop</goal>
              <goal>start</goal>
            </goals>
            [...]
          </execution>
          [...]
        </executions>
        [...]
      </plugin>
      [...]
    </plugins>
    [...]
  </build>
  [...]
</project>
+---+

* Reporting integration test results

  The ${thisPlugin} Plugin uses the exact same format as the ${thatPlugin} Plugin, so to generate a report you just add a second
  Surefire Report Plugin report set using the ${thisPlugin} reports directory, e.g.

+---+
<project>
  [...]
  <reporting>
    <plugins>
      <plugin>
        <groupId>${project.groupId}</groupId>
        <artifactId>maven-surefire-report-plugin</artifactId>
        <version>${project.version}</version>
        <reportSets>
          <reportSet>
            <id>integration-tests</id>
            <reports>
              <report>failsafe-report-only</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
    </plugins>
  </reporting>
  [...]
</project>
+---+

* Running integration tests multiple times

  If you need to run your integration tests multiple times, just use multiple executions of the <<<integration-test>>>
  goal.  You will need to specify a different summary file for each execution, and then configure the <<<verify>>> goal
  with the multiple summary files in order to fail the build when any one execution has failures, e.g.

+---+
<project>
  [...]
  <reporting>
    <plugins>
      <plugin>
        <groupId>${project.groupId}</groupId>
        <artifactId>${project.artifactId}</artifactId>
        <version>${project.version}</version>
        <executions>
          <execution>
            <id>integration-test-red-bevels</id>
            <goals>
              <goal>integration-test</goal>
            </goals>
            <configuration>
              <systemPropertyVariables>
                <bevels>red</bevels>
              </systemPropertyVariables>
              <summaryFile>target/failsafe-reports/failsafe-summary-red-bevels.xml</summaryFile>
            </configuration>
          </execution>
          <execution>
            <id>integration-test-no-bevels</id>
            <goals>
              <goal>integration-test</goal>
            </goals>
            <configuration>
              <systemPropertyVariables>
                <bevels>none</bevels>
              </systemPropertyVariables>
              <summaryFile>target/failsafe-reports/failsafe-summary-no-bevels.xml</summaryFile>
            </configuration>
          </execution>
          <execution>
            <id>verify</id>
            <goals>
              <goal>verify</goal>
            </goals>
            <configuration>
              <summaryFiles>
                <summaryFile>target/failsafe-reports/failsafe-summary-red-bevels.xml</summaryFile>
                <summaryFile>target/failsafe-reports/failsafe-summary-no-bevels.xml</summaryFile>
              </summaryFiles>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </reporting>
  [...]
</project>
+---+

* Usage in multi-module projects

  The recommendations for using the ${thisPlugin} Plugin listed at the top of this page are fine for 95% of use cases.
  When you are defining a shared definition of the ${thisPlugin} Plugin in a parent pom, it is considered best practice
  to define an execution id in order to allow child projects to override the configuration. Thus you might have the
  following in your parent <<<pom.xml>>>:

+---+
<project>
  [...]
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>${project.groupId}</groupId>
          <artifactId>${project.artifactId}</artifactId>
          <version>${project.version}</version>
          <executions>
            <execution>
              <id>integration-test</id>
              <goals>
                <goal>integration-test</goal>
                <goal>verify</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
  [...]
</project>
+---+

  The child projects can then trigger usage of the ${thisPlugin} Plugin with

+---+
<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>${project.groupId}</groupId>
        <artifactId>${project.artifactId}</artifactId>
        <version>${project.version}</version>
      </plugin>
    </plugins>
  </build>
  [...]
</project>
+---+

  For very complex builds, it may be better to separate the executions for the <<<integration-test>>> and <<<verify>>>
  goals.

+---+
<project>
  [...]
  <build>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>${project.groupId}</groupId>
          <artifactId>${project.artifactId}</artifactId>
          <version>${project.version}</version>
          <executions>
            <execution>
              <id>integration-test</id>
              <goals>
                <goal>integration-test</goal>
              </goals>
            </execution>
            <execution>
              <id>verify</id>
              <goals>
                <goal>verify</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>
  [...]
</project>
+---+

#{end}