How to Execute Tests Selectively in TestNG

1. Overview

In large TestNG-based suites, we often encounter scenarios where most tests pass, but a small subset fails. Re-running the entire suite in such cases is a waste of time and resources. TestNG provides several mechanisms to execute only failed tests. 

In this tutorial, we’ll explore various approaches to re-run only failed TestNG test methods, along with their examples and use cases.

2. Running the testng-failed.xml

TestNG automatically generates the testng-failed.xml file as a recovery suite after each test execution. We get this file only when our execution completes normally, at least one test fails or is skipped, and default reporters are enabled. This file captures only failed and skipped test methods while preserving our original suite structure. This allows us to re-run failures without modifying the original testng.xml.

Let’s look at the code below, which contains two test cases – one always fails:

public class ExecuteSelectivelyUnitTest {
    @Test
    public void givenTest_whenFails_thenExecuteSelectively() {
        Assert.assertEquals(5, 6);
    }

    @Test
    public void givenTest_whenPass_thenExecuteSelectively() {
        Assert.assertEquals(5, 5);
    }
}

Now, we’ll run tests using the command:

mvn test -Dtest=ExecuteSelectivelyUnitTest

We’re running our tests through Maven Surefire, and we can locate the file at target/surefire-reports/testng-failed.xml. Let’s take a look at the content of this file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="Failed suite [Surefire suite]" verbose="0">
  <test thread-count="5" name="Surefire test(failed)" verbose="0">
    <classes>
      <class name="com.baeldung.testng.ExecuteSelectivelyUnitTest">
        <methods>
          <include name="givenTest_whenFails_thenExecuteSelectively"/>
        </methods>
      </class> <!-- com.baeldung.testng.ExecuteSelectivelyUnitTest -->
    </classes>
  </test> <!-- Surefire test(failed) -->
</suite> <!-- Failed suite [Surefire suite] -->

The file explicitly includes only the failed method givenTest_whenFails_thenExecuteSelectively from ExecuteSelectivelyUnitTest, excluding all passed tests. Now, we can directly run the failed test case by running the following command:

mvn test -Dsurefire.suiteXmlFiles=target/surefire-reports/testng-failed.xml

Once we trigger the above command, we can see Maven re-run only the tests listed in testng-failed.xml that were previously failed.

3. Using <include> in testng.xml

Another way to run selective tests is to create a testng.xml file manually that includes only the tests that we want to run. TestNG doesn’t require any special metadata; the file structure is similar to what we’ve seen earlier. We can add test names with selective <include> entries in the <methods> section:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="Failed suite [Failed suite [Surefire suite]]" guice-stage="DEVELOPMENT" verbose="0">
  <test thread-count="5" name="Surefire test(failed)(failed)" verbose="0">
    <classes>
      <class name="com.baeldung.testng.ExecuteSelectivelyUnitTest">
        <methods>
          <include name="givenTest_whenFails_thenExecuteSelectively"/>
          <include name="method-name-here"/>
        </methods>
      </class> 
    </classes>
  </test> 
</suite>

Now, we can directly run the tests specified in testng.xml by running the following command:

mvn test -Dsurefire.suiteXmlFiles=testng.xml

This approach works well for small or ad hoc runs, giving us fine-grained control over which tests to execute. However, it requires manual editing and can become harder to maintain as the test suite grows.

4. Using Maven Surefire Single Method Execution

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 givenTest_whenFails_thenExecuteSelectively() method in the ExecuteSelectivelyUnitTest class:

