1. Overview

In this tutorial, we're going to look at how we can debug our unit tests and integration tests using Maven. For this purpose, we'll examine the Maven Surefire and Failsafe plugins.

2. Debug Unit Tests

When we execute mvn clean test, it is the Maven Surefire plugin that runs our tests. By default, it picks the test classes with the following name patterns:

  • Test*.java
  • *Test.java
  • *Tests.java
  • *TestCase.java

2.1. Default Port

Maven Surefire plugin has built-in support for debugging. We must just pass the JVM argument maven.surefire.debug when running our tests:

mvn -Dmaven.surefire.debug test

With this command, Maven compiles our code but suspends before running our unit tests. Additionally, It listens on port 5005 for the incoming debug sessions.

Listening for transport dt_socket at address: 5005

Note that maven waits until we attach a debugger.

2.2. Custom Port

To use a different debug port other than 5005, we must pass additional JVM options:

mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8090" test

Here, we're passing two JVM options to the Surefire plugin. Firstly, -Xdebug enables debugging. Then -Xrunjdwp configures the debug process with some key-value pairs:

  • transport=dt_scoket enables connections over a socket.
  • server=y designates our Maven process as the server, so it'll listen for the debugger applications to connect.
  • suspend=y makes Maven wait for a debugger application. So it'll suspend right before the tests.
  • address=8090 sets the debug port. Thus the debugger clients should use this port instead of the default one.

The outcome is very similar to the previous configuration except that the clients must use the port 8090 instead of 5005.

3. Debug Integration Tests

Now that we have seen how to debug unit tests, we'll now look at how we can debug integration tests.

When we run mvn clean verify, Maven executes the integration tests by the help of Maven Failsafe plugin. By default, the Failsafe plugin picks the integration test classes with the following name patterns:

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

3.1. Default Port

Maven Failsafe plugin also has built-in support for debugging. Firstly, we'll debug our integration tests with the default options:

mvn -Dmaven.failsafe.debug verify

As a result, Maven compiles the code but pauses right before executing the integration tests. It waits for a debugger application to connect on port 5005.

3.2. Custom Port

Similar to the Surefire plugin, we can also define a custom port for debugging integration tests.

mvn -Dmaven.failsafe.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8090" verify

The result is very similar to the previous configuration. But this time, clients must connect to Maven on port 8090.

4. Summary

In this tutorial, we've looked at how we can debug our unit tests and integration tests using Maven. We examined the different options that Maven Surefire and Failsafe plugins provide.

As always, the source code for all examples is available on Github.