Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 35 ยท Test Structure

Selenium with JUnit and TestNG

Structure Selenium tests in Java with JUnit 5 or TestNG: project layout, setup and teardown annotations, assertions, data-driven tests and suites, with a lifecycle stand-in.

Most large Selenium test suites in industry are written in Java, and in Java the usual test frameworks are JUnit (version 5, also called Jupiter) and TestNG. Like pytest in the previous lesson, they find your test methods, run them in a defined order, start and stop the browser through setup and teardown hooks, and report failures. Selenium itself is just a library that you call from inside those tests.

In this lesson you will see the Java project layout, the setup and teardown annotations of both frameworks side by side, assertions, data-driven tests and suites. The framework internals are the same for both, so the runnable examples rebuild the lifecycle in JavaScript to show exactly when each hook runs. If you are new to either framework, our JUnit and TestNG track teaches them from scratch.

The Java code and the Maven configuration are read-only: they need a JDK, a build tool and a real browser, none of which run here. The TryIts are stand-ins in JavaScript that imitate the order in which JUnit and TestNG call your hooks. They are not the real frameworks.

Project layout

Java projects built with Maven or Gradle put test code under src/test/java.

TEXT
shop-tests/
  pom.xml
  src/
    test/
      java/
        com/example/shop/
          pages/LoginPage.java        # page objects
          BaseTest.java               # driver setup and teardown
          LoginTest.java
      resources/
        testng.xml                    # suite file (TestNG only)
        config.properties

In pom.xml you declare the libraries your tests need: selenium-java, plus either junit-jupiter or testng, and the Surefire plugin that runs the tests during mvn test. Use the current version of each from the project's release page; the Maven, Gradle and Surefire lesson explains the build files. Selenium Manager (built into Selenium 4.6 and later) locates the browser driver, so there is no driver download step in the build.

The same test in both frameworks

A browser should be started before each test and closed after it. Both frameworks have annotations for that. This is a JUnit 5 version.

Java
// Read-only: JUnit 5
import org.junit.jupiter.api.*;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import static org.junit.jupiter.api.Assertions.assertEquals;

class LoginTest {
    private WebDriver driver;

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

    @AfterEach
    void stopBrowser() {
        driver.quit();
    }

    @Test
    void validLoginShowsDashboard() {
        LoginPage login = new LoginPage(driver).open();
        DashboardPage dashboard = login.logIn("[email protected]", "s3cret!");
        assertEquals("Dashboard", dashboard.headingText());
    }
}

And the same test in TestNG.

Java
// Read-only: TestNG
import org.testng.annotations.*;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import static org.testng.Assert.assertEquals;

public class LoginTest {
    private WebDriver driver;

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

    @AfterMethod(alwaysRun = true)
    public void stopBrowser() {
        driver.quit();
    }

    @Test
    public void validLoginShowsDashboard() {
        LoginPage login = new LoginPage(driver).open();
        DashboardPage dashboard = login.logIn("[email protected]", "s3cret!");
        assertEquals(dashboard.headingText(), "Dashboard");
    }
}

Two differences are worth noticing already. The annotation names differ (@BeforeEach and @AfterEach against @BeforeMethod and @AfterMethod). And the assertion argument order differs: JUnit's assertEquals(expected, actual) puts the expected value first, TestNG's assertEquals(actual, expected) puts it second. Swapping them does not make a passing test fail, but it makes the failure message misleading ("expected Dashboard but was Login" when the reverse is true), so keep the order of the framework you use.

Lifecycle annotations

Once per class JUnit @BeforeAll, TestNG @BeforeClass.
Per test JUnit @BeforeEach, TestNG @BeforeMethod.
Cleanup JUnit @AfterEach, TestNG @AfterMethod.
Once at the end JUnit @AfterAll, TestNG @AfterClass.

TestNG adds suite and test levels above these.

1 / 2

Putting the driver in a base class

Starting the driver in every test class would repeat code, so teams create a base test class that holds the driver, and the real test classes extend it.

Java
// Read-only: a base class (JUnit 5)
import org.junit.jupiter.api.*;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;

abstract class BaseTest {
    protected WebDriver driver;

    @BeforeEach
    void startBrowser() {
        ChromeOptions options = new ChromeOptions();
        if (Boolean.getBoolean("headless")) {          // mvn test -Dheadless=true
            options.addArguments("--headless=new");
        }
        driver = new ChromeDriver(options);
    }

    @AfterEach
    void stopBrowser() {
        if (driver != null) {
            driver.quit();
        }
    }
}

Boolean.getBoolean("headless") reads a Java system property, so you can pass -Dheadless=true on the command line, the Java counterpart of the --headless pytest option you saw before. Keep this base class small: the driver and nothing else.

When each hook runs

