Skip to content
javahacks.dev
JUnit

How to Run JUnit From Maven Surefire and Failsafe Plugins

Understand which Maven plugin runs which tests: Surefire for unit tests, Failsafe for integration tests, naming patterns, lifecycle phases and common fixes.

6 min read
Summarize in AI
Flat illustration of a JUnit test run with one failing test, with the JUnit5, Apache Maven, Docker and Cucumber logos.

Two Maven plugins run tests, and the split between them is deliberate. Surefire runs fast unit tests early in the lifecycle. Failsafe runs integration tests later, after the artifact is packaged, and it is built so that a failing test does not skip the cleanup that has to follow. Mixing them up is the most common reason an OrderIT class "never runs". This post uses Maven 3.9, JUnit Jupiter 6 and Java 25, and explains which plugin runs what, how to configure both, the commands that select tests, and how to keep forks and reports sane. If JUnit tests are not detected at all, start with tests not running.

Which phase runs which tests

PluginGoalPhaseDefault names
SurefiretesttestTest*, *Test, *Tests, *TestCase
Failsafeintegration-testintegration-testIT*, *IT, *ITCase
Failsafeverifyverifynot applicable

The Failsafe split has a purpose. Imagine an integration test that needs a database container. You start the container in pre-integration-test, run the tests in integration-test, and stop the container in post-integration-test. If a test fails inside integration-test, Failsafe records the failure and lets the build continue to post-integration-test, so the container is stopped. Then verify reads the result and fails the build. With Surefire in the earlier test phase, a failure ends the build at once and nothing after it, including cleanup, ever runs.

That also explains the naming convention. A class named OrderIT is invisible to Surefire and a class named PriceTest is invisible to Failsafe, which keeps the groups apart without any configuration.

Configure both, with versions

XML
<build>
  <plugins>
    <plugin>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.5.3</version>
    </plugin>
    <plugin>
      <artifactId>maven-failsafe-plugin</artifactId>
      <version>3.5.3</version>
      <executions>
        <execution>
          <goals>
            <goal>integration-test</goal>
            <goal>verify</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Surefire is bound by default, so it needs no executions. Failsafe is not, so the executions block is what switches it on. Without it, mvn verify finishes green and OrderIT never ran, because nothing asked Failsafe to do anything.

Always set the versions. Old default versions of these plugins do not detect JUnit 5 or 6 tests, and the symptom is a build that reports "No tests to run". Spring Boot's parent POM already pins working versions, which is one reason to inherit it, and the idea is explained in Maven BOMs.

The commands that matter

Shell
./mvnw test
./mvnw verify
./mvnw verify -DskipITs
./mvnw verify -DskipTests
./mvnw test -Dtest=PriceTest
./mvnw verify -Dit.test=OrderIT

test runs Surefire alone, so it never runs Failsafe, and people expecting OrderIT to run under mvn test are surprised. verify runs both, because it comes after integration-test in the lifecycle. -DskipITs skips only Failsafe, which keeps package and verify working when you just want to build quickly. -DskipTests skips both, and -Dmaven.test.skip=true goes further and does not even compile the tests, which is rarely what you want.

To run one class, use -Dtest for Surefire and -Dit.test for Failsafe. They are different properties because they are different plugins. A common mistake is passing -Dtest=OrderIT to verify and getting "No tests were executed" from Surefire; add -Dsurefire.failIfNoSpecifiedTests=false or use the right property.

Tags instead of file names

Name patterns are one way to separate the groups. JUnit tags are another, and they leave the class name free:

XML
<configuration>
  <groups>integration</groups>
</configuration>

With tags, Surefire excludes integration and Failsafe includes it, and the filename carries no meaning. The expression syntax and a vocabulary that holds up are in filtering with tags. Whichever you choose, keep one convention across the team. A project that mixes *IT classes and tagged classes ends up with tests that run in neither stage.

Forks, JVM flags and parallel runs

Both plugins start a forked JVM for the tests. forkCount controls how many JVMs run at once and reuseForks whether a JVM serves several test classes. The defaults, one fork reused for every class, are fast and share static state between classes, which can make order-dependent tests pass or fail unexpectedly. Setting reuseForks to false isolates classes at the price of startup time for each.

The argLine setting passes flags to the forked JVM, such as memory limits and agents. Coverage tools use it, and a plugin that overwrites argLine rather than appending to it silently turns coverage off. Use @{argLine} as a late-bound placeholder when you set your own, as described in JaCoCo. Parallelism inside a JVM is JUnit's job and not Maven's, covered in parallel execution.

Reading a failing build

When mvn verify fails, the order of the log tells you which plugin spoke. A failure printed under the Surefire banner came from a unit test, and the build stopped there. A failure under the Failsafe banner appears in integration-test but the build is marked failed only at the verify goal, a few lines later. People often scroll to the first red line and miss that cleanup ran between the two. Read from the summary line "Tests run: ..., Failures: ..." for each plugin and then open the report for the class named.

One more trap is the difference between failures and errors. A failure is an assertion that did not hold. An error is an unexpected exception, such as a NullPointerException or a container that did not start. Both fail the build, and they point at different kinds of fix.

Where the results go

Both plugins write reports as text and XML to target/surefire-reports and target/failsafe-reports. CI servers read the XML to draw test trends, so point their report patterns at both directories, or the integration results will be missing from the dashboard while the build is green or red correctly. When a test fails, the plain-text file for that class holds the stack trace and the captured output, and it is the first place to look.

Selecting what runs, from the command line

Most daily use of the two plugins is running a subset. The properties differ between the plugins, and mixing them up is the common mistake:

Shell
./mvnw test -Dtest=OrderServiceTest                  # one class with Surefire
./mvnw test -Dtest='OrderServiceTest#appliesDiscount'  # one method
./mvnw verify -Dit.test=OrderRepositoryIT            # one class with Failsafe
./mvnw verify -DskipTests                            # build and package, run nothing
./mvnw verify -DskipITs                              # unit tests only, skip Failsafe
./mvnw test -Dtest='*Service*' -Dsurefire.failIfNoSpecifiedTests=false

-Dtest belongs to Surefire and -Dit.test to Failsafe, so -Dtest=OrderRepositoryIT selects nothing on test and does not run the integration test, because Surefire excludes *IT by default. In a multi-module build the last option stops the build from failing in modules that contain no matching test.

Retrying a flaky test, honestly

Surefire and Failsafe can rerun a failing test, and the report marks tests that passed on a retry as flaky:

XML
<plugin>
  <artifactId>maven-failsafe-plugin</artifactId>
  <configuration>
    <rerunFailingTestsCount>1</rerunFailingTestsCount>
  </configuration>
</plugin>

Use it for the integration stage, against infrastructure that can hiccup, and read the flaky list as a to-do, not as a pass. A suite that goes green only because of reruns is hiding a problem that will show up as a real failure later, so count the flaky tests each week and fix them by owner. Do not turn it on for unit tests, where a test that fails once is a bug in the test or in the code.

When Maven is not the build

Gradle has no Surefire or Failsafe. It runs unit tests with the test task and integration tests with a second Test task that you register. The model is simpler and the principle is identical. The plugin pages, Surefire and Failsafe, document every option.

Also inDevOps
Taggedhow to
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.