TestNG Parallel Execution: Modes, Thread Safety, and WebDriver

TestNG Parallel Execution: Modes, Thread Safety, and WebDriver

Running tests sequentially is a bottleneck. A suite that takes 45 minutes in serial can often finish in 8–10 minutes with proper parallel execution. TestNG has built-in parallel execution support that's more flexible than most frameworks — and more dangerous if you get it wrong. This guide covers how to set it up correctly.

The Four Parallel Modes

TestNG supports four parallel modes, set in testng.xml:

<suite name="Test Suite" parallel="methods" thread-count="4">

methods

Each @Test method runs in its own thread. Maximum parallelism, maximum risk.

<suite name="Suite" parallel="methods" thread-count="10">
    <test name="All Tests">
        <classes>
            <class name="com.example.LoginTests"/>
            <class name="com.example.SearchTests"/>
        </classes>
    </test>
</suite>

All @Test methods across all classes run concurrently, up to 10 at a time. @BeforeMethod and @AfterMethod still run per-method but in the same thread as the test.

classes

Each test class gets its own thread. Methods within a class run sequentially.

<suite name="Suite" parallel="classes" thread-count="5">

This is usually the safest starting point. If your test classes are independent (which they should be), class-level parallelism gives you most of the speedup without the complexity of method-level threading.

tests

Each <test> element in your XML runs in its own thread.

<suite name="Suite" parallel="tests" thread-count="4">
    <test name="Chrome Tests">
        <parameter name="browser" value="chrome"/>
        <classes>
            <class name="com.example.LoginTests"/>
        </classes>
    </test>
    <test name="Firefox Tests">
        <parameter name="browser" value="firefox"/>
        <classes>
            <class name="com.example.LoginTests"/>
        </classes>
    </test>
</suite>

This is the standard pattern for cross-browser parallel testing. Each browser gets its own <test> block with its own thread.

instances

Each object instance of a test class runs in its own thread. Used with @Factory.

<suite name="Suite" parallel="instances" thread-count="3">
public class ApiTest {
    private String environment;

    public ApiTest(String env) {
        this.environment = env;
    }

    @Factory
    public static Object[] create() {
        return new Object[] {
            new ApiTest("staging"),
            new ApiTest("production"),
            new ApiTest("canary")
        };
    }

    @Test
    public void healthCheck() {
        // Runs in parallel for each environment
    }
}

Thread-Safe Test Design

The most common mistake with parallel testing is shared mutable state. Instance variables are per-object, so they're fine in parallel=classes or parallel=instances. But static variables are shared across threads and will cause random failures.

What's Safe

public class SafeTest {
    // Instance variable — safe in parallel=classes mode
    private WebDriver driver;
    private String testData;

    @BeforeMethod
    public void setup() {
        driver = new ChromeDriver();  // Each instance gets its own driver
        testData = generateUniqueData();
    }

    @Test
    public void testOne() {
        // Uses this.driver — safe
    }
}

What's Not Safe

public class UnsafeTest {
    // Static variable — shared across all threads. DO NOT DO THIS.
    private static WebDriver driver;
    private static String lastCreatedUserId;

    @BeforeClass
    public static void setup() {
        driver = new ChromeDriver();  // One driver shared by all parallel threads
    }

    @Test
    public void createUser() {
        // Thread A creates user, stores ID
        lastCreatedUserId = api.createUser("user1");
    }

    @Test
    public void deleteUser() {
        // Thread B might run simultaneously, sees Thread A's ID or null
        api.deleteUser(lastCreatedUserId);
    }
}

ThreadLocal for Shared Resources

When you need a per-thread instance of something (WebDriver being the classic case), use ThreadLocal:

public class DriverManager {
    private static final ThreadLocal<WebDriver> driver = new ThreadLocal<>();

    public static void setDriver(WebDriver webDriver) {
        driver.set(webDriver);
    }

    public static WebDriver getDriver() {
        return driver.get();
    }

