Comprehensive Guide to Running Single Test Methods with Maven

Maven Test Execution Fundamentals

In software development, frequently running specific test methods is a common requirement. Maven, through the Surefire plugin, provides flexible test execution mechanisms that allow developers to precisely control the scope of tests to be run.

Running Single Test Classes

To execute all methods within an entire test class, use the following command:

mvn test -Dtest=TestCircle

Where TestCircle is the name of the test class. If multiple Surefire plugin executors are configured in the project, you can explicitly specify to execute only the default test phase:

mvn surefire:test -Dtest=TestCircle

Executing Individual Test Methods

For executing single test methods, a specific syntax format is required:

mvn test -Dtest=TestCircle#xyz

Here, TestCircle represents the test class name, and xyz is the specific method name to be executed. This syntax format is supported in JUnit 4.x and TestNG frameworks.

Wildcard Usage

Maven supports using wildcards in both class names and method names to match multiple tests:

mvn test -Dtest=TestCircle#test*

This command will run all methods in the TestCircle class that start with test. Similarly, wildcards can be used in class names:

mvn test -Dtest=TestCi*le

Multiple Method Selection

For JUnit 4, JUnit 4.7+, and TestNG, you can select multiple specific methods to run:

mvn test -Dtest=TestCircle#testOne+testTwo

Using the plus sign + to connect multiple method names allows simultaneous execution of these specified test methods.

Multi-module Project Configuration

In multi-module Maven projects, you need to specify the particular module containing the target test:

mvn -pl <module-name> test -Dtest=TestCircle#xyz

Where <module-name> is the name of the target module, and the -pl parameter is used to specify the project list.

Special Handling for Integration Tests

For integration tests, different parameters are required:

mvn -pl <module-name> -Dit.test=TestCircle#xyz integration-test

Here, it.test is used instead of the test parameter, and the integration-test phase is executed instead of the test phase.

Advanced Pattern Matching

Maven supports complex test selection patterns, including excluding specific tests:

mvn "-Dtest=???Test, !Unstable*, pkg/**/Ci*leTest.java, *Test#test*One+testTwo?????, #fast*+slowTest" test

The exclamation mark ! is used to exclude matching tests, the question mark ? matches single characters, and the asterisk * matches zero or more characters.

Regular Expression Support

For more complex matching requirements, regular expressions can be used:

mvn "-Dtest=Basic*, !%regex[.*.Unstable.*], !%regex[.*.MyTest.class#one.*|two.*], %regex[#fast.*|slow.*]" test

Regular expressions provide more precise test selection capabilities, particularly useful for complex test organizational structures in large projects.

Parameterized Test Handling

For JUnit tests running with parameterization, method names include index information:

mvn test -Dtest=TestCircle#testMethod[5]

This syntax is applicable for executing test methods with specific parameter indices selected.

Fully Qualified Class Name Usage

Fully qualified class names can be used to precisely specify test locations:

mvn test -Dtest=com.example.TestCircle#methodName

This is particularly useful in large projects containing multiple test classes with the same name.