Contents

    Guides

    What is TestNG in Selenium? A Complete Guide for 2026

    Published on

    September 29, 2025
    What is TestNG in Selenium? A Complete Guide for 2026

    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

    What is TestNG

    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.

    Example of TestNG: Testing a Calculator

    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

    Key Features of TestNG in Automation

    Here are the three things TestNG provides in end-to-end UI automation.

    • Annotations control the lifecycle: The framework controls the test execution, method, run, and setup and teardown of tests on its own so that tests execute in order. Some methods it uses are @beforemethod, @test, @afterclass, and so on, for test creation.
    • Configuration is external: With testng.xml, you can define main classes, how many threads are to be executed, and the parameters to be passed during the test. The same class can run sequentially across multiple browsers. 
    • Test data is decoupled from logic: TestNG feeds data into tests instead of hardcoding it via two mechanisms: @Parameters and @DataProvider. @Parameters feeds static, XML-defined values (like a browser name); @DataProvider feeds dynamic, code-generated datasets (like rows of login credentials).

    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?

    Why Use TestNG in Selenium Automation

    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:

    • Flexible test execution: TestNG allows test methods to run in a defined order, with priorities or dependencies. This prevents unstable runs and ensures critical flows are always tested first.
    • Parallel testing: Instead of running one test after another, TestNG can run tests across multiple browsers or environments at the same time. This saves execution time, which is important when regression packs contain hundreds of test cases.
    • Parameterization support: Data can be passed into tests without hardcoding values. This helps when the same script must run with different inputs, like user credentials or environment-specific URLs.
    • Grouping and tagging: Test cases can be grouped into categories such as smoke, regression, or functional. Teams can then selectively execute only the required group rather than the entire suite.
    • Detailed reporting: TestNG generates HTML reports that show which tests passed, failed, or were skipped, along with error stack traces. This gives testers and developers immediate feedback for debugging.
    • Integration with build tools: TestNG works smoothly with tools like Maven and Jenkins, enabling continuous testing in CI/CD pipelines. This is a key advantage for teams running automated tests on every build.

    ‍Read More: Mastering TestNG Reports

    Differences Between TestNG and JUnit for Selenium Testing

    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.

    Aspect JUnit TestNG
    Annotations Basic sets such as @Before, @After, and @Test (JUnit 4) Richer sets such as @BeforeSuite, @BeforeTest, @BeforeClass, and @AfterMethod
    Configuration Setup mostly at the method or class level Configurable at suite, test, class, and method levels via annotations and XML
    Parallel Execution Not native in JUnit 4; JUnit 5 supports it via config, but setup is more involved Native parallel execution by thread, class, or suite, configured directly in testng.xml
    Test Grouping No built-in grouping in JUnit 4; JUnit 5 added @Tag Group tests using the groups attribute and run selectively
    Dependencies Tests run independently by default Supports dependencies with dependsOnMethods and dependsOnGroups
    Reporting Minimal built-in output, plugins required for HTML reports Built-in HTML reports with pass/fail/skip counts and stack traces
    Test Suites No native suite concept in JUnit 4; requires custom runners or build tool configs XML-based test suites for structured execution and parallel settings

    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.

    TestNG Annotations and Their Use Cases

    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:

    • @BeforeSuite / @AfterSuite: Run once before and after the entire test suite. Typically used for initializing or closing resources that apply to all tests, such as database connections, Selenium Grid setup, or server configuration.
    • @BeforeTest / @AfterTest: Run before and after all test methods defined inside a <test> tag in the XML file. Useful for environment-specific setup, such as loading configuration files or creating browser instances for a given test set.
    • @BeforeClass / @AfterClass: Run before and after the first and last test methods in a class. This is where browser setup and teardown for a particular test class is often handled in Selenium.
    • @BeforeMethod / @AfterMethod: Run before and after every individual test method. Commonly used for logging into an application before a test and logging out or clearing session data after it finishes.
    • @Test: Marks a method as a test case. Parameters like priority, groups, and dependsOnMethods provide additional control over how the test runs.
    • @DataProvider: Supplies test data to methods, supporting parameterized testing. Ideal for Selenium tests that need to run against multiple sets of inputs, such as different user credentials or browsers.
    • @Parameters: Reads values directly from the XML configuration file and passes them to test methods. Often used for passing URLs, environment values, or browser types.

    TestNG Execution Order and Parameterization: @Parameters vs. @DataProvider

    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");
    }

    Why Use TestNG in Selenium Automation

    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:

    • Flexible test execution: TestNG allows test methods to run in a defined order, with priorities or dependencies. This prevents unstable runs and ensures critical flows are always tested first.
    • Parallel testing: Instead of running one test after another, TestNG can run tests across multiple browsers or environments at the same time. This saves execution time, which is important when regression packs contain hundreds of test cases.
    • Parameterization support: Data can be passed into tests without hardcoding values. This helps when the same script must run with different inputs, like user credentials or environment-specific URLs.
    • Grouping and tagging: Test cases can be grouped into categories such as smoke, regression, or functional. Teams can then selectively execute only the required group rather than the entire suite.
    • Detailed reporting: TestNG generates HTML reports that show which tests passed, failed, or were skipped, along with error stack traces. This gives testers and developers immediate feedback for debugging.
    • Integration with build tools: TestNG works smoothly with tools like Maven and Jenkins, enabling continuous testing in CI/CD pipelines. This is a key advantage for teams running automated tests on every build.

    Differences Between TestNG and JUnit for Selenium Testing

    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. 

    Aspect JUnit TestNG
    Annotations Basic set such as @Before, @After, @Test Richer set such as @BeforeSuite, @BeforeTest, @BeforeClass, @AfterMethod
    Configuration Setup mostly at method or class level Configurable at suite, test, class, and method levels via annotations and XML
    Parallel execution Not native, requires external libraries or runners Native parallel execution by thread, class, or suite configured in XML
    Test grouping No built-in grouping mechanism Group tests using the groups attribute and run selectively
    Dependencies Tests run independently by default Supports dependencies with dependsOnMethods and dependsOnGroups
    Reporting Minimal built-in output, plugins required for HTML reports Built-in HTML reports with pass/fail/skip counts and stack traces
    Suites No native suite concept, requires custom runners or build tool configs XML-based test suites for structured execution and parallel settings

    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

    Role of Test Suites in TestNG

    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:

    • Centralized execution: Suites bring multiple test classes together so they can be executed in a single run. The tester doesn’t have to worry about which test to execute first, as suites automatically carry them out. It is very useful for regression or smoke testing.
    • Selective control: Suites conduct tests based on their own quality mechanism. They are programmed to run tests or skip tests.
    • Parellel runs, at four different granularities: Suites can be run in parallel. The attribute on <suite> accepts methods, classes, tests, and instances.
    • Thread count: Suites have a thread count to determine how many of these tests run in parallel at one time. If you set it too high for small Selenium grids, you will get flaky tests and repetition.
    • Environment configuration suites provide a place to configure parameters like browser type, base URL, or system properties that apply to all included tests. This reduces duplication and keeps the framework consistent.
    • Dependency management: Suites handle the dependencies between test cases so that there will be no overlap between app states.
    • Reporting alignment: It is easy to generate bug reports within suites, making it easier to trace the failures back to a specific group, browser, or module.

    Read More: How to Assert and Verify Methods in Selenium

    How to Create and Configure a Test Suite in TestNG

    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:

    1. Create a testng.xml file: At the root of your project, add an XML file (usually named testng.xml). This file will hold suite and test definitions.
    2. Define the suite: Start with the <suite> tag and provide attributes like name and parallel if needed. For example, <suite name="RegressionSuite"> identifies the suite clearly.
    3. Add tests inside the suite: Use the <test> tag to define a logical group of classes. Each <test> can include one or more classes. This is useful for grouping by module or feature.
    4. Include test classes: Within each <test>, specify <classes> and <class> tags that point to your Java test classes. This is where you decide which classes belong to the suite run.
    5. Set parameters: Use <parameter> tags to pass values such as browser type, environment URLs, or credentials. These parameters are mapped to methods through the @Parameters annotation.
    6. Control execution: Add attributes like thread-count and parallel at the suite or test level to enable parallel execution. This allows scaling across browsers or machines.
    7. Save and run: Once the XML file is ready, right-click on it in your IDE (such as Eclipse or IntelliJ) and select "Run as TestNG Suite." TestNG reads the file and executes tests as defined.

    Prerequisites for Running TestNG Tests in Selenium

    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:

    • Java installation: TestNG is built on Java, so the JDK must be installed and configured in the system. Verify installation with the java -version command.
    • IDE support: Most testers use Eclipse or IntelliJ IDEA. Both IDEs provide TestNG plugins that simplify suite creation and execution. The plugin can be installed directly from the IDE marketplace.
    • Selenium libraries: Add Selenium client libraries to your project. This can be done manually by downloading the JARs or by using build tools like Maven or Gradle for dependency management.
    • TestNG dependency: Add the TestNG JARs or declare the dependency in pom.xml (for Maven) or build.gradle. This gives your project access to TestNG classes and annotations.
    • Browser drivers: Ensure that the WebDriver executables for Chrome, Firefox, Edge, or any other browser are available and mapped to the system path. Without drivers, Selenium scripts cannot launch browsers.
    • Build tool setup (optional but recommended): Tools like Maven or Gradle help manage dependencies, run suites from the command line, and integrate with CI/CD pipelines. While not mandatory, they are useful for long-term maintenance.

    How to Write a TestNG XML File for Executing Test Suites

    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.

    How to Run TestNG Tests: Step-by-Step Example

    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.

    Troubleshooting Common Issues in TestNG

    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 not detected in IDE: If the plugin is not installed or the project is missing TestNG dependencies, you won’t be able to access it. Confirm that the TestNG plugin is enabled and that the JARs or Maven dependencies are present.
    • Browser not launching: If the WebDriver executable is missing or not mapped to the system path, Selenium will fail to start the browser. Download the correct driver version and make sure it matches the browser installed.
    • Annotations not working as expected: A frequent mistake is mixing JUnit annotations with TestNG or using the wrong order. Check that all methods use TestNG-specific annotations like @BeforeClass instead of JUnit equivalents.
    • Test dependencies failing: When using dependsOnMethods or dependsOnGroups, a single failed test can skip all dependent ones. Ensure dependencies are logically necessary and avoid over-chaining.
    • Parameter injection errors: If parameters from testng.xml are not mapped properly, TestNG throws errors at runtime. Verify that parameter names in the XML match those in the @Parameters annotation.
    • Intermittent failures only under parallel execution: Most often a single WebDriver instance being read and written by two threads at once. Check for static or instance-level driver fields that aren't wrapped in ThreadLocal before assuming the test itself is unreliable.
    • Report not generated: This usually happens when the suite crashes before completion or when reports are disabled. Check the test-output folder in the project and ensure the suite runs without interruption.

    Best Practices for TestNG Automation

    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:

    • Keep tests isolated: Each test should have its before and after hooks determined for methods so that they run independently, without interfering with other tests in the pipeline.
    • Thread-safe WebDriver: Create WebDrivers for every thread so that each component loads independently on the browser. Mixing WebDrivers leads to session conflicts that result in flakiness.
    • Use Page Object Model: Store locators and page actions in page classes, and keep validations in test classes for clarity and reusability.
    • Prefer explicit waits over hardcoded pauses: Replace Thread. sleep() with WebDriver Wait to handle dynamic elements. This matters even more in parallel runs, where a fixed sleep on every thread adds to a longer runtime.
    • Parameterize inputs: Use @DataProvider and @Parameters to run tests with different datasets and environment-specific values without duplicating code.
    • Retry carefully: Flaky tests should be fixed, but where retries are necessary, log them clearly so unstable cases remain visible.
    • Capture diagnostics: Save screenshots, logs, and page sources on failure. These artifacts help developers identify issues quickly.
    • Real Device testing: Local environments cannot capture differences in OS, browser versions, and hardware. Testing on real devices uncovers these issues. BrowserStack offers a Selenium grid with real devices, parallel execution, CI/CD support, and debugging logs.

    Conclusion

    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. 

    Data-rich bug reports loved by everyone

    Get visual proof, steps to reproduce and technical logs with one click

    Make bug reporting 50% faster and 100% less painful

    Rating LogosStars
    4.6
    |
    Category leader

    Liked the article? Spread the word

    Put your knowledge to practice

    Try Bird on your next bug - you’ll love it

    “Game changer”

    Julie, Head of QA

    star-ratingstar-ratingstar-ratingstar-ratingstar-rating

    Overall rating: 4.7/5

    Try Bird later, from your desktop