How to Create a TestNG Project in Eclipse and Run Selenium Tests

To create a TestNG project in Eclipse and run Selenium tests, create a Maven Java project, add TestNG and Selenium dependencies to pom.xml, install the TestNG Eclipse plugin, then create and run a test class with Run As → TestNG Test. For supported modern Selenium releases, start with Selenium Manager: Selenium can discover and manage a browser driver when one has not been supplied, so a separate manual driver download is usually unnecessary.

TestNG provides the test framework and test annotations; Selenium WebDriver drives the browser. The Eclipse plugin adds IDE support for creating and launching TestNG tests, but it does not replace the TestNG dependency in your project.

1. Check the prerequisites

• Eclipse IDE: Use an Eclipse installation with Maven integration. The TestNG Eclipse plugin documentation lists Eclipse 4.2 or later as its minimum.
• Java: Install a JDK and configure Eclipse to use it. TestNG’s installation guidance specifies Java 11 or later for plugin version 7.8.0 and newer. This plugin requirement is not a compatibility guarantee for every Selenium, TestNG, or Java combination.
• Browser: Install the browser you intend to automate, such as Chrome or Firefox.
• Network access: Maven needs access to resolve project dependencies. Selenium Manager may also need network access to obtain driver metadata or a driver.

Check the Java requirements for the particular Selenium and TestNG releases you select. The official setup pages explain the individual tools, but do not provide one exhaustive compatibility matrix for every IDE, Java, browser, and library combination. See TestNG’s Eclipse plugin documentation and Selenium’s Java library installation guide.

2. Install the TestNG plugin in Eclipse

1. Open Eclipse and choose Help → Eclipse Marketplace.
2. Search for TestNG, locate the TestNG for Eclipse plugin, and install it.
3. Accept the prompts and restart Eclipse when asked.

If Marketplace is unavailable, choose Help → Install New Software, enter the official update site https://testng.org/testng-eclipse-update-site, select the TestNG plugin, and complete the installation. Restart Eclipse afterward. The plugin provides a TestNG test wizard, launch options, and a results view; it does not add TestNG to a Maven project’s dependencies.

Official instructions: TestNG Eclipse plugin.

3. Create a Maven project

1. In Eclipse, choose File → New → Maven Project. If the Maven project wizard is not listed, choose File → New → Other and find it under Maven.
2. Choose a workspace location. To start with a plain project, select the option to create a simple project and skip archetype selection.
3. Enter a group ID, such as com.example, and an artifact ID, such as eclipse-testng-selenium.
4. Finish the wizard. Eclipse should show the project with a pom.xml.

Maven keeps dependency versions in the project and gives IDE and command-line runs a shared dependency source. TestNG documents Maven and Surefire integration in its Maven guide. Selenium’s Java setup guide likewise uses a build tool to add the Java library.

4. Add TestNG and Selenium dependencies

