Guide to Running Unit Tests with Maven

Learn to run JUnit tests using Maven Surefire Plugin. We will learn to run a single test, run only selected tests or run all the tests in the project.

//Run all tests
$ mvn test

//Run a single test class
$ mvn -Dtest=TestClassOne test

//Run multiple test classes
$ mvn -Dtest=TestClassOne,TestClassTwo test

//Run a single test method
$ mvn -Dtest=TestClassOne#methodname test

//Run tests matching name 'testMethod' in all test classes
$ mvn -Dtest="*#testMethod" test

//Run tests matching name 'test*' in a test class 
$ mvn -Dtest="TestClassOne#test*" test

//Rerun failing tests 2 times
mvn '-Dsurefire.rerunFailingTestsCount=2' -Dtest=ModuleTwoTests test

1. Setup

Begin with importing the latest version of maven-surefire-plugin.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>3.0.0-M7</version>
    </plugin>
  </plugins>
</build>

The surefire plugin, by default, supports all tests written in JUnit 4 and JUnit 5. It automatically detects the JUnit version and uses the appropriate runner for executing the tests.

For JUnit 4, include the latest version of JUnit 4; for JUnit 5, include the latest version of junit-jupiter-api which transitively pulls in the other required dependencies.

<!-- For JUnit 5 -->
<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter-api</artifactId>
  <version>5.9.0</version>
  <scope>test</scope>
</dependency>

<!-- For JUnit 4 -->
<dependency>
  <groupId>junit</groupId>
  <artifactId>junit</artifactId>
  <version>4.13.2</version>
  <scope>test</scope>
</dependency>

We are using the following test classes and methods for demo purposes.

public class ModuleOneTests {
	@Test public void testMethodOne() {...}
	@Test public void testMethodTwo() {...}
}

public class ModuleTwoTests {
	@Test public void testMethodOne() {...}
	@Test public void testMethodTwo() {...}
	@Test public void testMethodThree() {...}
	@Test public void testMethodFour() {...}
}

2. Executing JUnit Tests

Let us check out various ways to execute tests.

2.1. Execute All Test Classes and Methods

To execute all tests run the 'mvn test' command.

$ mvn test

INFO: Executing ModuleOneTests#testMethodOne
INFO: Executing ModuleOneTests#testMethodTwo
...
INFO: Executing ModuleTwoTests#testMethodOne
INFO: Executing ModuleTwoTests#testMethodTwo
INFO: Executing ModuleTwoTests#testMethodThree
INFO: Executing ModuleTwoTests#testMethodFour
...
[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0

2.2. Execute All Test Methods in Test Class

Pass the '-Dtest=TestClass' for executing all tests in a test class.

$ mvn -Dtest=ModuleOneTests test

INFO: Executing ModuleOneTests#testMethodOne
INFO: Executing ModuleOneTests#testMethodTwo
...
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

Pass the name of test classes in double-quotes in syntax -Dtest="TestClassOne,TestClassTwo" for executing all tests in multiple test classes.

$ mvn -Dtest="ModuleOneTests,ModuleTwoTests" test

INFO: Executing ModuleOneTests#testMethodOne
INFO: Executing ModuleOneTests#testMethodTwo
...
INFO: Executing ModuleTwoTests#testMethodOne
INFO: Executing ModuleTwoTests#testMethodTwo
INFO: Executing ModuleTwoTests#testMethodThree
INFO: Executing ModuleTwoTests#testMethodFour
...
[INFO] Tests run: 6, Failures: 0, Errors: 0, Skipped: 0

2.3. Execute a Single Test Method

Pass the '-Dtest=TestClass#testMethod' for executing a specific test method in a test class.

$ mvn -Dtest=ModuleOneTests#testMethodOne test

INFO: Executing ModuleOneTests#testMethodOne
...
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0

2.4. Execute Tests with Name Matching Regex Pattern

To execute all test methods in the application that matches a given pattern, use the regular expression wild-card to for creating a name matching pattern. For example, the following example executes all the tests with name testMethodOne() in all the test classes in the application.

$ mvn -Dtest="*#testMethodOne" test

INFO: Executing ModuleOneTests#testMethodOne
INFO: Executing ModuleTwoTests#testMethodOne
...
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

Note that we can create any pattern for matching test names and classes. The following command executes all the tests with names starting with test in test class ModuleOneTests.

$ mvn -Dtest="ModuleOneTests#test*" test

INFO: Executing ModuleOneTests#testMethodOne
INFO: Executing ModuleOneTests#testMethodTwo
...
[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

3. Rerun Failing Tests

Another possible usecase can be to rerun any failing tests during the test execution. We can pass '-Dsurefire.rerunFailingTestsCount=n' parameter to rerun a failing test n times.

The following command will run all the tests in ModuleTwoTests class. And each failing test will be rerun two times. We have intentionally failed the testMethodFour() for this example.

mvn '-Dsurefire.rerunFailingTestsCount=2' -Dtest=ModuleTwoTests test

[ERROR] Tests run: 4, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0 s <<< FAILURE! - in com.howtodoinjava.ModuleTwoTests
...
[ERROR] Failures:
[ERROR] com.howtodoinjava.ModuleTwoTests.testMethodFour
[ERROR]   Run 1: ModuleTwoTests.testMethodFour:35
[ERROR]   Run 2: ModuleTwoTests.testMethodFour:35
[ERROR]   Run 3: ModuleTwoTests.testMethodFour:35
...
[ERROR] Tests run: 4, Failures: 1, Errors: 0, Skipped: 0

4. Conclusion

In this Maven tutorial, we learned to execute the JUnit tests using mvn test command in various ways. We learned to execute all tests, selected tests, and even a single test. We also learned to rerun the failing tests from the command line.

Happy Learning !!

Sourcecode on Github