Running JUnit Tests with Maven

The Maven Surefire Plugin is the plugin that runs the unit tests of a Maven project, and it supports JUnit 4 and JUnit 5 tests. We use it to run all tests, selected tests or a single test from the command line, and to rerun failing tests. The following commands run all tests, one test class, several test classes, one test method and the tests that match a name pattern.

//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

See Also: Running Tests with Gradle

1. Setup

Import 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>

By default, the Surefire plugin supports tests written in JUnit 4 and JUnit 5. It detects the JUnit version and uses the matching runner to execute 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>

The commands in the next sections run the tests of these two classes.

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

Maven runs all tests, the tests of one class, a single method or the tests that match a name pattern, depending on the options we pass to the Surefire plugin.

2.1. Execute All Test Classes and Methods

To execute all tests, we 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

To execute all tests in a test class, we pass -Dtest=TestClass.

$ mvn -Dtest=ModuleOneTests test

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

To execute all tests in several test classes, we pass the class names in double quotes, as in -Dtest=”TestClassOne,TestClassTwo”.

$ 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

To execute one test method, we pass -Dtest=TestClass#testMethod.

$ 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 that match a name pattern, we use a wildcard in the pattern. For example, the following command executes all the tests named testMethodOne() in all the test classes of the application.

$ mvn -Dtest="*#testMethodOne" test

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

We can write any pattern for test class and method names. The following command executes all the tests with names starting with test in the 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

The Surefire plugin can rerun failing tests during the test execution. The parameter -Dsurefire.rerunFailingTestsCount=n reruns a failing test n times.

The following command runs all the tests in the class ModuleTwoTests and reruns each failing test two times. The method testMethodFour() fails on purpose in 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

The mvn test command runs JUnit tests through the Surefire plugin. With the parameter -Dtest, we run all tests, the tests of selected classes, a single method or the methods that match a pattern. The parameter -Dsurefire.rerunFailingTestsCount reruns failing tests.

Happy Learning !!

Source Code on Github