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>3.8.1</version>
        <configuration>
          <cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
          <settingsFile>src/it/settings.xml</settingsFile>
          <localRepositoryPath>${project.build.directory}/local-repo</localRepositoryPath>
          <postBuildHookScript>verify</postBuildHookScript> <!-- no extension required -->
        </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 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 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 usually 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 Using Pre and 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*.