The order of hooks matters for speed and isolation. Class-level hooks run once, so an expensive browser started there is shared by every test in the class. Method-level hooks run around each test, so each test gets a fresh browser. The stand-in below is a miniature runner that uses the hook names of JUnit 5 and prints the order of events for two tests.

JS Lifecycle hooks in order

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

No output.

The browser is started and quit around each test, and the quit happens after the failing test as well. The class-level hooks surround the whole group. TestNG has the same idea with more levels: @BeforeSuite, @BeforeTest and @BeforeGroups run above @BeforeClass, which is useful for work such as starting a test server once for the entire run.

Data-driven tests

Both frameworks can run one method with many rows of data. With JUnit 5 you add the junit-jupiter-params module and write a @ParameterizedTest.

Java
// Read-only: JUnit 5 parameterized test
@ParameterizedTest
@CsvSource({
    "[email protected], wrong,   Wrong email or password",
    "'',              s3cret!, Email is required",
    "[email protected], '',      Password is required"
})
void loginShowsError(String email, String password, String message) {
    LoginPage page = new LoginPage(driver).open().logInExpectingError(email, password);
    assertEquals(message, page.errorMessage());
}

TestNG uses a @DataProvider method that returns an array of rows, and a @Test(dataProvider = "...") that consumes it.

Java
// Read-only: TestNG data provider
@DataProvider(name = "badLogins")
public Object[][] badLogins() {
    return new Object[][] {
        {"[email protected]", "wrong",   "Wrong email or password"},
        {"",                "s3cret!", "Email is required"},
        {"[email protected]", "",        "Password is required"},
    };
}

@Test(dataProvider = "badLogins")
public void loginShowsError(String email, String password, String message) {
    LoginPage page = new LoginPage(driver).open().logInExpectingError(email, password);
    assertEquals(page.errorMessage(), message);
}

The two stand-in tests below imitate a data provider and show the argument-order lesson from earlier: the same failing check produces a very different message depending on which side you pass first.

JS A data provider and the assertEquals order

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

No output.

Each row is one test result, and row 4 fails alone without hiding the others. The last two lines show why the order matters: with the arguments swapped, the message claims the expected value was "OK", which sends the reader in the wrong direction.

Suites and running the tests

With Maven, mvn test runs every test class that the Surefire plugin finds. To run a subset, use tags in JUnit 5 (@Tag("smoke") plus -Dgroups=smoke) or groups in TestNG (@Test(groups = "smoke")). TestNG can also describe an entire run in a testng.xml file.

XML
<!-- Read-only: src/test/resources/testng.xml -->
<!DOCTYPE suite SYSTEM "https://testng.org/testng-1.0.dtd">
<suite name="Shop regression">
  <test name="Login and cart">
    <classes>
      <class name="com.example.shop.LoginTest"/>
      <class name="com.example.shop.CartTest"/>
    </classes>
  </test>
</suite>

The XML file is where TestNG users usually switch on parallel execution and pick which browser parameter to pass, which Running in CI returns to. For help choosing, see JUnit vs TestNG. For a new project, JUnit 5 is a safe default; TestNG remains common in existing Selenium code bases and in teams that like its XML suites and built-in dependencies between tests.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which JUnit 5 annotation runs before every single test method, a good place to start a fresh browser?

    @BeforeEach runs before each test. @BeforeAll runs once per class, while @BeforeClass and @BeforeSuite are TestNG annotations.
  2. 2. What is the TestNG counterpart of JUnit 5's @AfterEach?

    @AfterMethod runs after each test method in TestNG. @AfterClass runs once after all tests of the class.
  3. 3. TestNG's assertEquals(a, b) expects which argument first?

    TestNG uses assertEquals(actual, expected), the reverse of JUnit's assertEquals(expected, actual). Using the wrong order only affects the failure message.
  4. 4. Where does Maven expect Java test code by default?

    src/test/java holds test classes and src/test/resources holds test resources. Production code lives in src/main.
  5. 5. Why should driver.quit() be in an @AfterEach or @AfterMethod hook rather than at the end of the test body?

    If an assertion fails in the test body, the lines after it never run. A teardown hook runs regardless, so the browser is always closed.

Summary

  • Java Selenium suites run inside JUnit 5 or TestNG; Maven or Gradle builds and runs them from src/test/java.
  • @BeforeEach/@AfterEach (JUnit) and @BeforeMethod/@AfterMethod (TestNG) start and quit a browser around each test, and always run teardown.
  • Class-level hooks run once; TestNG adds suite, test and group levels.
  • @ParameterizedTest with @CsvSource and TestNG's @DataProvider run one method over many rows.
  • Mind the assertEquals argument order, and use tags, groups or testng.xml to choose what runs.

Next: Test Data and Configuration.