    public static void removeDriver() {
        driver.get().quit();
        driver.remove();
    }
}

Base test class using it:

public abstract class BaseTest {

    @BeforeMethod
    public void setUp() {
        WebDriver webDriver = new ChromeDriver();
        DriverManager.setDriver(webDriver);
    }

    @AfterMethod
    public void tearDown() {
        DriverManager.removeDriver();
    }

    protected WebDriver getDriver() {
        return DriverManager.getDriver();
    }
}

Test class:

public class LoginTest extends BaseTest {

    @Test
    public void loginWithValidCredentials() {
        WebDriver driver = getDriver();  // Gets THIS thread's driver
        driver.get("https://example.com/login");
        // ...
    }
}

Each thread gets its own WebDriver instance. No shared state. Tests can run fully in parallel.

Parallel WebDriver with Cross-Browser XML

The standard cross-browser setup in TestNG:

<suite name="Cross Browser Suite" parallel="tests" thread-count="4">

    <test name="Chrome">
        <parameter name="browser" value="chrome"/>
        <classes>
            <class name="com.example.tests.LoginTest"/>
            <class name="com.example.tests.CheckoutTest"/>
        </classes>
    </test>

    <test name="Firefox">
        <parameter name="browser" value="firefox"/>
        <classes>
            <class name="com.example.tests.LoginTest"/>
            <class name="com.example.tests.CheckoutTest"/>
        </classes>
    </test>

    <test name="Safari">
        <parameter name="browser" value="safari"/>
        <classes>
            <class name="com.example.tests.LoginTest"/>
            <class name="com.example.tests.CheckoutTest"/>
        </classes>
    </test>

</suite>

Base test class receiving the parameter:

public abstract class BaseTest {

    @Parameters({"browser"})
    @BeforeMethod
    public void setUp(String browser) {
        WebDriver webDriver = createDriver(browser);
        DriverManager.setDriver(webDriver);
    }

    private WebDriver createDriver(String browser) {
        return switch (browser.toLowerCase()) {
            case "chrome" -> new ChromeDriver();
            case "firefox" -> new FirefoxDriver();
            case "safari" -> new SafariDriver();
            default -> throw new IllegalArgumentException("Unknown browser: " + browser);
        };
    }

    @AfterMethod
    public void tearDown() {
        DriverManager.removeDriver();
    }
}

thread-count vs data-provider-thread-count

Two separate thread count settings:

<suite name="Suite"
       parallel="methods"
       thread-count="8"
       data-provider-thread-count="4">
  • thread-count — max threads for parallel test execution
  • data-provider-thread-count — max threads when a @DataProvider has parallel=true
@DataProvider(name = "urls", parallel = true)
public Object[][] urlsToTest() {
    return new Object[][] {
        {"https://example.com"},
        {"https://example.com/about"},
        {"https://example.com/contact"},
        {"https://example.com/blog"}
    };
}

@Test(dataProvider = "urls")
public void pageLoadsCorrectly(String url) {
    // Each URL tested in parallel (up to data-provider-thread-count)
}

Controlling Which Tests Run in Parallel

You don't have to parallelize everything. Mix parallel and sequential by using multiple <test> blocks:

<suite name="Suite" parallel="tests" thread-count="4">

    <!-- These run in parallel -->
    <test name="Independent Tests">
        <classes>
            <class name="com.example.SearchTests"/>
            <class name="com.example.ProductTests"/>
        </classes>
    </test>

    <test name="More Independent Tests">
        <classes>
            <class name="com.example.AccountTests"/>
        </classes>
    </test>

    <!-- This test is excluded from parallel by not sharing the thread pool -->
    <!-- Sequential tests can be in a separate suite file -->

</suite>

For tests that must run sequentially even within a parallel suite, use singleThreaded on the class:

@Test(singleThreaded = true)
public class DatabaseMigrationTest {
    // Even in parallel=methods mode, these run sequentially
    @Test
    public void step1() { }

