------
 Usage
 ------
 Jason van Zyl
 ------
 2008-08-02
 ------

 ~~ 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

  This page provides general usage information along with a basic example.  The plugin
  is commonly used to run and verify integration tests for a project, say a Maven plugin.  This is done using
  the <<<{{{./run-mojo.html} invoker:run }}>>> goal. And as a preparation for the integration tests, one usually wants to
  stage the artifacts under tests into a testing repository. For this job, the
  <<<{{{./install-mojo.html} invoker:install }}>>> goal can be used.

* Basic Example

  The following example demonstrates a basic plugin configuration for running integration tests. Let's assume the following
  directory structure of your project:

+------------------
./
+- pom.xml
+- src/
   +- it/
      +- settings.xml
      +- first-it/
      |  +- pom.xml
      |  +- src/
      +- second-it/
         +- pom.xml
         +- invoker.properties
         +- test.properties
         +- verify.bsh
         +- src/
+------------------

  In this example, the directory <<<src/it>>> is the location where all the IT projects reside. You simply put each
  integration test into a distinct sub directory, like shown by <<<first-it>>> and <<<second-it>>>. The plugin
  configuration for this example would look like this:

+------------------
<project>
  ...
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-invoker-plugin</artifactId>
        <version>${project.version}</version>
        <configuration>
          <projectsDirectory>src/it</projectsDirectory>
          <cloneProjectsTo>\${project.build.directory}/it</cloneProjectsTo>
          <pomIncludes>
            <pomInclude>*/pom.xml</pomInclude>
          </pomIncludes>
          <settingsFile>src/it/settings.xml</settingsFile>
          <localRepositoryPath>\${project.build.directory}/local-repo</localRepositoryPath>
          <postBuildHookScript>verify.bsh</postBuildHookScript>
        </configuration>
        <executions>
          <execution>
            <id>integration-test</id>
            <goals>
              <goal>install</goal>
              <goal>run</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  ...
</project>
+------------------

  Now, to get things going, just tell Maven to execute the lifecycle phase <<<integration-test>>>:

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

  First, the <<<invoker:install>>> goal will be executed during the phase <<<pre-integration-test>>> and will copy the
  main artifact of the project along with any attached artifacts over to <<<target/local-repo>>>. Furthermore, any
  locally reachable parent POMs of the project will be copied to the staging repository. Last but not least, if you are
  running a reactor build, all project dependencies that reside in the reactor will be staged, too.

  Next up, the <<<invoker:run>>> goal will execute during the phase <<<integration-test>>> and will use the configured
  include/exclude patterns to search the directory <<<src/it>>> for IT POMs. Every directory where an IT POM is found
  will be copied over to <<<target/it>>>. Additionally, the IT POMs will be filtered, i.e. expressions like
  <<<@project.version@>>> will be replaced with the corresponding values from the project's POM. This is especially
  handy to make sure your IT POMs always reference the currently built version of the project artifact. You can also
  define other properties via the plugin configuration that you wish to use for filtering.

  Once the IT POMs have been filtered, a Maven build will be started on them. By default, the Invoker Plugin will execute the
  phase <<<package>>> on the IT POMs but that can be changed globally in the plugin configuration or for an individual
  integration test by using the <<<{{{./examples/invoker-properties.html}invoker.properties}}>>> as done in the example
  for <<<second-it>>>. Likewise, system properties can be passed to the IT builds via the file <<<test.properties>>>.
  And the file <<<src/it/settings.xml>>> can be used to specify custom user settings for the tests. Among others, this
  allows you to make the integration tests use your local repository as a remote repository, avoiding time-consuming
  downloads from <<<central>>> in order to fill up the initially empty staging repository. Please see the example
  {{{./examples/fast-use.html}Fast Invoker Plugin Configuration}} for more details on this technique. The output of the
  IT builds is written to a log file named <<<build.log>>> (e.g. <<<target/it/first-it/build.log>>>) and allows
  diagnostics in case an integration test fails.

  When an integration test has finished, the plugin will invoke an optional post build hook script. In the example,
  this is the case for <<<second-it>>> where <<<verify.bsh>>> will be run. The purpose of this script is usally to
  check that the build of the integration test did not only succeed but also produced the intended output. Have a look
  at the example {{{./examples/post-build-script.html}Using a Post Build Script}} for a code snippet.

* Running Only Some Tests

  The plugin also supports a parameter <<<-Dinvoker.test>>> to run only ITs in the directories matched by the patterns
  used in the parameter. This enables you to quickly rerun individual tests. See this example command line:

+---
  mvn invoker:run -Dinvoker.test=*MWAR*,simple*
+---

  Assuming the base directory of the sub projects is <<<src/it>>>, the plugin will only run projects from directories
  matching the path <<<src/it/*MWAR*>>> and <<<src/it/simple*>>>.