Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 29 ยท Getting started

Your First TestNG Test

Write your first TestNG test: the @Test annotation, Assert argument order, testng.xml, and the key differences from JUnit, with a runnable JavaScript stand-in.

TestNG ("Next Generation") is the second big Java testing framework. At first glance it looks almost like JUnit: you mark methods with @Test, call assertions, and let a runner report green or red. The differences show up in the details: where the annotations live, which way round the assertion arguments go, how many objects the runner creates, and how you configure a whole run.

This lesson shows a first TestNG test, explains each piece, and then builds a tiny working model of a TestNG-style runner you can run in your browser. You have already met the JUnit side in Your First JUnit Test.

Real versus stand-in. TestNG is not installed on this site's runner, so the TestNG code in this lesson is real but read-only. The runnable examples are JavaScript stand-ins: small programs that model how a TestNG-like runner discovers annotated methods and treats them. They are not TestNG itself.

A first TestNG test (read-only)

Add TestNG to a Maven project with a test-scoped dependency (use the current 7.x release):

XML
<dependency>
  <groupId>org.testng</groupId>
  <artifactId>testng</artifactId>
  <version>7.x.y</version>   <!-- pick the latest 7.x -->
  <scope>test</scope>
</dependency>

Then write a test class under src/test/java:

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

public class DiscountsTest {

    @Test
    public void tenPercentOffTwentyDollars() {
        long result = Discounts.apply(2000, 10);

        Assert.assertEquals(result, 1800);
    }

    @Test(expectedExceptions = IllegalArgumentException.class)
    public void rejectsPercentAboveOneHundred() {
        Discounts.apply(1000, 120);
    }

    @Test(enabled = false, description = "waiting for the rounding rule")
    public void roundsHalfCentsUp() {
        Assert.assertEquals(Discounts.apply(999, 15), 849);
    }
}

Compare it with the JUnit version line by line:

Concept JUnit (Jupiter) TestNG
@Test import org.junit.jupiter.api.Test org.testng.annotations.Test
Assertion class Assertions (static methods) Assert (static methods)
Argument order assertEquals(expected, actual) assertEquals(actual, expected)
Visibility package-private is fine public methods
Expect an exception assertThrows(...) inside the test expectedExceptions attribute
Skip a test @Disabled("reason") enabled = false
Description @DisplayName description attribute

The most dangerous difference is the argument order. In TestNG the actual value comes first, and the failure message reads expected [1800] but found [1700]. If you move between frameworks and keep your muscle memory, the tests still pass and fail correctly, but the messages mislead. Check which Assert you imported before trusting the words in a failure.

JUnit and TestNG side by side

Same idea Annotated methods, assertions, a runner.
Reversed order TestNG puts actual first.
Attributes TestNG configures through annotation attributes.
Suite file An optional testng.xml describes a whole run.
1 / 2

Class-level @Test

If you put @Test on the class, every public method of the class becomes a test, and method-level @Test annotations can still override settings:

Java
@Test
public class ParsingTest {
    public void parsesAnInteger() { ... }       // a test
    public void parsesNegativeNumbers() { ... } // also a test
    void helper() { ... }                       // not public, not a test
}

Running TestNG

You have three common options. All are read-only here, but each is what you will do in real projects:

  • From the IDE. IntelliJ IDEA, Eclipse and VS Code recognize TestNG classes and show a green arrow next to them, just like JUnit.
  • From the build tool. Maven's Surefire plugin detects TestNG on the test classpath and runs the tests with mvn test. To run a specific suite file: mvn test -DsuiteXmlFile=testng.xml. Gradle uses useTestNG() in the test task.
  • From a testng.xml file. This XML describes a suite: which classes or packages to run, which groups to include, which parameters to pass.
XML
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="Checkout suite">
  <test name="Pricing">
    <classes>
      <class name="com.shop.DiscountsTest"/>
      <class name="com.shop.TaxTest"/>
    </classes>
  </test>
</suite>

You do not need testng.xml for simple projects; it becomes valuable when you want to run the same classes in different configurations, or mix browsers, environments and parameters. It gets a full lesson later: testng.xml, Suites and Test Configuration.

The result is a console summary like Total tests run: 2, Passes: 1, Failures: 0, Skips: 1, and an HTML report in test-output/ (or in target/surefire-reports under Maven).

Stand-in: annotations as registrations

How does a runner find @Test methods at all? An annotation is just metadata attached to a method. At start-up the framework scans classes (using reflection in Java), collects the annotated methods together with their attributes, and then runs the list. We can model exactly that in JavaScript: a Test(...) call registers a function along with its options, and a runner loops over the registry.

The stand-in follows TestNG's conventions on purpose: Assert.assertEquals(actual, expected), enabled: false to skip, and expectedExceptions to demand an error.

JS A TestNG-style runner: attributes and assert order

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Two tests pass, one is skipped, and two fail on purpose: expectedExceptionNeverThrown fails because the call did not throw although the attribute demanded it (the same rule real TestNG enforces), and the last one shows the argument-order trap. Notice that last test. The author wrote it JUnit-style, assertEquals(1700, apply(...)), believing 1700 was the expected value. The code actually returned 1800, so the check fails, but the stand-in (like real TestNG) reads the first argument as the actual value and prints expected [1800] but found [1700]: the numbers are the wrong way round. The verdict is right; the report misleads the reader. That is what happens when JUnit habits meet TestNG's argument order.

Stand-in: one instance or many?

A subtler difference is what an instance means. JUnit creates a new object of the test class for every test method. TestNG creates one object per test class and calls all methods on it. So a field modified by the first test is still modified when the second starts. The stand-in below runs the same three methods both ways.

JS One instance per class versus one per test

Press Run (or Ctrl + Enter) to see the console output here.

No output.

With one shared instance the counts are 1, 2, 3: tests can see each other's leftovers. With a fresh instance each one sees 1. This is why TestNG tests that keep state in fields need explicit reset code in a @BeforeMethod, a topic for TestNG Annotations and Lifecycle. JUnit can imitate TestNG's behavior with @TestInstance(PER_CLASS), but you choose that deliberately.

Which should you start with?

For this track, learn the JUnit basics first (they are the larger share of Java jobs), then see TestNG as "the same ideas plus extras": groups, dependencies, data providers and XML suites. Most of what you learn about test design transfers directly.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In TestNG, which call is written the conventional way?

    TestNG's assertEquals takes the actual value first and the expected value second, the reverse of JUnit. The failure message is worded accordingly.
  2. 2. How does TestNG's @Test(enabled = false) compare with JUnit?

    Setting enabled to false skips the test, similar to JUnit's @Disabled, and the skip is counted in the report.
  3. 3. By default, how many instances of a test class does TestNG create?

    TestNG creates one instance per class. JUnit's default is one instance per test method, which is why fields behave differently.
  4. 4. What is the job of testng.xml?

    A testng.xml file defines suites and tests, selects classes or groups, and supplies parameters. Simple projects can run without one.

Summary

  • TestNG tests are @Test-annotated public methods using org.testng.annotations.Test and org.testng.Assert.
  • Assert.assertEquals(actual, expected) has the opposite argument order from JUnit, so check your imports.
  • Attributes such as enabled, description and expectedExceptions configure a test directly in its annotation.
  • A testng.xml file describes suites; simple projects can run from the IDE or Maven without one.
  • TestNG shares one instance per class by default, JUnit creates one per test: mutable fields behave differently.
  • The JavaScript runners here are stand-ins showing how annotation registration, attributes and instances work; they are not TestNG.

Next: JUnit Assertions in Depth, where you master the full JUnit assertion toolbox and read real failure messages.