    @Test(dependsOnMethods = "step1")
    public void step2() { }
}

Common Pitfalls

Pitfall 1: Shared Test Data Files

Reading from the same test data file in parallel is usually fine (reads are thread-safe on most filesystems). Writing to the same file is not.

// BAD — concurrent writes to same file
@Test
public void recordResult() {
    Files.write(Path.of("results.txt"), result.getBytes(), StandardOpenOption.APPEND);
}

// GOOD — thread-safe alternative
@Test
public void recordResult() {
    String filename = "results-" + Thread.currentThread().getId() + ".txt";
    Files.write(Path.of(filename), result.getBytes());
}

Pitfall 2: Database State

Parallel tests hitting the same database will step on each other if they share data:

// BAD — tests share the same user
@BeforeClass
public static void createTestUser() {
    testUserId = db.createUser("testuser@example.com");
}

// GOOD — each test creates unique data
@BeforeMethod
public void createTestUser() {
    String uniqueEmail = "test-" + System.nanoTime() + "@example.com";
    testUserId = db.createUser(uniqueEmail);
}

Pitfall 3: Port Conflicts

Starting local servers in parallel tests will cause port conflicts:

// BAD
@BeforeClass
public void startServer() {
    server = new TestServer(8080);  // All parallel classes try port 8080
    server.start();
}

// GOOD — dynamic port allocation
@BeforeClass
public void startServer() {
    int port = findAvailablePort();
    server = new TestServer(port);
    server.start();
    baseUrl = "http://localhost:" + port;
}

private int findAvailablePort() {
    try (ServerSocket socket = new ServerSocket(0)) {
        return socket.getLocalPort();
    } catch (IOException e) {
        throw new RuntimeException(e);
    }
}

Pitfall 4: Selenium WebDriver Timeouts

With parallel WebDriver, each driver needs its own timeouts. Don't set timeouts as static values:

// BAD
private static final int TIMEOUT = 10;

// GOOD — configure per driver instance
@BeforeMethod
public void setUp() {
    WebDriver driver = new ChromeDriver();
    driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));
    driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(30));
    DriverManager.setDriver(driver);
}

Checking Thread Count During Tests

Useful for debugging parallel issues:

@Test
public void debugThread() {
    System.out.println("Thread: " + Thread.currentThread().getName() +
                       " ID: " + Thread.currentThread().getId());
}

In listeners, you can log thread info on failures:

@Override
public void onTestFailure(ITestResult result) {
    System.out.println("FAILED: " + result.getName() +
                       " on thread: " + Thread.currentThread().getName());
}

For a UI test suite hitting a real application:

<suite name="Test Suite"
       parallel="classes"
       thread-count="4"
       verbose="1">

    <listeners>
        <listener class-name="com.example.listeners.TestLogger"/>
    </listeners>

    <test name="Regression">
        <classes>
            <class name="com.example.LoginTests"/>
            <class name="com.example.SearchTests"/>
            <class name="com.example.CheckoutTests"/>
            <class name="com.example.AccountTests"/>
        </classes>
    </test>

</suite>

Start with parallel="classes" and 4 threads. Measure the speedup. If your tests are clean (no shared state), bump to 6–8 threads. Move to parallel="methods" only after you've proven your tests are thread-safe.

Maven Surefire Integration

Running parallel TestNG from Maven:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <suiteXmlFiles>
            <suiteXmlFile>src/test/resources/testng.xml</suiteXmlFile>
        </suiteXmlFiles>
        <!-- Or configure parallel directly: -->
        <parallel>classes</parallel>
        <threadCount>4</threadCount>
        <forkCount>1</forkCount>
    </configuration>
</plugin>

Using forkCount>1 with parallel gives you JVM-level isolation (separate JVM processes) on top of thread-level parallelism. Use this when tests leak JVM-level state (like system properties or static initializers) that ThreadLocal can't fix.

Read more

Start now free