TestNG Maven Dependency: pom.xml, Gradle, and Surefire Setup

TestNG Maven Dependency for pom.xml

Open pom.xml and add the dependency inside the dependencies element. The version below is the current release on Maven Central at the time of writing; check the org.testng:testng listing before you copy it into a long-lived build.

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

Three details matter here. The test scope keeps TestNG off the runtime classpath of the application you are testing, so it never ships inside the jar or war. Maven resolves TestNG's own dependencies, JCommander for the command line and SLF4J for logging, so you do not declare them. And Maven caches the download in ~/.m2/repository, so the first build needs network access and later builds do not.

If several modules share a parent pom, declare the version once under dependencyManagement in the parent and omit it in each module. That keeps every module on the same TestNG release, which matters because reports and listeners changed shape between major versions.

After saving, refresh the project in your IDE (Maven, Reload project in IntelliJ IDEA; Maven, Update Project in Eclipse) so the editor picks up the new classpath. A class under src/test/java with a method annotated @Test is now a runnable TestNG test.

TestNG in Gradle

Gradle needs two lines: the dependency, and a switch that tells the test task to use the TestNG runner instead of the JUnit default.

dependencies {
    testImplementation 'org.testng:testng:7.12.0'
}

test {
    useTestNG()
}

To drive the run from a suite file, pass it inside the useTestNG block: useTestNG { suites 'testng.xml' }. Kotlin DSL users write testImplementation("org.testng:testng:7.12.0") and tasks.test { useTestNG() }. Forgetting useTestNG() is the most common Gradle mistake: the build succeeds and reports that no tests ran.

Running testng.xml with Surefire

Maven runs tests through the Surefire plugin. With the TestNG dependency present, Surefire 3.x selects its TestNG provider on its own and runs every class that contains TestNG annotations. When you want a testng.xml to decide what runs, which groups are included, and how many threads to use, name the file in the plugin configuration:

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

The path is relative to the module root, so a file at src/test/resources/testng.xml is written as such. You can list several suite files, and each runs in turn. The Create a testng.xml File chapter covers the suite file itself, and Parallel Test Execution in TestNG covers the parallel and thread-count attributes Surefire hands through unchanged.

TestNG and Selenium in One pom.xml

Most TestNG projects on this site drive a browser, so the second dependency is usually Selenium. Selenium 4 ships Selenium Manager, which downloads the matching browser driver at run time, so no WebDriverManager or driver path is needed.

<dependencies>
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>4.49.0</version>
    </dependency>
    <dependency>
        <groupId>org.testng</groupId>
        <artifactId>testng</artifactId>
        <version>7.12.0</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Keep both libraries on current releases. Old Selenium versions pull in Guava and Netty builds that can collide with what TestNG or your application brings, and the symptom is a NoSuchMethodError deep inside a driver call rather than a clear message. When that happens, run mvn dependency:tree and look for two versions of the same library.

Running the Tests With mvn test

From the module root:

# every TestNG class Surefire can find
mvn test

# one suite file, overriding whatever pom.xml names
mvn test -Dsurefire.suiteXmlFiles=smoke.xml

# a single class, then a single method
mvn test -Dtest=LoginTest
mvn test -Dtest=LoginTest#validCredentials

# skip tests entirely when you only need the build
mvn package -DskipTests

Surefire prints a summary line with the counts of tests run, failures, errors, and skips, writes XML reports to target/surefire-reports, and TestNG writes its own HTML report to test-output (or target/surefire-reports/index.html, depending on the provider version). The TestNG Reports chapter explains how to read and publish them.

Troubleshooting the TestNG Maven Dependency

• Could not resolve org.testng:testng. The version does not exist or Maven cannot reach Maven Central. Check the version string against the listing, and behind a proxy add the proxy to ~/.m2/settings.xml.
• Package org.testng does not exist. The test class is under src/main/java, where test-scoped dependencies are not visible. Move it to src/test/java.
• No tests were executed. Surefire found no TestNG annotations, or a suiteXmlFiles path is wrong. Confirm the file path relative to the module root and that the classes named in the suite match the package names.
• Tests run in the IDE but not in Maven. The IDE uses its own runner. Usually the class name does not match Surefire's default include pattern (*Test, Test*, *Tests, *TestCase), or the Surefire version is 2.x, which needs an explicit provider. Upgrade to Surefire 3.x.
• Surefire runs JUnit instead of TestNG. Both frameworks are on the classpath and Surefire chose the wrong provider. Remove the one you do not use, or declare the surefire-testng provider as a plugin dependency.
• UnsupportedClassVersionError. TestNG 7.x is compiled for Java 11; the build is running on an older JDK. Point JAVA_HOME at Java 11 or newer, or pin an older TestNG release.

Conclusion

One dependency block with test scope is all Maven needs to run TestNG, and Gradle needs the dependency plus useTestNG(). Surefire 3.x handles discovery; a testng.xml named in suiteXmlFiles takes over when you need groups, parameters, or parallel threads. With the build in place, the next chapter, Your First TestNG Test, writes and runs the first test class.