Running a TestNG Project From the Command Line

1. Overview

In this short tutorial, we’ll see how to launch TestNG tests from the command line. This is useful for builds or if we want to run an individual test directly during development.
We may use a build tool like Maven to execute our tests, or we may wish to run them directly via the java command.
Let’s look at both approaches.

2. Example Project Overview

For our example, let’s use some code containing one service that formats a date into a string:

public class DateSerializerService {
    public String serializeDate(Date date, String format) {
        SimpleDateFormat dateFormat = new SimpleDateFormat(format);
        return dateFormat.format(date);
    }
}

For the test, let’s have one test to check that a NullPointerExeception is thrown when a null date is passed to the service:

@Test(testName = "Date Serializer")
public class DateSerializerServiceUnitTest {
    private DateSerializerService toTest;

    @BeforeClass
    public void beforeClass() {
        toTest = new DateSerializerService();
    }

    @Test(expectedExceptions = { NullPointerException.class })
    void givenNullDate_whenSerializeDate_thenThrowsException() {
        Date dateToTest = null;

        toTest.serializeDate(dateToTest, "yyyy/MM/dd HH:mm:ss.SSS");
    }
}

We’ll also create a pom.xml that defines the required dependencies to execute TestNG from the command line. The first dependency we need is TestNG:

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

Next, we need JCommander. TestNG uses it to parse the command line:

<dependency>
    <groupId>com.beust</groupId>
    <artifactId>jcommander</artifactId>
    <version>1.81</version>
    <scope>test</scope>
</dependency>

Finally, if we want TestNG to write HTML test reports, we need to add the WebJar for JQuery dependency:

<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>jquery</artifactId>
    <version>3.5.1</version>
    <scope>test</scope>
</dependency>

3. Setup to Run TestNG Commands

3.1. Using Maven to Download the Dependencies

As we have a Maven project, let’s build it:

c:\> mvn test

This command should output:

[INFO] Scanning for projects...
[INFO] 
[INFO] ----------< com.baeldung.testing_modules:testng_command_line >----------
[INFO] Building testng_command_line 1.0-SNAPSHOT
[INFO] --------------------------------[ jar ]---------------------------------
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  5.639 s
[INFO] Finished at: 2021-12-19T15:16:52+01:00
[INFO] ------------------------------------------------------------------------

Now, we have everything we need to run TestNG tests from the command line.
All the dependencies will have been downloaded into the Maven local repository, which is normally inside the user’s .m2 folder.

3.2. Getting Our Classpath

To execute commands via the java command, we need to add a -classpath option:

$ java -cp "~/.m2/repository/org/testng/testng/7.4.0/testng-7.4.0.jar;~/.m2/repository/com/beust/jcommander/1.81/jcommander-1.81.jar;~/.m2/repository/org/webjars/jquery/3.5.1/jquery-3.5.1.jar;target/classes;target/test-classes" org.testng.TestNG ...

We’ll abbreviate this to -cp <CLASSPATH> in our command-line examples later on.

4. Check TestNG Command Line

Let’s check that we can access TestNG via java:

$ java -cp <CLASSPATH> org.testng.TestNG

If everything works fine, the console will show a message:

You need to specify at least one testng.xml, one class or one method
Usage: <main class> [options] The XML suite files to run
Options:
...

5. Launch TestNG Single Test

5.1. Running a Single Test With the java Command

Now, we can run a single test quickly without having to configure a single test suite file, simply using the following command line:

$ java -cp <CLASSPATH> org.testng.TestNG -testclass "com.baeldung.testng.DateSerializerServiceUnitTest"

5.2. Running a Single Test With Maven

If we want Maven to only execute this test, we could configure the maven-surefire-plugin in the pom.xml file:

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <includes>
                        <include>**/DateSerializerServiceUnitTest.java</include>
                    </includes>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

In the example, we have a profile with the name ExecuteSingleTest configured to execute DateSerializerServiceUnitTest.java. We can run this profile:

$ mvn -P ExecuteSingleTest test

As we can see, Maven requires much more configuration than a simple TestNG command-line execution to execute a single test.

6. Launch TestNG Test Suite

6.1. Running a Test Suite With the java Command

Test Suite files define how the tests should be run. We can have as many as we need. And, we can run a test suite by pointing to the XML file that defines the test suite:

$ java -cp <CLASSPATH> org.testng.TestNG testng.xml

6.2. Running a Test Suite Using Maven

If we want to execute test suites using Maven, we should configure the plugin maven-surefire-plugin:

<build>
    <pluginManagement>
        <plugins>
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <configuration>
                    <suiteXmlFiles>
                        <suiteXmlFile>testng.xml</suiteXmlFile>
                    </suiteXmlFiles>
                </configuration>
            </plugin>
        </plugins>
    </pluginManagement>
</build>

Here, we have a Maven profile named ExecuteTestSuite that will configure the maven-surefire plugin to launch the testng.xml test suite. We can run this profile using the command:

$ mvn -P ExecuteTestSuite test

7. Conclusion

In this article, we saw how the TestNG command line is helpful to run single test files, while Maven should be used to configure and launch a full set of tests.