Run integration tests with Maven Failsafe plugin

The Failsafe plugin is the de facto Maven plugin designed to run integration tests. Similar to the Surefire plugin that runs unit tests, Failsafe can be configured to run integration tests in a Maven goal. It provides enough flexibility to specify the goal and integration tests file convention. In this article, I go through how to run integration tests using the Maven Failsafe plugin.

The first thing is to add some integration tests. Let’s create a DummyTestIT.java file.

Note that the file ends with IT.java that’s because Failsafe plugin marks any files that ended with *IT.java, IT*.java, or *ITCase.java as an integration test.

Our test case would be a simple assertion like below.

class DummyTestIT {
    @Test
    void alwaysTrue() {
        assertTrue(true);
    }
}

Now we have to configure the plugin in Maven. The objective is to run integration tests when executing a Maven goal. The best practice says we should run the integration test during the verify stage. For that, we add the plugin as follows,

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-failsafe-plugin</artifactId>
      <version>3.0.0-M3</version>
      <executions>
        <execution>
          <goals>
            <goal>integration-test</goal>
            <goal>verify</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

That’s all it takes to configure the project. It’s time to test whether it works or not.

For that, we run this maven command,

$ mvn clean verify

This should execute both unit and integration tests. On the other hand, if you run,

$ mvn clean test

Only unit tests should run not integration tests. If both ran, means something is wrong with your configuration.

If you are not fond of the default file convention, don’t worry, you can change that very easily by using includes tag. Similar to this,

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <version>3.0.0-M3</version>
  <configuration>
    <skipTests>false</skipTests>
    <rerunFailingTestsCount>3</rerunFailingTestsCount>
    <includes>
      <include>**/*IT.java</include>
    </includes>
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
</plugin>

In addition to the file type, the above snippet supports the retry mechanism. It retries three times before failing the test. This particularly is useful when tests call third party services.

Conclusion

What I have demonstrated in this post is a simplified version of the Failsafe plugin can do. You can achieve much more with the plugin. Failsafe supports different test provides, custom test results reporting, multi-module projects, and so on. To learn about them I highly recommend referring to the official documentation.

If you curious how to use the Failsafe plugin with Testcontainers have a look at Integration test with testcontainers in Java article.