Maven — Debugging JUnit tests
All IDEs provide facility to run and debug JUnit tests. It is, however, not always possible to run application from IDE and we have only option to run it from command line using mvn command. There we can run tests in debug mode using following command:
mvn -Dmaven.surefire.debug test
Example
Let’s create a very simple project with a JUnit test.
Run the test from project root
D:\LogicBig\example-projects\maven\maven-debug-test>mvn -Dmaven.surefire.debug test [INFO] Scanning for projects. [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building maven-debug-test 1.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-resources-plugin:2.6:resources (default-resources) @ maven-debug-test --- [WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent! [INFO] Copying 0 resource [INFO] [INFO] --- maven-compiler-plugin:3.5.1:compile (default-compile) @ maven-debug-test --- [INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-resources-plugin:2.6:testResources (default-testResources) @ maven-debug-test --- [WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent! [INFO] skip non existing resourceDirectory D:\LogicBig\example-projects\maven\maven-debug-test\src\test\resources [INFO] [INFO] --- maven-compiler-plugin:3.5.1:testCompile (default-testCompile) @ maven-debug-test --- [INFO] Nothing to compile - all classes are up to date [INFO] [INFO] --- maven-surefire-plugin:2.12.4:test (default-test) @ maven-debug-test --- [INFO] Surefire report directory: D:\LogicBig\example-projects\maven\maven-debug-test\target\surefire-reports ------------------------------------------------------- T E S T S ------------------------------------------------------- Listening for transport dt_socket at address: 5005
The last line indicates that maven has automatically paused and will wait for a remote debugger to connect at port 5005.
In the next step, we have to setup our IDE (where our project source is) to debug the tests remotely.
Following video shows how to do that. We are using Intellij IDE. Setting up remote debugger from IDE is just like setting up the debugger for remote server application.
If we want to change the port then we can use following command:
mvn -Dmaven.surefire.debug="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000 -Xnoagent -Djava.compiler=NONE" test
Example Project
Dependencies and Technologies Used:
- junit 4.12: JUnit is a unit testing framework for Java, created by Erich Gamma and Kent Beck.
- JDK 1.8
- Maven 3.3.9
Debug Tests using Maven
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:
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 testWith 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: 5005Note 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" testHere, 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:
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 verifyAs 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" verifyThe 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.