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 executiondata-provider-thread-count— max threads when a@DataProviderhasparallel=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());
}Recommended Starting Configuration
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.