
Most Selenium tests don’t fail because of bad locators; they fail because of test overlap.
Testers might start a checkout test before the signup is completed or test a button after it changes. Not paying attention in test automation always leads to more reruns, red CI/CD, and slow production.
TestNG solves this with an annotation approach: an XML file that controls test order and parallelism without touching backend code. This makes it easier to align test design with the project.
In this guide, we will learn more about TestNG basics, JUnit comparison, annotations, suites, issues, and best practices for Selenium automation.
CTA: Run Selenium Tests on Cloud
TestNG, or “Test Next Generation," is a Java testing framework that streamlines test case designs as per the XML design of the actual website. It streamlines functional testing, unit testing, and integration testing in one window.
A study states that TestNG, along with JUnit, commands over 85% of the market share for test runner execution. TestNG is frequently preferred over JUnit for complex or large-scale integration and regression suites due to its built-in XML testing.
TestNG offers support to set up and tear down the test lifecycle, controls parallel execution of data, and automates test execution.
TestNG uses a testng.xml file to configure which test classes, methods, or groups to run, along with settings like parameters and parallel execution. TestNG then runs those tests and reports whether the functionality being checked works as expected.
Consider you want to test a calculator app. You have a Calculator class with a few methods, and you want to be sure they behave correctly. TestNG lets you write a separate test class that calls those methods and checks the results automatically.
1. The class under test
This is the plain application code. It has no TestNG in it.
public class Calculator {
public int add(int a, int b) {
return a + b;
}
public int divide(int a, int b) {
return a / b;
}
}2. The test class
Now you create a second class, CalculatorTest, that uses Calculator and verifies its behavior.
@BeforeMethod runs setUp() before every test, so each test gets a fresh Calculator object and tests cannot affect one another.
@Test marks testAdd() as a test. It calls add(2, 3) and uses Assert.assertEquals to confirm the result is 5. If it is not, the test fails.
expectedExceptions tells TestNG that testDivideByZero() should throw an ArithmeticException. The test passes if the exception occurs and fails if it does not.
@DataProvider supplies three sets of input values, and testAddParameterized() runs once for each set. This avoids writing three nearly identical tests.
import org.testng.Assert;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.DataProvider;
import org.testng.annotations.Test;
public class CalculatorTest {
private Calculator calc;
@BeforeMethod
public void setUp() {
calc = new Calculator();
}
@Test
public void testAdd() {
Assert.assertEquals(calc.add(2, 3), 5);
}
@Test(expectedExceptions = ArithmeticException.class)
public void testDivideByZero() {
calc.divide(10, 0);
}
@DataProvider(name = "addData")
public Object[][] addData() {
return new Object[][] { {1, 1, 2}, {0, 5, 5}, {-1, 1, 0} };
}
@Test(dataProvider = "addData")
public void testAddParameterized(int a, int b, int expected) {
Assert.assertEquals(calc.add(a, b), expected);
}
}When you run the tests, for example with mvn test, TestNG finds every method annotated with @Test, executes it, and reports whether it passed or failed. In this example, five tests run (one for testAdd, one for testDivideByZero, and three for the data provider rows), and all of them pass.
Read More: TestNG Annotations in Selenium: A Complete Guide
Here are the three things TestNG provides in end-to-end UI automation.
TestNG isn’t a Selenium-specific tool.
It is used in integration with Selenium for end-to-end testing but also integrates with other test automation frameworks. It offers features like parallel testing, syncing, and database seeding.
Read More:How to run parallel tests in TestNG in 2026?
Selenium alone provides browser automation but lacks advanced test management features. TestNG fills this gap by handling execution flow, grouping, and reporting. It makes automation projects more organized and easier to scale in real-world test environments.
Here are the main reasons TestNG is used with Selenium:
Read More: Mastering TestNG Reports
TestNG offers everything that JUnit doesn’t: parallel testing, native suites, and dependencies.
The older version of JUnit (JUnit 4) didn't support these features. But the updated version (JUnit 5) does support them with its extension model that supports parallel execution.
The table below reflects the comparison most teams still encounter in practice, since a large share of existing Selenium codebases are still on JUnit 4.
If your team is already on JUnit 5 for unit tests, they can consider the switch to TestNG for features like XML-driven suite control and maturity of the parallel execution model, both of which are more direct in TestNG rather than JUnit 5.
Annotations in TestNG control how tests are set up, executed, and cleaned up. They define the sequence in which methods run and are essential for managing Selenium test suites effectively.
Below are the most commonly used annotations with their practical use cases:
All the TestNG annotations (@BeforeSuite, @BeforeClass, @BeforeMethod, @Test, etc.) don't run in a random or configurable order when they're in the same class.
TestNG always runs them in one fixed sequence.
If you put login logic in @BeforeClass when you actually needed it to run before every test (@BeforeMethod), your first test gets a fresh login, but the second test reuses old session state it shouldn't have.
If you want to pull a single static data point (browser URL), you can pass a parameter, but if you want to add dynamic test data values, @dataprovider helps you do so.
@DataProvider(name = "loginCredentials")
public Object[][] getCredentials() {
return new Object[][] {
{ "admin", "password123" },
{ "guest", "guestpass" }
};
}
@Test(dataProvider = "loginCredentials")
public void verifyLogin(String username, String password) {
driver.findElement(By.id("username")).sendKeys(username);
driver.findElement(By.id("password")).sendKeys(password);
driver.findElement(By.id("loginBtn")).click();
Assert.assertEquals(driver. getTitle(), "Dashboard");
}Selenium alone provides browser automation but lacks advanced test management features. TestNG fills this gap by handling execution flow, grouping, and reporting. It makes automation projects more organized and easier to scale in real-world test environments.
Here are the main reasons TestNG is used with Selenium:
JUnit was the first widely adopted testing framework for Java, while TestNG was developed later to address its limitations. For Selenium automation, TestNG provides features that make it more suitable for managing large and complex test suites.
Here’s a table highlighting the core differences between TestNG and JUnit for Selenium testing.
This single method now runs twice, once per row, without any duplicated test code. Pair it with parallel execution (covered next), and those two runs execute concurrently instead of one after another.
Read More: How to Prioritize Tests in TestNG with Selenium
Test suites help multiple test cases to run concurrently in TestNG. It means running a single XML file that already knows which classes belong together and what order they run in.
Here is the key role test suites play in TestNG:
Read More: How to Assert and Verify Methods in Selenium
Creating a test suite in TestNG is about defining which classes to run and how they should run.
The suite is described in an XML file, which gives testers full control over structure, order, and configuration. This XML-based setup is one of the main reasons TestNG is well-suited for Selenium projects where execution often spans multiple environments and browsers.
Here are the main steps for creating and configuring a suite:
Before you can use TestNG with Selenium, the environment needs to be prepared. This ensures that the framework runs smoothly and integrates with your existing automation setup.
The requirements are straightforward but important, especially when setting up a project from scratch or onboarding new team members.
Here are the main prerequisites:
A testng.xml file tells TestNG which tests to run and how to run them. Instead of running classes one by one, you describe them in a single file and execute the whole suite at once.
Here is a step-by-step flow:
1. Start with the DOCTYPE and the <suite> tag
The <suite> tag is the root element. Every testng.xml file has exactly one suite, and its name appears in the test report.
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="CalculatorSuite">
</suite> 2. Add a <test> tag inside the suite
A <test> groups related classes together. A suite can contain many <test> tags, and each one appears as a separate[prettycode] section in the report.
<suite name="CalculatorSuite">
<test name="Calculator [/prettycode]Tests">
</test>
</suite>
3. List the classes inside <classes>
Add each test class in a <class> tag. Use the full package name if the class is inside a package, such as tests.CalculatorTest.
<test name="CalculatorTests">
<classes>
<class name="CalculatorTest" />
</classes>
</test> 4. Put it all together
Here is a complete testng.xml file for the calculator example:
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="CalculatorSuite">
<test name="CalculatorTests">
<classes>
<class name="CalculatorTest" />
</classes>
</test>
</suite> 9. Execute the suite
Right-click the XML file in your IDE and select "Run as TestNG Suite." To run it with Maven, point the Surefire plugin to the file in your pom.xml:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<suiteXmlFiles>
<suiteXmlFile>testng.xml</suiteXmlFile>
</suiteXmlFiles>
</configuration>
</plugin> Then run mvn test, and TestNG will execute the suite and generate a report.
Running TestNG tests involves writing the class under test, writing a test class, applying annotations, and executing everything through a testng.xml file. The process is straightforward once the environment is ready.
Here is a step-by-step flow:
1. Create the class to be tested
Write a Java class inside your main package. For example, Calculator.java.
public class Calculator {
public int add(int a, int b) {
return a + b;
}
public int divide(int a, int b) {
return a / b;
}
} 2. Create a test class and add the setup
Write a second class inside your test package, for example CalculatorTest.java. Use @BeforeMethod to create a fresh Calculator object before every test. This ensures each test starts clean and cannot be affected by another.
public class CalculatorTest {
private Calculator calc;
@BeforeMethod
public void setUp() {
calc = new Calculator();
}
}3. Write the test method
Mark your test with @Test. Include an assertion to validate the expected behavior.
@Test
public void testAdd() {
Assert.assertEquals(calc.add(2, 3), 5);
}4. Test an expected exception
Use expectedExceptions when a method should throw an error. The test passes only if that exception occurs.
@Test(expectedExceptions = ArithmeticException.class)
public void testDivideByZero() {
calc.divide(10, 0);
}5. Add a data provider for multiple inputs
Use @DataProvider to supply several sets of values, and link it to a test with dataProvider = "addData". The test runs once per set.
@DataProvider(name = "addData")
public Object[][] addData() {
return new Object[][] { {1, 1, 2}, {0, 5, 5}, {-1, 1, 0} };
}
@Test(dataProvider = "addData")
public void testAddParameterized(int a, int b, int expected) {
Assert.assertEquals(calc.add(a, b), expected);
} 6. Create a testng.xml file
Add your test class inside the <classes> section.
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="CalculatorSuite">
<test name="CalculatorTests">
<classes>
<class name="CalculatorTest" />
</classes>
</test>
</suite>
If your test class is inside a package, use the full name, such as tests.CalculatorTest.
7. Execute the suite
Right-click the XML file in your IDE and select "Run as TestNG Suite." You can also run mvn test if the file is configured in your pom.xml. TestNG will run all five tests (one for testAdd, one for testDivideByZero, and three for the data provider rows) and generate a report showing that all of them passed.
Even with proper setup, TestNG might face issues during Selenium automation. It might face issues related to integration, dependency injection, or package imports that helps interact with logic and create ordered tests:
Here are the most common issues and how to address them:
TestNG gives flexibility but demands careful monitoring and an eye for detail. Below are the core practices to implement while you are working with it to increase test reliability and maintainability:
By using TestNG, you can ensure tests work in order, execute after rendering timeout, and be automated safely across browsers.
With parallel execution, parameterization, and annotation, you can handle large packs of tests and make them reliable enough to run on their own.
TestNG is a dependable foundation for long-term cross-browser automation. When clubbed with products like Birds Eat Bug by BrowserStack, it enables you to record and document reports clearly across test suites to reduce the possibility of flakiness.
Get visual proof, steps to reproduce and technical logs with one click
Continue reading
Try Bird on your next bug - you’ll love it
“Game changer”
Julie, Head of QA
Try Bird later, from your desktop