Integration Testing With the Maven Cargo Plugin
Last updated: August 7, 2025
Mocking is an essential part of unit testing, and the Mockito library makes it easy to write clean and intuitive unit tests for your Java code.
Get started with mocking and improve your application tests using our Mockito guide:
Handling concurrency in an application can be a tricky process with many potential pitfalls. A solid grasp of the fundamentals will go a long way to help minimize these issues.
Get started with understanding multi-threaded applications with our Java Concurrency guide:
Spring 5 added support for reactive programming with the Spring WebFlux module, which has been improved upon ever since. Get started with the Reactor project basics and reactive programming in Spring Boot:
Since its introduction in Java 8, the Stream API has become a staple of Java development. The basic operations like iterating, filtering, mapping sequences of elements are deceptively simple to use.
But these can also be overused and fall into some common pitfalls.
To get a better understanding on how Streams work and how to combine them with other language features, check out our guide to Java Streams:
Explore Spring Boot 3 and Spring 6 in-depth through building a full REST API with the framework:
Yes, Spring Security can be complex, from the more advanced functionality within the Core to the deep OAuth support in the framework.
I built the security material as two full courses - Core and OAuth, to get practical with these more complex scenarios. We explore when and how to use each feature and code through it on the backing project.
You can explore the course here:
Spring Data JPA is a great way to handle the complexity of JPA with the powerful simplicity of Spring Boot.
Get started with Spring Data JPA through the guided reference course:
Refactor Java code safely — and automatically — with OpenRewrite.
Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.
Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.
Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.
Distributed systems often come with complex challenges such as service-to-service communication, state management, asynchronous messaging, security, and more.
Dapr (Distributed Application Runtime) provides a set of APIs and building blocks to address these challenges, abstracting away infrastructure so we can focus on business logic.
In this tutorial, we'll focus on Dapr's pub/sub API for message brokering. Using its Spring Boot integration, we'll simplify the creation of a loosely coupled, portable, and easily testable pub/sub messaging system:
Get up to speed with the core of Maven quickly, and then go beyond the foundations into the more powerful functionality of the build tool, such as profiles, scopes, multi-module projects and quite a bit more:
Distributed systems often come with complex challenges such as service-to-service communication, state management, asynchronous messaging, security, and more.
Dapr (Distributed Application Runtime) provides a set of APIs and building blocks to address these challenges, abstracting away infrastructure so we can focus on business logic.
In this tutorial, we'll focus on Dapr's pub/sub API for message brokering. Using its Spring Boot integration, we'll simplify the creation of a loosely coupled, portable, and easily testable pub/sub messaging system:
1. Overview
A very common need in the lifecycle of a project is setting up integration testing. In this tutorial, we’ll see how to set up this scenario using the Maven Cargo plugin.
2. Maven Integration Test Build Phases
Luckily, Maven has built-in support for this exact scenario, with the following phases of the default build lifecycle (from the Maven documentation):
- pre-integration-test: Perform actions required before integration tests are executed. This may involve things such as setting up the required environment.
- integration-test: Process and deploy the package if necessary into an environment where integration tests can be run.
- post-integration-test: Perform actions required after integration tests have been executed. This may including cleaning up the environment.
3. Set Up Cargo Plugin
Let’s go over the setup required, step by step.
3.1. Exclude Integration Tests from the Surefire Plugin
First, the maven-surefire-plugin is configured so that integration tests are excluded from the standard build lifecycle:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.22.2</version>
<configuration>
<excludes>
<exclude>**/*IntegrationTest.java</exclude>
</excludes>
</configuration>
</plugin>Exclusions are done via ant-style path expressions, so all integration tests must follow this pattern and end with “IntegrationTest.java“.
3.2. Configure the Cargo Plugin
Next, the cargo-maven3-plugin is used, as Cargo comes with top-notch out-of-the-box support for embedded web servers. Of course, if the server environment requires a specific configuration, cargo also knows how to construct the server out of an archived package as well as deploy to an external server.
<plugin>
<groupId>org.codehaus.cargo</groupId>
<artifactId>cargo-maven3-plugin</artifactId>
<version>1.9.9</version>
<configuration>
<configuration>
<properties>
<cargo.servlet.port>8080</cargo.servlet.port>
</properties>
</configuration>
</configuration>
</plugin>A default embedded Jetty 9 web server is defined, listening on port 8080.
In the newer version of cargo (1.1.0 upwards), the default value of the wait flag has been changed to false, for cargo:start. This goal should only be used for running integration tests and is bound to the Maven lifecycle; for development, the cargo:run goal should be executed instead – which has wait=true.
In order for the package maven phase to generate a deployable war file, the packaging of the project must be <packaging>war</packaging>.
3.3. Add a New Maven Profile
Next, a new integration Maven profile is created to enable running the integration tests only when this profile is active, and not as part of the standard build lifecycle.
<profiles>
<profile>
<id>integration</id>
<build>
<plugins>
...
</plugins>
</build>
</profile>
</profiles>It is this profile that will contain all the remaining configuration details.
Now, the Jetty server is configured to start in the pre-integration-test phase and stop in the post-integration-test phase.
<plugin>
<groupId>org.codehaus.cargo</groupId>
<artifactId>cargo-maven3-plugin</artifactId>
<executions>
<execution>
<id>start-server</id>
<phase>pre-integration-test</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>stop-server</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>This ensures the cargo:start goal and cargo:stop goals will execute before and after the integration-test phase. Note that because there are two individual execution definitions, the id element must be present (and different) in both, so that Maven can accept the configuration.
3.4. Configure Integration Tests in the New Profile
Next, the maven-surefire-plugin configuration needs to be overridden inside the integration profile, so that the integration tests which were excluded in the default lifecycle are will now be included and run:
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<executions>
<execution>
<phase>integration-test</phase>
<goals>
<goal>test</goal>
</goals>
<configuration>
<excludes>
<exclude>none</exclude>
</excludes>
<includes>
<include>**/*IntegrationTest.java</include>
</includes>
</configuration>
</execution>
</executions>
</plugin>
</plugins>There are a few things worth noting:
1. The test goal of the maven-surefire-plugin is executed in the integration-test phase; at this point, Jetty is already started with the project deployed, so the integration tests should run with no problems.
2. The integration tests are now included in the execution. In order to achieve this, the exclusions are also overridden – this is because of the way Maven handles overriding plugin configurations inside profiles.
The base configuration is not completely overridden, but rather augmented with new configuration elements inside the profile.
Because of this, the original <excludes> configuration, which excluded the integration tests in the first place, is still present in the profile and needs to be overridden, or it would conflict with the <includes> configuration and the tests would still not run.
3. Note that, since there is only a single <execution> element, there is no need for an id to be defined.
Now, the entire process can run:
mvn clean install -Pintegration
4. Conclusion
The step-by-step configuration of Maven covers the entire process of setting up the integration process as part of the project lifecycle.
Usually, this is set up to run in a Continuous Integration environment, preferably after each commit. If the CI server already has a server running and consuming ports, then the cargo configuration will have to deal with that scenario, which I will cover in a future post.
Also, check out this article for best practices of structuring a project and organizing the unit and integration tests.
