TestNG Parallel Test Execution: Threading, Config, and Best Practices
A slow test suite is a broken feedback loop. When developers wait 20 minutes for tests to finish, they stop running them before every commit. Parallel test execution in TestNG is the most direct way to cut that time — but done incorrectly, it introduces flaky tests that are harder to debug than a slow suite.
This guide covers TestNG's parallel execution model in full: configuration options, thread safety, best practices, and the patterns that actually work at scale.
Why Parallelism Matters
Consider a test suite with 200 tests averaging 2 seconds each. Sequential execution: 400 seconds. With 4 parallel threads: roughly 100 seconds. With 8 threads: around 50 seconds. That difference — from 6+ minutes to under a minute — is the difference between tests that run in CI and tests that block deploys.
Parallelism also lets you exploit multi-core machines. Most CI environments have 4–16 cores; a sequential test suite uses one.
Parallel Modes in TestNG
TestNG supports four parallel modes, configured in testng.xml:
parallel="methods"
Each test method runs in its own thread. Highest throughput, most complex to get right.
<suite name="My Suite" parallel="methods" thread-count="8">
<test name="All Tests">
<classes>
<class name="com.example.UserTest"/>
<class name="com.example.OrderTest"/>
<class name="com.example.ProductTest"/>
</classes>
</test>
</suite>Methods from the same class can run concurrently. This requires that test methods are completely independent — no shared mutable state on the class instance.
parallel="classes"
All methods within a class run sequentially, but different classes run in parallel threads.
<suite name="My Suite" parallel="classes" thread-count="4">
<test name="All Tests">
<classes>
<class name="com.example.UserTest"/>
<class name="com.example.OrderTest"/>
<class name="com.example.ProductTest"/>
</classes>
</test>
</suite>Each class gets its own thread. Methods within a class are safe to share instance state. This is the safest parallel mode for most test suites.
parallel="tests"
Each <test> element in the XML runs in its own thread. Classes and methods within a <test> block run sequentially.
<suite name="My Suite" parallel="tests" thread-count="3">
<test name="User Tests">
<classes>
<class name="com.example.UserTest"/>
</classes>
</test>
<test name="Order Tests">
<classes>
<class name="com.example.OrderTest"/>
</classes>
</test>
<test name="Product Tests">
<classes>
<class name="com.example.ProductTest"/>
</classes>
</test>
</suite>Each <test> block runs independently. This is the easiest mode to reason about because entire logical test groups run in isolation.
parallel="instances"
For data-driven tests using @Factory, each object instance runs in its own thread. Advanced use case — relevant when using the factory pattern for parameterized test classes.
Thread Count
<suite name="My Suite" parallel="classes" thread-count="8">Start with the number of CPU cores available in your CI environment. Then adjust based on:
- CPU-bound tests: Thread count = number of cores
- I/O-bound tests (database, HTTP): Thread count = 2–4× cores, since threads spend time waiting
- Browser tests: Thread count = number of browser instances you can support
Don't guess — measure. Run the suite at thread-count=2, 4, 8, 16 and chart total runtime. You'll see diminishing returns (and eventually regression) as contention increases.
Thread Safety: The Hard Part
Parallel tests break when tests share mutable state. Common failure patterns:
Anti-pattern: Shared instance variables
// BROKEN — multiple threads write to this field concurrently
public class UserTest {
private User currentUser; // shared mutable state
@BeforeMethod
public void setup() {
currentUser = userService.createUser("test@example.com");
}
@Test
public void testUpdateName() {
currentUser.setName("Alice"); // thread A sets name
// thread B may overwrite currentUser before this assertion
assertEquals(currentUser.getName(), "Alice");
}
}With parallel="methods", multiple threads share the same UserTest instance. Both threads call setup(), overwriting currentUser. Tests fail unpredictably.
Fix 1: ThreadLocal
public class UserTest {
private ThreadLocal<User> currentUser = new ThreadLocal<>();
@BeforeMethod
public void setup() {
currentUser.set(userService.createUser("test@example.com"));
}
@AfterMethod
public void teardown() {
userService.deleteUser(currentUser.get().getId());
currentUser.remove();
}
@Test
public void testUpdateName() {
User user = currentUser.get();
user.setName("Alice");
assertEquals(user.getName(), "Alice");
}
}Each thread gets its own User instance. No contention.
Fix 2: Use parallel="classes" instead of parallel="methods"
If your test class has setup that naturally applies to the whole class, use class-level parallelism. Methods within the class run sequentially, so instance variables are safe.
<suite parallel="classes" thread-count="4">This is often the right trade-off: you get parallelism across classes without needing to audit every method for thread safety.
Fix 3: Local variables in test methods
The safest approach for method-level parallelism: don't use instance variables at all.
public class ProductTest {
// No instance variables
@Test
public void testCreateProduct() {
// Everything is local to this method
ProductService service = new ProductService(getConnection());
Product product = service.create(new ProductRequest("Widget", 9.99));
assertNotNull(product.getId());
service.delete(product.getId()); // cleanup
}
@Test
public void testUpdateProduct() {
ProductService service = new ProductService(getConnection());
Product product = service.create(new ProductRequest("Gadget", 19.99));
service.updatePrice(product.getId(), 14.99);
Product updated = service.find(product.getId());
assertEquals(updated.getPrice(), 14.99, 0.001);
service.delete(product.getId()); // cleanup
}
}Each method creates its own service, its own data, and cleans up after itself. No shared state possible.
Database Isolation in Parallel Tests
Tests that hit a shared database are a common source of parallel test failures. Three strategies:
Strategy 1: Unique test data per method
Each test generates uniquely-named data:
@Test
public void testFindUserByEmail() {
String uniqueEmail = "user-" + Thread.currentThread().getId()
+ "-" + System.nanoTime() + "@example.com";
userService.create(uniqueEmail, "Test User");
User found = userService.findByEmail(uniqueEmail);
assertEquals(found.getEmail(), uniqueEmail);
userService.delete(found.getId()); // cleanup
}Thread IDs and timestamps guarantee uniqueness.
Strategy 2: Per-thread database connections with transactions
Each thread uses its own connection and rolls back after each test:
public class DbTest {
private static ThreadLocal<Connection> threadConnection = new ThreadLocal<>();
@BeforeMethod
public void beginTransaction() throws SQLException {
Connection conn = dataSource.getConnection();
conn.setAutoCommit(false);
threadConnection.set(conn);
}
@AfterMethod
public void rollback() throws SQLException {
Connection conn = threadConnection.get();
conn.rollback();
conn.close();
threadConnection.remove();
}
protected Connection getConnection() {
return threadConnection.get();
}
}Tests write freely; everything rolls back. No cleanup code needed in individual tests.
Strategy 3: Separate schemas per thread
For integration tests that can't use transactions (e.g., tests that span multiple commits), use a separate schema per test thread:
@BeforeSuite
public void setupSchemas() {
for (int i = 0; i < threadCount; i++) {
dbAdmin.createSchema("test_thread_" + i);
}
}Map each thread to its schema using ThreadLocal<Integer> for the schema index. More infrastructure but complete isolation.
Parallel Data Providers
TestNG's @DataProvider supports parallel execution independently of suite-level parallelism:
@DataProvider(name = "apiEndpoints", parallel = true)
public Object[][] apiEndpoints() {
return new Object[][] {
{"/api/users", 200},
{"/api/products", 200},
{"/api/orders", 200},
{"/api/analytics", 200},
{"/api/reports", 200},
};
}
@Test(dataProvider = "apiEndpoints")
public void testEndpoint(String path, int expectedStatus) {
// Each row runs in its own thread
Response response = httpClient.get(baseUrl + path);
Assert.assertEquals(response.getStatus(), expectedStatus);
}Data provider thread count is configured separately:
<suite name="Suite" data-provider-thread-count="5">This is useful when the test itself is parallelizable (like hitting independent endpoints) but you're not running the full suite in parallel mode.
Configuring Parallel Tests with Maven Surefire
If you're using Maven rather than testng.xml, configure parallel in the Surefire plugin:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.1.2</version>
<configuration>
<parallel>classes</parallel>
<threadCount>4</threadCount>
<suiteXmlFiles>
<suiteXmlFile>testng.xml</suiteXmlFile>
</suiteXmlFiles>
</configuration>
</plugin>Note: if both testng.xml and Surefire specify parallelism, Surefire settings override the XML.
Logging in Parallel Tests
Standard logging configurations write to a shared log file. In parallel tests, log entries from different threads are interleaved, making debugging very hard.
Use MDC (Mapped Diagnostic Context) if you're using SLF4J/Logback:
@BeforeMethod
public void setLogContext() {
MDC.put("threadId", String.valueOf(Thread.currentThread().getId()));
MDC.put("testName", ((ITestResult) this).getName()); // if you have access
}
@AfterMethod
public void clearLogContext() {
MDC.clear();
}Configure Logback to include %X{threadId} in the pattern:
<pattern>%d{HH:mm:ss} [%thread] [tid:%X{threadId}] %-5level %logger - %msg%n</pattern>Now you can filter logs by thread ID when debugging a specific failing test.
Detecting Thread-Safety Issues
If tests pass sequentially but fail in parallel, the cause is almost always shared mutable state. Checklist:
- Instance variables in test classes — use
ThreadLocalor make methods self-contained - Static variables — never use static mutable state in tests
- Shared test data in the database — use unique data or transactions
- Shared HTTP client instances — check if your client is thread-safe (most modern ones are)
- File system access — use unique temp file names per thread
- External service state — if tests depend on service state, they must clean up after themselves
Parallel E2E Tests and TestNG
For Selenium/WebDriver tests, parallel execution means multiple browsers. The pattern:
public class BrowserTest {
private ThreadLocal<WebDriver> driver = new ThreadLocal<>();
@BeforeMethod
public void launchBrowser() {
driver.set(new ChromeDriver(getChromeOptions()));
}
@AfterMethod
public void closeBrowser() {
driver.get().quit();
driver.remove();
}
protected WebDriver getDriver() {
return driver.get();
}
}Each thread gets its own browser instance. For CI, use Selenium Grid or a cloud provider (BrowserStack, Sauce Labs) to run multiple browsers concurrently.
For teams that want parallel E2E coverage without the infrastructure overhead, HelpMeTest runs tests in parallel automatically, across multiple browsers and devices, with usage-based pricing ($0.003/test run, no base fee). The tests are written in plain English — no Selenium setup, no thread management, no driver lifecycle code. It's a fundamentally different model than TestNG-based WebDriver tests, and for many teams it removes a significant infrastructure burden while still providing continuous UI coverage.
Summary
TestNG's parallel execution is mature and configurable. The key decisions:
- Choose the right parallel mode:
classesis the safest starting point;methodsis highest throughput but requires thread-safe tests - Set thread count based on measurement, not intuition
- Eliminate shared mutable state: use
ThreadLocal, local variables, and transaction-based cleanup - Database isolation: unique data, transactions, or separate schemas
- Log with context: MDC thread IDs make parallel test failures debuggable
Done well, parallel execution cuts suite runtime by 4–8× without introducing flakiness. Done poorly, it creates intermittent failures that erode trust in the test suite. The investment in thread-safe test design pays dividends for the entire lifetime of the test suite.