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 failedSoft 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 testTestNG 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.