$ mvn test -Dtest=ExecuteSelectivelyUnitTest#givenTest_whenFails_thenExecuteSelectively    
...
[INFO] Scanning for projects...
...
[INFO] -------------------------------------------------------
[INFO]  T E S T S
[INFO] -------------------------------------------------------
[INFO] Running com.baeldung.testng.ExecuteSelectivelyUnitTest
[ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 0.379 s <<< FAILURE! -- in com.baeldung.testng.ExecuteSelectivelyUnitTest
[ERROR] com.baeldung.testng.ExecuteSelectivelyUnitTest.givenTest_whenFails_thenExecuteSelectively -- Time elapsed: 0.006 s <<< FAILURE!
java.lang.AssertionError: expected [6] but found [5]
...
[INFO] Results:
[INFO] 
[ERROR] Failures: 
[ERROR]   ExecuteSelectivelyUnitTest.givenTest_whenFails_thenExecuteSelectively:9 expected [6] but found [5]
[INFO] 
[ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------

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

5. Selective Execution via @BeforeMethod

TestNG always executes configuration methods such as @BeforeMethod and @BeforeClass before running a test. When we throw SkipException from these methods, TestNG treats it as a deliberate skip. We can evaluate conditions at this point and throw a SkipException to selectively skip tests without altering the suite definition.

Let’s take a look at the code below:

private static final Set<String> SKIP_METHODS = Set.of("givenTest_whenFails_thenExecuteSelectively");

@BeforeMethod
public void skipSelectedMethods(Method method) {
    if (SKIP_METHODS.contains(method.getName())) {
        throw new SkipException("Skipping test method: " + method.getName());
    }
}

Here, we maintained a Set of test method names to skip. Before each test run, we compare the current method name against this set and throw a SkipException when a match is found. This allows us to skip specific tests dynamically without modifying the test suite or annotations. 

6. Using IMethodInterceptor

IMethodInterceptor is a TestNG interface that allows us to control which test methods are executed before the test run begins. This mechanism allows us to decide which test methods should be included, skipped, or reordered at the discovery stage itself.

We implement the IMethodInterceptor interface and override the intercept() method. TestNG calls this method once and passes a list of all discovered test methods. Inside the method, we have a collection of test methods we want to skip. This ensures that TestNG never schedules or executes the skipped methods:

public class SkipMethodInterceptor implements IMethodInterceptor {

    private static final Set<String> SKIP_METHODS = Set.of("givenTest_whenFails_thenExecuteSelectively");

    @Override
    public List<IMethodInstance> intercept(List<IMethodInstance> methods, ITestContext context) {
        return methods.stream()
                .filter(m -> !SKIP_METHODS.contains(m.getMethod().getMethodName()))
                .collect(Collectors.toList());
    }
}

To skip the givenTest_whenFails_thenExecuteSelectively test, we need to attach this interceptor to our tests by registering it with TestNG. We can annotate the test class using @Listeners and reference the interceptor class directly, like this:

@Listeners(SkipMethodInterceptor.class)
public class ExecuteSelectivelyUnitTest {
    // tests here
}

 This approach allows us to avoid executing unnecessary setup logic and keep test selection logic centralized and flexible.

7. IDE-Driven Selective Execution

Modern Java test frameworks and IDEs seamlessly work together. We can run specific tests at the method or class level directly from the IDE. We don’t need to modify the suite files or add any configuration. 

In IntelliJ IDEA, we can run a specific TestNG test directly from the editor, instead of modifying the testng.xml. We need to open the test class, place the cursor on the method annotated with @Test, and click the green icon in the gutter or right-click and select Run, as shown in the image:

This approach requires no setup, no group annotations, or no suite changes. It allows us to iterate quickly, debug failures immediately, and validate fixes without affecting other tests in the suite.

8. Conclusion

In this article, we discussed various approaches to executing tests selectively in TestNG. 

We saw how TestNG supports selective execution using testng-failed.xml and <include> in testng.xml. These are effective for re-running failures and controlling execution in CI pipelines. Maven Surefire’s single-test execution further enhances this by using command-line-driven reruns without modifying the suite files.

IntelliJ’s IDE-driven execution is the most commonly used approach due to zero setup, fast, and built-in debugging. When more flexibility is required, IMethodInterceptor and @BeforeMethod enable pre-execution filtering and a simple way to isolate tests during debugging.

As always, the code is available over on GitHub.