Replace the project’s pom.xml contents with the following starter configuration. The version properties are examples of where to declare versions, not timeless version recommendations. Before using it, check the official release information and confirm that your selected versions support your project’s Java runtime.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>eclipse-testng-selenium</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <testng.version>7.9.0</testng.version>
    <selenium.version>REPLACE_WITH_A_COMPATIBLE_SELENIUM_VERSION</selenium.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.seleniumhq.selenium</groupId>
      <artifactId>selenium-java</artifactId>
      <version>${selenium.version}</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.testng</groupId>
      <artifactId>testng</artifactId>
      <version>${testng.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

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

This example configures Surefire to use a suite file, which you will create below. If you want Maven to discover test classes without a suite file, remove the <configuration> block and add a compatible Surefire version. Use a Java release supported by your installed JDK and selected library versions. The TestNG Maven page includes dependency and Surefire guidance; consult it alongside TestNG’s Maven integration documentation and Selenium’s Java installation page.

After saving the POM, right-click the project and choose Maven → Update Project. Select the project and update it. Maven downloads the declared libraries and Eclipse refreshes its build path. If you use a newer compatible TestNG or Selenium release, update the properties rather than hard-coding versions in multiple places.

5. Write a runnable Selenium TestNG test

Create src/test/java/com/example/SmokeTest.java. In Eclipse, right-click the project, choose New → Class, and ensure the class is in the test source folder. If src/test/java does not exist, create it as a test source folder or create it on disk and update the Maven project.

package com.example;

import org.openqa.selenium.By;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.testng.Assert;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Test;

public class SmokeTest {
    private WebDriver driver;

    @BeforeMethod
    public void startBrowser() {
        driver = new ChromeDriver();
    }

    @Test
    public void exampleDomainHasExpectedHeading() {
        driver.get("https://example.com/");

        String heading = driver.findElement(By.cssSelector("h1")).getText();
        Assert.assertEquals(heading, "Example Domain");
    }

    @AfterMethod(alwaysRun = true)
    public void closeBrowser() {
        if (driver != null) {
            driver.quit();
        }
    }
}

The test opens a browser, visits the example domain, reads its heading, checks the expected value, and quits the session even when the test fails. Selenium’s first WebDriver script guide describes the basic session and browser interaction pattern.

ChromeDriver selects Chrome. For another supported browser, use that browser’s Selenium driver class and have the browser installed. If a test creates a driver before an assertion fails, the alwaysRun cleanup still attempts to close it. Avoid sharing one mutable WebDriver instance between parallel tests unless your test design explicitly isolates sessions.

6. Run the test from Eclipse

1. In Package Explorer, right-click SmokeTest.java.
2. Choose Run As → TestNG Test.
3. Watch the Console and TestNG results view. A passing test should show one successful test and no failures.

You can also select a method or configure a launch target through Run → Run Configurations. The TestNG plugin supports running a class, method, group, or XML suite. If the TestNG option is missing, check that the plugin is installed and that the project has its TestNG dependency.

7. Run the same project with Maven

From a terminal at the project root, run:

mvn test

With the POM shown above, Surefire reads testng.xml. Add that file at the project root:

<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="Browser smoke suite">
  <test name="Example domain">
    <classes>
      <class name="com.example.SmokeTest"/>
    </classes>
  </test>
</suite>

To run a single class through Maven, remove the suite configuration and use Surefire’s test selection, for example mvn -Dtest=SmokeTest test, subject to the selected Surefire and TestNG configuration. Keep the IDE and Maven run aligned by checking the active JDK, suite XML, groups, system properties, environment variables, and Maven plugin configuration. The Eclipse launch can use IDE settings that a Maven command does not inherit.

8. Do you need to download a browser driver?

Usually, no manual driver download is needed when you use a supported modern Selenium release. Selenium Manager is included with Selenium releases and is invoked by the bindings as a fallback when no driver has been provided. It can discover, download, and cache drivers. This depends on having the browser available and being able to reach the required metadata and downloads.

If automatic setup cannot work in your environment, use a driver available on PATH or configure the appropriate Selenium Service explicitly. This is useful in restricted networks, controlled build images, or environments that pin browser and driver versions. Follow Selenium’s current Selenium Manager documentation and the documentation for the selected browser. Avoid mixing a stale manually installed driver with an incompatible browser.

9. Useful TestNG and Selenium configuration choices

Need	Where to configure it	What to check
Run a class or method quickly	Eclipse TestNG launch	Confirm the project JRE and test class are correct.
Run a suite or groups	testng.xml and Maven Surefire, or an Eclipse suite launch	Ensure IDE and command-line runs use the same suite and group selection.
Set Java version	Maven compiler properties and Eclipse project JRE	Use a JDK compatible with every chosen dependency and plugin.
Control browser startup	Selenium browser options and Service configuration	Use options only when needed for your browser or execution environment; do not assume a local headed browser is available on a headless build machine.
Keep tests isolated	TestNG lifecycle methods and test design	Create and quit sessions predictably; avoid sharing driver state across parallel tests.
Control dependencies	pom.xml	Declare versions centrally and verify Java compatibility before upgrading.

TestNG provides additional annotations, groups, and suite configuration. Use only the settings your tests need; more configuration does not make a test more reliable by itself.

10. Common errors and fixes

Symptom	Likely cause	Fix
Run As → TestNG Test is missing	The Eclipse plugin is not installed, Eclipse was not restarted, or the file is not recognized as a Java test source.	Install or update the TestNG plugin, restart Eclipse, refresh the project, and confirm the class is under src/test/java.
org.testng or org.openqa.selenium cannot be resolved	The Maven dependencies have not resolved or the project build path is stale.	Check the POM coordinates and versions, then choose Maven → Update Project. Check the Maven console for dependency download errors.
mvn test reports no tests	The class is outside the test source tree, has no @Test method, does not match discovery rules, or a suite file does not name it.	Put the class in src/test/java, add the TestNG annotation, and check the suite class name and Surefire configuration.
SessionNotCreatedException or browser/driver version mismatch	The browser and selected driver are incompatible, a stale driver on PATH is taking precedence, or the selected Selenium setup cannot obtain a suitable driver.	Check the installed browser, remove or correct the stale driver, and review Selenium Manager output and network access. Pin a compatible driver explicitly only when your environment requires it.
Driver startup fails with a network or download error	Selenium Manager cannot reach driver metadata or download locations, or a proxy/firewall blocks access.	Configure permitted network access or provide a compatible driver through your controlled environment and Selenium Service configuration.
UnsupportedClassVersionError or compiler release error	The JDK running Maven or Eclipse is older than the configured compiler release or dependency requirement.	Align the installed JDK, Eclipse project JRE, Maven runtime, and maven.compiler.release.
Browser stays open after a failure	Cleanup did not run, the driver was not stored for cleanup, or the process ended unexpectedly.	Put driver.quit() in an @AfterMethod(alwaysRun = true) method and guard against a null driver.
Eclipse passes but Maven fails, or the reverse	The runs use different JDKs, suite files, group selections, environment variables, system properties, or dependency resolution state.	Compare the launch settings and Maven configuration. Re-run mvn test after updating the project and ensure both paths select the same tests.
Browser opens but a locator fails	The page has not reached the expected state, the selector is wrong, or the target is in a frame or shadow root.	Inspect the page and selector, wait for the needed condition, and switch into the relevant frame or use the appropriate shadow-root API where applicable.

11. Performance, reliability, and cost

• Startup time: Creating a fresh browser session for each test improves isolation but adds startup work. Reuse sessions only when the test suite is designed to prevent state leaking between tests.
• Driver setup: Selenium Manager can cache downloaded drivers, but first-time setup can require network access. For repeatable CI runs, make the JDK, browser, Selenium version, and driver strategy part of the build environment.
• Test stability: Prefer checks on meaningful page state over arbitrary fixed sleeps. Close sessions in cleanup, and make tests independent of order where possible.
• IDE versus build: Eclipse is convenient for iterating on one class or method. Maven/Surefire makes dependencies and suite configuration visible to command-line and automated runs. Run both when you need to check parity.
• Cost: The documented setup uses open-source Java libraries and tools; the dossier does not identify a required paid setup service. Browser execution still consumes machine resources, and hosted browser infrastructure, if separately chosen, may have its own costs.

Or skip the browser setup

If your goal is a website screenshot rather than an interactive browser test, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns an image or PDF, without setting up Selenium and a browser driver in your project. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.

FAQ

Is the TestNG Eclipse plugin enough to run a TestNG test?

No. The plugin adds Eclipse integration, while the Maven project still needs the TestNG runtime dependency.

Can I run a TestNG suite without Eclipse?

Yes. Configure Maven Surefire and a TestNG suite as shown above, then run the project from the command line or a build environment.

Should I use Maven or add JAR files manually?

For this workflow, Maven is the simpler way to declare and resolve Selenium and TestNG dependencies consistently between Eclipse and command-line builds.

Does this setup test every browser?

No. The example launches Chrome. Each browser needs to be installed and selected with its corresponding Selenium driver support and compatible environment.