TestNG Tutorial: Complete Guide to Java Testing Framework

TestNG Tutorial: Complete Guide to Java Testing Framework

TestNG is one of the most widely used testing frameworks in the Java ecosystem. Originally inspired by JUnit, it was built to address limitations in JUnit 3 and 4 — particularly around test configuration, parallel execution, and grouping. If you're writing Java tests for backend services, APIs, or business logic, TestNG gives you a rich, flexible toolkit.

This guide covers everything you need to get started: installation, core annotations, test groups, configuration files, and how TestNG fits into a broader test strategy.

Setting Up TestNG

Maven Dependency

Add TestNG to your pom.xml:

<dependency>
    <groupId>org.testng</groupId>
    <artifactId>testng</artifactId>
    <version>7.8.0</version>
    <scope>test</scope>
</dependency>

Gradle Dependency

testImplementation 'org.testng:testng:7.8.0'

test {
    useTestNG()
}

That's all you need to write your first test.

Core Annotations

TestNG is annotation-driven. Each annotation controls when and how a method runs relative to your test suite.

@Test

The fundamental annotation. Any method marked @Test is treated as a test case.

import org.testng.annotations.Test;
import org.testng.Assert;

public class CalculatorTest {

    @Test
    public void testAddition() {
        int result = 2 + 3;
        Assert.assertEquals(result, 5);
    }

    @Test
    public void testDivisionByZero() {
        Assert.assertThrows(ArithmeticException.class, () -> {
            int result = 10 / 0;
        });
    }
}

Setup and Teardown Annotations

TestNG provides fine-grained lifecycle hooks:

Annotation Runs
@BeforeSuite Once before all tests in the suite
@AfterSuite Once after all tests in the suite
@BeforeClass Once before the first method in the class
@AfterClass Once after the last method in the class
@BeforeMethod Before each test method
@AfterMethod After each test method
@BeforeGroups Before the first test in a specified group
@AfterGroups After the last test in a specified group
public class DatabaseTest {

    private Connection connection;

    @BeforeClass
    public void setupDatabase() {
        connection = DriverManager.getConnection("jdbc:h2:mem:testdb");
    }

    @AfterClass
    public void teardownDatabase() throws Exception {
        connection.close();
    }

    @BeforeMethod
    public void beginTransaction() throws Exception {
        connection.setAutoCommit(false);
    }

    @AfterMethod
    public void rollbackTransaction() throws Exception {
        connection.rollback();
    }

    @Test
    public void testInsertRecord() throws Exception {
        // test runs inside a transaction that gets rolled back after
        PreparedStatement stmt = connection.prepareStatement(
            "INSERT INTO users (name) VALUES (?)"
        );
        stmt.setString(1, "Alice");
        int rows = stmt.executeUpdate();
        Assert.assertEquals(rows, 1);
    }
}

This pattern — open a transaction before each test and roll it back after — keeps your database in a clean state without re-seeding between tests.

Test Groups

Groups are one of TestNG's most useful features. You can tag tests and then run only the tests that belong to a specific group.

public class ApiTest {

    @Test(groups = {"smoke", "regression"})
    public void testHealthEndpoint() {
        // fast, cheap — always run this
    }

    @Test(groups = {"regression"})
    public void testCreateUser() {
        // more expensive — run in regression pass
    }

    @Test(groups = {"slow", "regression"})
    public void testBulkImport() {
        // slow — run only in nightly
    }
}

You can then select which groups to run in your testng.xml configuration file.

The testng.xml Configuration File

The testng.xml file is how you control test suites, groups, parallel execution, and more. It lives at the root of your project (or in src/test/resources).

Basic Suite

<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="My Test Suite">
    <test name="All Tests">
        <classes>
            <class name="com.example.CalculatorTest"/>
            <class name="com.example.ApiTest"/>
            <class name="com.example.DatabaseTest"/>
        </classes>
    </test>
</suite>

Running Specific Groups

<suite name="Smoke Suite">
    <test name="Smoke Tests">
        <groups>
            <run>
                <include name="smoke"/>
            </run>
        </groups>
        <packages>
            <package name="com.example"/>
        </packages>
    </test>
