Spring Boot Integration Test

Posted on In ,

This post shows how to run integration tests in a Spring Boot project with Maven, including the required pom.xml changes and the most useful commands for daily development and CI.

Spring Boot Integration Test

In Maven projects, integration tests are usually separated from unit tests:

  • Unit tests run in the test phase with maven-surefire-plugin.
  • Integration tests run in integration-test and verify phases with maven-failsafe-plugin.

This separation keeps fast feedback for unit tests while still allowing full end-to-end validation.

Naming Convention for Integration Tests

By default, Failsafe looks for test class names like:

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

Example:

1
2
3
4
5
6
7
8
@SpringBootTest
class UserApiIT {

  @Test
  void shouldCreateUserSuccessfully() {
    // integration test logic
  }
}

pom.xml Changes

Maven Surefire Plugin (Unit Tests)

The Surefire plugin runs unit tests during the test phase. Configure it to ensure tests are not skipped:

1
2
3
4
5
6
7
8
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>3.2.5</version>
  <configuration>
    <skipTests>false</skipTests>
  </configuration>
</plugin>

Maven Failsafe Plugin (Integration Tests)

The Failsafe plugin runs integration tests during the integration-test and verify phases. The minimal required configuration is:

1
2
3
4
5
6
7
8
9
10
11
12
13
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-failsafe-plugin</artifactId>
  <version>3.2.5</version>
  <executions>
    <execution>
      <goals>
        <goal>integration-test</goal>
        <goal>verify</goal>
      </goals>
    </execution>
  </executions>
</plugin>

By default, Failsafe automatically includes tests matching *IT.java and *ITCase.java patterns. This configuration is sufficient for most projects.

Optional: Custom Include Patterns

If you need to customize which test files are included in Failsafe, add the optional <configuration> block:

1
2
3
4
5
6
<configuration>
  <includes>
    <include>**/*IT.java</include>
    <include>**/*ITCase.java</include>
  </includes>
</configuration>

Use this when you have non-standard naming conventions for your integration tests or want to be explicit about the patterns.

Both plugins should be added to <build><plugins> in your pom.xml. If you use Spring Boot parent, plugin versions can also be managed in pluginManagement. Keeping explicit versions is still clear for readers.

Commands to Run Tests

Run Unit Tests Only

1
mvn test

Run Integration Tests (with full lifecycle)

1
mvn verify

This command runs unit tests first, then integration tests via Failsafe.

Run Only Integration Tests

1
mvn verify -DskipTests

-DskipTests skips unit tests from Surefire, but integration tests still run in Failsafe phases.

Skip Integration Tests

1
mvn verify -DskipITs

Add this in Failsafe configuration if you want the skipITs switch:

1
2
3
<configuration>
  <skipITs>${skipITs}</skipITs>
</configuration>

Typical CI Command

In CI pipelines, a common command is:

1
mvn -B clean verify
  • -B / --batch-mode: run Maven non-interactively (prevents prompts and prints machine-friendly logs).

Summary

To run Spring Boot integration tests correctly with Maven:

  1. Name integration test classes with *IT pattern.
  2. Configure maven-failsafe-plugin for integration-test and verify goals.
  3. Use mvn verify in CI to validate the full test lifecycle.

This setup gives clear separation between fast unit testing and realistic integration verification.