Running a Single Test or Method With Maven

1. Overview

Usually, we execute tests during a Maven build using the Maven surefire plugin.

This tutorial will explore how to use this plugin to run a single test class or test method.

2. Introduction to the Problem

The Maven surefire plugin is easy to use. It has only one goal: test.

Therefore, with the default configuration, we can execute all tests in the project by the command mvn test.

Sometimes, we may want to execute one single test class or even one single test method.

In this tutorial, we’ll take JUnit 5 as the testing provider example to address how to achieve it.

3. The Example Project

To show the test results in a more straightforward way, let’s create a couple of simple test classes:

class TheFirstUnitTest {

    // declaring logger ... 

    @Test
    void whenTestCase_thenPass() {
        logger.info("Running a dummyTest");
    }
}

class TheSecondUnitTest {

    // declaring logger ... 

    @Test
    void whenTestCase1_thenPrintTest1_1() {
        logger.info("Running When Case1: test1_1");
    }

    @Test
    void whenTestCase1_thenPrintTest1_2() {
        logger.info("Running When Case1: test1_2");
    }

    @Test
    void whenTestCase1_thenPrintTest1_3() {
        logger.info("Running When Case1: test1_3");
    }

    @Test
    void whenTestCase2_thenPrintTest2_1() {
        logger.info("Running When Case2: test2_1");
    }
}

In the TheFirstUnitTest class, we have only one test method. However, TheSecondUnitTest contains four test methods. All our method names are following the “when…then…” pattern.

To make it simple, we’ve made each test method output a line indicating the method is being called.

Now if we run mvn test, all tests will be executed:

$ mvn test
...
[INFO] Scanning for projects...
...
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.baeldung.runasingletest.TheSecondUnitTest
16:58:16.444 [main] INFO ...TheSecondUnitTest - Running When Case2: test2_1
16:58:16.448 [main] INFO ...TheSecondUnitTest - Running When Case1: test1_1
16:58:16.449 [main] INFO ...TheSecondUnitTest - Running When Case1: test1_2
16:58:16.450 [main] INFO ...TheSecondUnitTest - Running When Case1: test1_3
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.065 s - in com.baeldung.runasingletest.TheSecondUnitTest
[INFO] Running com.baeldung.runasingletest.TheFirstUnitTest
16:58:16.453 [main] INFO ...TheFirstUnitTest - Running a dummyTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0 s - in com.baeldung.runasingletest.TheFirstUnitTest
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
 ...

Next, let’s tell Maven to execute only specified tests.

4. Execute a Single Test Class

The Maven surefire plugin provides a test parameter that we can use to specify test classes or methods we want to execute.

If we want to execute a single test class, we can execute the command mvn test -Dtest=”TestClassName”.

For instance, we can pass -Dtest=”TheFirstUnitTest” to the mvn command to execute the TheFirstUnitTest class only:

$ mvn test -Dtest="TheFirstUnitTest"
...
[INFO] Scanning for projects...
...
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.baeldung.runasingletest.TheFirstUnitTest
17:10:35.351 [main] INFO com.baeldung.runasingletest.TheFirstUnitTest - Running a dummyTest
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.053 s - in com.baeldung.runasingletest.TheFirstUnitTest
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
 ...

As the output shows, only the test class we’ve passed to the test parameter is executed.

5. Execute a Single Test Method

Additionally, we can ask the Maven surefire plugin to execute a single test method by passing -Dtest=”TestClassName#TestMethodName” to the mvn command.

Now let’s execute the whenTestCase2_thenPrintTest2_1() method in the TheSecondUnitTest class:

$ mvn test -Dtest="TheSecondUnitTest#whenTestCase2_thenPrintTest2_1"    
...
[INFO] Scanning for projects...
...
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.baeldung.runasingletest.TheSecondUnitTest
17:22:07.063 [main] INFO ...TheSecondUnitTest - Running When Case2: test2_1
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.057 s - in com.baeldung.runasingletest.TheSecondUnitTest
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
...

As we can see, this time, we’ve executed only the specified test method.

6. More About the test Parameter

So far, we’ve shown how to execute a single test class or test method by providing the test parameter value accordingly.

Actually, the Maven surefire plugin allows us to set the value of the test parameter in different formats to execute tests flexibly.

Next, we’ll show some commonly used formats:

• Execute multiple test classes by name: -Dtest=”TestClassName1, TestClassName2, TestClassName3…”
• Execute multiple test classes by name pattern: -Dtest=”*ServiceUnitTest” or -Dtest=”The*UnitTest, Controller*Test”
• Specify multiple test methods by name: -Dtest=”ClassName#method1+method2″
• Specify multiple method names by name pattern: -Dtest=”ClassName#whenSomethingHappens_*”

Finally, let’s see one more example.

Let’s say we only want to execute all “whenTestCase1…” methods in the TheSecondUnitTest class.

So, following the pattern we’ve talked about above, we hope that -Dtest=”TheSecondUnitTest#whenTestCase1*” will do the job:

$ mvn test -Dtest="TheSecondUnitTest#whenTestCase1*"
...
[INFO] Scanning for projects...
...
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.baeldung.runasingletest.TheSecondUnitTest
17:51:04.973 [main] INFO ...TheSecondUnitTest - Running When Case1: test1_1
17:51:04.979 [main] INFO ...TheSecondUnitTest - Running When Case1: test1_2
17:51:04.980 [main] INFO ...TheSecondUnitTest - Running When Case1: test1_3
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.055 s - in com.baeldung.runasingletest.TheSecondUnitTest
[INFO] 
[INFO] Results:
[INFO] 
[INFO] Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
...

As we expected, only the three test methods matching the specified name pattern have been executed.

7. Conclusion

The Maven surefire plugin provides a test parameter that allows us a lot of flexibility in choosing which tests we want to execute.

In this article, we’ve discussed some commonly used value formats of the test parameter.

Also, we’ve addressed through examples how to run only specified test classes or test methods with Maven.