</suite>

This runs only methods tagged @Test(groups = {"smoke"}) — ideal for fast pre-deployment checks.

Excluding Groups

<groups>
    <run>
        <include name="regression"/>
        <exclude name="slow"/>
    </run>
</groups>

This runs the regression suite but skips anything marked slow.

Dependencies Between Tests

TestNG lets you declare that one test depends on another:

@Test
public void testLogin() {
    // establishes session
}

@Test(dependsOnMethods = {"testLogin"})
public void testDashboard() {
    // only runs if testLogin passed
}

@Test(dependsOnMethods = {"testDashboard"})
public void testLogout() {
    // only runs if testDashboard passed
}

If testLogin fails, TestNG marks testDashboard and testLogout as skipped rather than failed — which gives you accurate failure reporting. You know the root cause without wading through cascading failures.

You can also depend on entire groups:

@Test(dependsOnGroups = {"setup"})
public void testFeature() {
    // runs after all "setup" group tests pass
}

Assertions

TestNG's Assert class provides all the standard assertions:

Assert.assertEquals(actual, expected);
Assert.assertNotEquals(actual, unexpected);
Assert.assertTrue(condition);
Assert.assertFalse(condition);
Assert.assertNull(object);
Assert.assertNotNull(object);

// Soft assertions — collect all failures before reporting
SoftAssert softAssert = new SoftAssert();
softAssert.assertEquals(user.getName(), "Alice");
softAssert.assertEquals(user.getEmail(), "alice@example.com");
softAssert.assertAll(); // throws if any assertion failed

Soft assertions are valuable when you want to validate multiple fields in a single test without stopping at the first failure.

Expected Exceptions

@Test(expectedExceptions = IllegalArgumentException.class,
      expectedExceptionsMessageRegExp = ".*cannot be negative.*")
public void testNegativeAmount() {
    new BankAccount(-100);
}

The test passes only if the expected exception is thrown with a message matching the regex.

Test Timeouts

@Test(timeOut = 3000) // milliseconds
public void testSlowOperation() {
    // fails if it takes more than 3 seconds
}

Useful for catching performance regressions in unit tests.

Where TestNG Fits in Your Test Strategy

TestNG handles unit and integration tests well — anything you can express in Java code. But a complete test strategy includes more than that.

For end-to-end and UI testing — validating that your application works correctly from a user's perspective — tools like HelpMeTest fill a different role. HelpMeTest lets you write tests in plain English, no code required, and runs them against your live application 24/7. With usage-based pricing (no base fee), it's practical for teams that want continuous E2E coverage without building and maintaining Selenium or Playwright infrastructure.

The combination works well: TestNG covers your business logic and API layer; HelpMeTest covers your user-facing flows. Neither replaces the other.

Running TestNG from the Command Line

# Maven
mvn test

# Run specific suite
mvn test -DsuiteXmlFile=smoke-suite.xml

# Run specific groups
mvn test -Dgroups=smoke

# Gradle
gradle test

TestNG Reports

TestNG generates HTML and XML reports in test-output/ by default. The HTML report shows pass/fail/skip counts, method-level results, and timing. Integrate with your CI pipeline to publish these reports as build artifacts.

For Maven, the Surefire plugin picks up TestNG automatically:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.1.2</version>
    <configuration>
        <suiteXmlFiles>
            <suiteXmlFile>testng.xml</suiteXmlFile>
        </suiteXmlFiles>
    </configuration>
</plugin>

Summary

TestNG gives Java teams a mature, annotation-driven framework with real advantages over basic JUnit: test groups, fine-grained lifecycle hooks, dependency declarations, and built-in parallel execution support (covered in depth in our parallel execution guide). The testng.xml configuration file makes suite management explicit and version-controllable.

Start with @Test, @BeforeMethod, and @AfterMethod for most tests. Add groups when you need to separate smoke from regression from nightly runs. Use dependsOnMethods when test order genuinely matters. And keep your unit tests fast — save the slow, expensive validation for your E2E layer.

Read more

Start now free