Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 41 ยท Testing and Quality

Integration Tests with Failsafe

Separate slow integration tests from unit tests with the Maven Failsafe plugin: IT naming, the verify phase, why two plugins exist, and how to run and skip them.

Unit tests check one class at a time and finish in milliseconds. Integration tests check that the parts work together: your code with a real database, a running web server, or the packaged jar. They are slower, they need setup and cleanup, and they can leave things running when they fail. Maven handles them with a second plugin, Failsafe, and two extra phases around the tests.

This lesson explains why Maven separates the two kinds of tests, how to configure Failsafe, and which command to run. The commands need a real Maven installation, so they are read-only here. The runnable parts are Java stand-ins: a classifier that sorts test classes between the two plugins, and a phase simulator that shows why Failsafe fails the build late on purpose. You should be comfortable with Running Tests with Surefire first.

Why a second plugin?

Surefire runs in the test phase, which comes before package. That is fine for unit tests, but an integration test often needs the packaged artifact, or a server started from it. And if Surefire fails, the build stops immediately, so nothing gets a chance to stop that server again.

Failsafe is designed for this. It runs in the integration-test phase, which comes after package, and it does not fail the build at that point. It records the results and lets the build continue to post-integration-test, where you shut things down. Only then, in the verify phase, does the Failsafe verify goal read the results and fail the build if any test failed.

Plugin Goal Default phase Fails the build in
Surefire test test test
Failsafe integration-test integration-test does not fail here
Failsafe verify verify verify
flowchart LR
  P["package"] --> PRE["pre-integration-test<br/>(start server)"]
  PRE --> IT["integration-test<br/>(Failsafe runs ITs)"]
  IT --> POST["post-integration-test<br/>(stop server)"]
  POST --> V["verify<br/>(Failsafe checks results)"]

Cleanup runs even when a test failed, because the failure is reported only at verify.

Naming and configuration

Failsafe finds tests by file name, like Surefire, but with different patterns:

  • **/IT*.java
  • **/*IT.java
  • **/*ITCase.java

So PriceTest belongs to Surefire and PriceIT belongs to Failsafe. Keeping the two sets of names apart is the whole mechanism: it is how a single src/test/java folder can hold both kinds.

Unlike Surefire, Failsafe is not active by default. Packaging jar binds Surefire to test but binds nothing for Failsafe, so you declare the plugin and its two goals:

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

An execution with goals but no explicit phase uses each goal's default phase, so this runs the tests in integration-test and the check in verify. A very common mistake is to declare only integration-test and forget verify: then failing integration tests never fail the build.

Unit test or integration test?

Unit test One class, no I/O, runs in milliseconds.
Integration test Real parts working together.

If it needs a database, a port or the jar, it is an IT.

1 / 2

Which command to run

Run mvn verify to execute everything: unit tests, packaging, integration tests and the final check. Do not stop at mvn integration-test. That command runs the tests but skips verify, so a failure is recorded but not reported, and your pipeline would show green. mvn install and mvn deploy include verify, so they are safe as well.

To run only some integration tests, use the same filter style as Surefire but with the Failsafe property:

Terminal
mvn verify -Dit.test=PriceIT
mvn verify -Dit.test='Order*IT'

Two skip switches are useful:

  • -DskipITs skips only the integration tests and still runs unit tests.
  • -DskipTests skips both Surefire and Failsafe.

So mvn verify -DskipITs is the command for "run the quick checks and package, but not the slow tests", a common pre-commit routine. Reports are written to target/failsafe-reports, next to (not inside) the Surefire reports.

Starting and stopping what the tests need

The phases pre-integration-test and post-integration-test exist so other plugins can prepare and clean up. Typical uses are starting an embedded server or a container before the tests and stopping it after. The idea is always the same: bind one goal to pre-integration-test and one to post-integration-test, and Failsafe runs in between.

Today many projects skip those phases and let the test code manage its own dependencies. A library such as Testcontainers starts a real database in a Docker container from inside the test, and stops it when the test ends. That keeps the whole setup in Java, close to the test that needs it, and works the same on a laptop and in CI. You still use Failsafe, so those slow, Docker-dependent tests stay out of the quick mvn test run. Docker itself is outside this tutorial; the Docker tutorial on this site covers it.

A good rule: if a test needs something outside the JVM (a port, a file system layout, a container, a network call), name it *IT. Then mvn test stays fast and reliable, and mvn verify stays complete.

Configuration you will meet

A few settings appear in real projects:

  • <classesDirectory> and <additionalClasspathElements> let ITs run against the packaged jar rather than loose classes, which is the point of running after package.
  • <systemPropertyVariables> passes values such as the port of the server your test started.
  • <trimStackTrace>false</trimStackTrace> shows full stack traces when diagnosing a failure.
  • <rerunFailingTestsCount> retries failing ITs. It is more tempting for ITs than for unit tests, because they are flakier by nature. Use it to measure flakiness, not to hide it.

Stand-in: classify the tests

The first program applies the two naming rules to a list of class names and shows which plugin would pick each one. The real plugins use the same idea with glob patterns on compiled classes.

Java Surefire or Failsafe?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

PriceSpec and Helper match neither rule, so no plugin runs them. Notice that the integration check comes first: a name such as CheckoutIT ends with IT and not with Test, so the order only matters for odd names like ITTest.

Stand-in: why verify fails late

The second program simulates the five phases around the integration tests. It runs the same build twice. In the first run an integration test fails; you can see that the "server" is still stopped in post-integration-test and that the failure is reported in verify. For contrast, the second run models a build that fails right in the test phase, where nothing gets to clean up.

Java Phase split simulator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The second run leaves the server running. In real life that means a port stays occupied, a container keeps running, or a database stays locked, and the next build fails for a confusing reason. Failsafe's design avoids that by splitting "run the tests" from "judge the results".

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which phase does the Failsafe verify goal belong to?

    The verify goal runs in the verify phase and fails the build if the recorded integration tests failed.
  2. 2. Why does Failsafe not fail the build in the integration-test phase?

    Failing late guarantees the cleanup phase runs, even when a test failed.
  3. 3. Which command is the safe way to run integration tests and fail the build on a failure?

    mvn integration-test stops before the verify goal, so failures would not fail the build. mvn verify (or install) includes it.
  4. 4. Which flag skips integration tests but still runs unit tests?

    -DskipITs targets Failsafe only. -DskipTests skips both plugins.
  5. 5. Which class name does the default Failsafe configuration pick up?

    Failsafe's defaults are IT*, *IT and *ITCase. PriceTest belongs to Surefire.

Summary

  • Integration tests check parts working together; they are slower and need setup, so they run apart from unit tests.
  • Surefire runs *Test classes in test; Failsafe runs *IT classes in integration-test and checks results in verify.
  • Failsafe must be declared with both the integration-test and verify goals.
  • Use mvn verify, not mvn integration-test; -DskipITs skips only integration tests.
  • pre- and post-integration-test exist for starting and stopping what tests need; Testcontainers does this from inside the test.
  • Failing late is what guarantees cleanup.

Next: Code Quality: Coverage and Static Checks