Playwright Java TestNG Integration: Complete Step-by-Step Tutorial (2026)

1. Introduction

Playwright is a modern browser automation library developed by Microsoft. It supports automated web testing across Chromium, Firefox, and WebKit browsers.

Java automation testers can use Playwright Java to create reliable browser automation scripts for functional testing, regression testing, and end-to-end testing.

TestNG is a popular Java testing framework that helps testers organize test cases, manage execution, run tests in parallel, and generate test reports.

Combining Playwright Java with TestNG provides a powerful automation solution for QA engineers and SDETs.

In this Playwright Java TestNG integration tutorial, you will learn how to configure a Maven project, add Playwright and TestNG dependencies, create TestNG test classes, use annotations, implement DataProvider, execute parallel tests, generate reports, and integrate automation into CI/CD pipelines.

By the end, you will understand how to develop a reusable Playwright Java TestNG Framework suitable for real-world automation projects.

2. Prerequisites for Playwright Java TestNG Integration

Before creating the project, install the following tools.

ToolRecommended versionPurpose
Java JDK17 or laterExecute Java programs
Apache Maven3.8+Dependency management
IntelliJ IDEACommunity or UltimateJava development
Playwright Java1.64.0Browser automation
TestNG7.11.0Test execution
ChromiumPlaywright-managedBrowser testing

Verify Java installation

Open Command Prompt or Terminal:

java -version

Verify Maven installation

mvn -version

If Maven is not installed, download it from the official Apache Maven website.

You should also have basic knowledge of Java, Maven dependencies, annotations, and browser automation.

Important distinction: Playwright Java is the official Java browser automation library. TestNG is the test runner in this integration. This is different from Playwright Test, which is the separate test runner used primarily with Playwright’s Node.js ecosystem.

3. Playwright Java TestNG Project Setup Using Maven

We will use Maven to create the Playwright Java TestNG project because Maven simplifies dependency management and project configuration.

Step 1: Create a Maven project

Open IntelliJ IDEA and follow these steps:

  1. Select File → New → Project.
  2. Choose Java.
  3. Select Maven as the build system.
  4. Select JDK 17.
  5. Enter the project name PlaywrightTestNGProject.
  6. Click Create.

You can also create a project using the terminal:

mvn archetype:generate \

-DgroupId=com.techsarvam \

-DartifactId=PlaywrightTestNGProject \

-DarchetypeArtifactId=maven-archetype-quickstart \

-DinteractiveMode=false

Navigate to the project:

cd PlaywrightTestNGProject

Step 2: Add Playwright and TestNG dependencies

Open pom.xml and add the following configuration.

Complete Maven pom.xml:

<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.techsarvam</groupId>

    <artifactId>PlaywrightTestNGProject</artifactId>

    <version>1.0-SNAPSHOT</version>

    <properties>

        <maven.compiler.release>17</maven.compiler.release>

        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

    </properties>

    <dependencies>

        <!– Playwright Java –>

        <dependency>

            <groupId>com.microsoft.playwright</groupId>

            <artifactId>playwright</artifactId>

            <version>1.64.0</version>

        </dependency>

        <!– TestNG –>

        <dependency>

            <groupId>org.testng</groupId>

            <artifactId>testng</artifactId>

            <version>7.11.0</version>

            <scope>test</scope>

        </dependency>

    </dependencies>

    <build>

        <plugins>

            <!– Java Compiler –>

            <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-compiler-plugin</artifactId>

                <version>3.13.0</version>

            </plugin>

            <!– TestNG Execution –>

            <plugin>

                <groupId>org.apache.maven.plugins</groupId>

                <artifactId>maven-surefire-plugin</artifactId>

                <version>3.5.2</version>

                <configuration>

                    <suiteXmlFiles>

                        <suiteXmlFile>testng.xml</suiteXmlFile>

                    </suiteXmlFiles>

                </configuration>

            </plugin>

            <!– Playwright CLI –>

            <plugin>

                <groupId>org.codehaus.mojo</groupId>

                <artifactId>exec-maven-plugin</artifactId>

                <version>3.5.0</version>

            </plugin>

        </plugins>

    </build>

</project>

Dependency explanation:

DependencyPurpose
PlaywrightBrowser automation
TestNGTest execution and organization
Maven CompilerJava compilation
Maven SurefireRuns TestNG suites
Exec Maven PluginExecutes Playwright browser installation commands

After saving the file, reload Maven dependencies in IntelliJ IDEA.

Execute:

mvn clean install

Maven downloads the required libraries and compiles the project.

Step 3: Install Playwright browsers

Execute this command:

mvn exec:java -e \

-Dexec.mainClass=com.microsoft.playwright.CLI \

-Dexec.args=”install”

This installs the compatible Chromium, Firefox, and WebKit browser binaries.

For Linux CI environments, use:

mvn exec:java -e \

-Dexec.mainClass=com.microsoft.playwright.CLI \

-Dexec.args=”install –with-deps”

You must reinstall browser binaries after upgrading to a Playwright version that requires different browser revisions.

Playwright Java+1

4. Playwright Java TestNG Project Folder Structure

A good folder structure helps maintain reusable automation scripts.

Recommended project structure:

PlaywrightTestNGProject

│

├── pom.xml

├── testng.xml

│

├── src

│   ├── main

│   │   └── java

│   │       └── com/techsarvam

│   │           ├── pages

│   │           └── utilities

│   │

│   └── test

│       ├── java

│       │   └── com/techsarvam

│       │       ├── base

│       │       └── tests

│       │

│       └── resources

│

└── test-output

FolderResponsibility
baseBrowser setup and teardown
pagesPage Object Model classes
testsTestNG test classes
utilitiesReusable helper methods
resourcesTest data and configuration
test-outputTestNG reports

Keep browser configuration separate from test logic. This makes your framework easier to maintain as the number of test cases increases.

5. Configure TestNG Using testng.xml

TestNG uses testng.xml to organize test suites and define execution settings.

Create testng.xml in the project root directory.

<!DOCTYPE suite SYSTEM “https://testng.org/testng-1.0.dtd”>

<suite name=”Playwright Test Suite”>

    <test name=”Browser Automation Tests”>

        <classes>

            <class name=”com.techsarvam.tests.FirstTest”/>

        </classes>

    </test>

</suite>

Important TestNG annotations:

AnnotationPurpose
@TestDefines a test method
@BeforeSuiteRuns before the entire suite
@AfterSuiteRuns after the entire suite
@BeforeClassRuns before the test class
@AfterClassRuns after the test class
@BeforeMethodRuns before every test method
@AfterMethodRuns after every test method
@DataProviderSupplies multiple test data sets

TestNG uses these annotations to manage test execution and setup/teardown operations.

testng.org

To execute the XML suite directly from Maven:

mvn clean test

Because we configured the Surefire plugin to use testng.xml, Maven executes the specified suite.

6. Create Your First Playwright Java TestNG Test

Now let’s create our first browser automation test using Playwright Java and TestNG.

Create FirstTest.java inside:

src/test/java/com/techsarvam/tests

package com.techsarvam.tests;

import com.microsoft.playwright.*;

import org.testng.annotations.Test;

import org.testng.Assert;

public class FirstTest {

    @Test

    public void verifyWebsiteTitle() {

        try (Playwright playwright = Playwright.create()) {

            Browser browser =

                playwright.chromium().launch(

                    new BrowserType.LaunchOptions()

                        .setHeadless(true)

                );

            Page page = browser.newPage();

            page.navigate(“https://playwright.dev”);

            String actualTitle = page.title();

            System.out.println(

                “Website Title: ” + actualTitle

            );

            Assert.assertTrue(

                actualTitle.contains(“Playwright”),

                “Website title verification failed”

            );

            browser.close();

        }

    }

}

Explanation of the code

  1. Playwright.create() initializes Playwright.
  2. chromium().launch() launches Chromium.
  3. browser.newPage() creates a new browser page.
  4. page.navigate() opens the website.
  5. page.title() retrieves the website title.
  6. Assert.assertTrue() verifies the expected condition.
  7. browser.close() closes the browser.

The try-with-resources statement ensures that the Playwright instance is also closed.

Expected result: The test should pass if the website title contains the word Playwright.

Execute the test

Run:

mvn test

You should see the test execution summary in the Maven console.

7. Real-World Login Automation Using Playwright Java TestNG

Let’s implement a practical login automation scenario.

We will use the demo application:

https://the-internet.herokuapp.com/login

Demo credentials:

  • Username: tomsmith
  • Password: SuperSecretPassword!

Instead of repeating browser initialization in every test, we will create a reusable base class.

Step 1: Create BaseTest.java

package com.techsarvam.base;

import com.microsoft.playwright.*;

import org.testng.annotations.*;

public class BaseTest {

    protected Playwright playwright;

    protected Browser browser;

    protected Page page;

    @BeforeMethod

    public void setUp() {

        playwright = Playwright.create();

        browser = playwright.chromium().launch(

            new BrowserType.LaunchOptions()

                .setHeadless(true)

        );

        page = browser.newPage();

    }

    @AfterMethod(alwaysRun = true)

    public void tearDown() {

        if (browser != null) {

            browser.close();

        }

        if (playwright != null) {

            playwright.close();

        }

    }

}

Here, @BeforeMethod initializes a fresh browser for every test, while @AfterMethod closes the browser after execution.

Step 2: Create LoginTest.java

package com.techsarvam.tests;

import com.techsarvam.base.BaseTest;

import org.testng.annotations.Test;

import org.testng.Assert;

public class LoginTest extends BaseTest {

    @Test

    public void verifySuccessfulLogin() {

        page.navigate(

            “https://the-internet.herokuapp.com/login”

        );

        page.locator(“#username”)

            .fill(“tomsmith”);

        page.locator(“#password”)

            .fill(“SuperSecretPassword!”);

        page.locator(“button[type=’submit’]”)

            .click();

        String message =

            page.locator(“.flash”).innerText();

        Assert.assertTrue(

            message.contains(

                “You logged into a secure area!”

            ),

            “Login was unsuccessful”

        );

        Assert.assertEquals(

            page.locator(“h2”).innerText(),

            “Secure Area”

        );

    }

}

How does this framework work?

  • BaseTest manages browser initialization and cleanup.
  • LoginTest contains application-specific test steps.
  • TestNG manages execution through annotations.
  • Playwright performs browser interactions.
  • TestNG assertions validate the application response.

This is a basic reusable framework structure. In larger projects, move login actions into a separate LoginPage class and keep assertions in test classes.

8. Advanced TestNG Features with Playwright Java

TestNG provides several advanced features that help automation engineers build scalable test frameworks.

8.1 DataProvider

DataProvider allows testers to execute the same test with multiple sets of test data.

For example, you can test multiple username and password combinations.

package com.techsarvam.tests;

import com.techsarvam.base.BaseTest;

import org.testng.annotations.*;

import org.testng.Assert;

public class DataDrivenLoginTest extends BaseTest {

    @DataProvider(name = “loginData”)

    public Object[][] getLoginData() {

        return new Object[][] {

            {“tomsmith”, “SuperSecretPassword!”},

            {“invaliduser”, “wrongpassword”}

        };

    }

    @Test(dataProvider = “loginData”)

    public void verifyLogin(

        String username,

        String password) {

        page.navigate(

            “https://the-internet.herokuapp.com/login”

        );

        page.locator(“#username”).fill(username);

        page.locator(“#password”).fill(password);

        page.locator(“button[type=’submit’]”).click();

        String message =

            page.locator(“.flash”).innerText();

        if (username.equals(“tomsmith”)) {

            Assert.assertTrue(

                message.contains(“You logged into a secure area!”)

            );

        } else {

            Assert.assertTrue(

                message.contains(“Your username is invalid!”)

            );

        }

    }

}

Benefits of DataProvider:

8.2 TestNG Groups

Groups allow you to organize tests according to functionality.

Example:

@Test(groups = {“smoke”})

public void verifyLogin() {

    System.out.println(“Smoke test executed”);

}

@Test(groups = {“regression”})

public void verifyDashboard() {

    System.out.println(“Regression test executed”);

}

You can select groups in testng.xml:

<suite name=”Regression Suite”>

    <test name=”Regression Tests”>

        <groups>

            <run>

                <include name=”regression”/>

            </run>

        </groups>

        <classes>

            <class name=”com.techsarvam.tests.LoginTest”/>

        </classes>

    </test>

</suite>

8.3 TestNG Priority

Priority controls the execution order of test methods.

@Test(priority = 1)

public void openApplication() {

    System.out.println(“Application opened”);

}

@Test(priority = 2)

public void verifyLogin() {

    System.out.println(“Login verified”);

}

@Test(priority = 3)

public void verifyDashboard() {

    System.out.println(“Dashboard verified”);

}

Lower priority values execute before higher priority values.

However, independent tests should not rely on priority for their setup. Each test should ideally be able to execute independently.

8.4 Parallel Execution

TestNG supports parallel execution, which helps reduce execution time.

Update testng.xml:

<!DOCTYPE suite SYSTEM “https://testng.org/testng-1.0.dtd”>

<suite name=”Parallel Suite”

       parallel=”classes”

       thread-count=”3″>

    <test name=”Automation Tests”>

        <classes>

            <class name=”com.techsarvam.tests.LoginTest”/>

            <class name=”com.techsarvam.tests.FirstTest”/>

        </classes>

    </test>

</suite>

Here:

  • parallel=”classes” runs separate test classes in different threads.
  • thread-count=”3″ allows up to three parallel threads.

For parallel execution, every test must have its own browser and page instances. Avoid sharing mutable Playwright objects across threads.

For larger frameworks, use ThreadLocal browser contexts or a carefully designed thread-safe driver manager.

8.5 Setup and Teardown

Setup and teardown are important for browser lifecycle management.

AnnotationExample responsibility
@BeforeSuiteLoad framework configuration
@BeforeClassInitialize class-level resources
@BeforeMethodLaunch a fresh browser
@AfterMethodCapture failures and close browser
@AfterClassRelease class-level resources
@AfterSuiteGenerate final execution summary

Use the lifecycle that matches your test isolation requirements rather than launching one shared browser for unrelated tests.

9. Reporting and Debugging in Playwright Java TestNG

Reporting helps QA teams understand which tests passed, failed, or were skipped.

TestNG generates default reports after execution.

Execute:

mvn clean test

The reports are generally available in:

test-output/

    index.html

    emailable-report.html

    testng-results.xml

With Maven Surefire, you can also inspect:

target/surefire-reports/

Capture screenshots when tests fail

You can enhance the BaseTest teardown method to capture screenshots.

import org.testng.ITestResult;

import java.nio.file.*;

@AfterMethod(alwaysRun = true)

public void tearDown(ITestResult result) {

    if (result.getStatus() == ITestResult.FAILURE

            && page != null) {

        try {

            Files.createDirectories(

                Paths.get(“screenshots”)

            );

            page.screenshot(

                new Page.ScreenshotOptions()

                    .setPath(Paths.get(

                        “screenshots/”

                        + result.getName()

                        + “.png”

                    ))

            );

        } catch (Exception e) {

            e.printStackTrace();

        }

    }

    if (browser != null) browser.close();

    if (playwright != null) playwright.close();

}

For production frameworks, use unique screenshot filenames to avoid overwriting files during parallel execution.

Playwright Trace Viewer

Playwright tracing is useful when investigating difficult automation failures.

context.tracing().start(

    new Tracing.StartOptions()

        .setScreenshots(true)

        .setSnapshots(true)

        .setSources(true)

);

After test execution:

context.tracing().stop(

    new Tracing.StopOptions()

        .setPath(Paths.get(“trace.zip”))

);

Create the BrowserContext explicitly before using tracing. Save traces on failure where possible, and view them with the Playwright Trace Viewer.

10. CI/CD Integration with Playwright Java TestNG

In real-time automation projects, testers execute automation suites through CI/CD tools such as Jenkins and GitHub Actions.

CI/CD integration helps teams execute regression tests automatically whenever developers push new code.

GitHub Actions integration

Create the following workflow file:

.github/workflows/playwright-testng.yml

name: Playwright Java TestNG

on:

  push:

    branches: [main]

  pull_request:

    branches: [main]

jobs:

  automation:

    runs-on: ubuntu-latest

    steps:

      – name: Checkout Code

        uses: actions/checkout@v6

      – name: Setup Java

        uses: actions/setup-java@v5

        with:

          distribution: temurin

          java-version: ’17’

          cache: maven

      – name: Install Dependencies

        run: mvn clean install -DskipTests

      – name: Install Playwright Browsers

        run: >

          mvn exec:java

          -Dexec.mainClass=com.microsoft.playwright.CLI

          -Dexec.args=”install –with-deps”

      – name: Execute TestNG Tests

        run: mvn test

      – name: Upload Test Reports

        if: always()

        uses: actions/upload-artifact@v5

        with:

          name: testng-reports

          path: |

            test-output/

            target/surefire-reports/

            screenshots/

Workflow explanation:

  1. GitHub checks out the automation project.
  2. Java 17 is configured.
  3. Maven downloads project dependencies.
  4. Playwright browsers and Linux dependencies are installed.
  5. TestNG test cases execute using Maven.
  6. Test reports and screenshots are uploaded as artifacts.

For Jenkins, configure Java and Maven tools, install the Playwright browser dependencies on the agent, and execute:

mvn clean test

You can also configure Jenkins to publish JUnit-compatible Surefire XML reports and archive TestNG HTML reports.

11. Best Practices and Common Mistakes

Follow these best practices when developing a Playwright Java TestNG Framework.

Best practiceWhy it matters
Use Page Object ModelImproves maintainability
Create fresh browser contextsProvides test isolation
Use TestNG lifecycle annotationsManages browser resources
Use DataProviderSupports data-driven testing
Use parallel execution carefullyReduces execution time
Use reliable locatorsImproves test stability
Avoid Thread.sleep()Prevents unnecessary waiting
Capture screenshots on failureSimplifies debugging
Use environment variablesProtects credentials
Integrate CI/CDAutomates regression execution

Common mistakes beginners should avoid

1. Sharing browser objects between parallel tests

Sharing the same Page or BrowserContext across threads can cause unpredictable results. Create independent browser contexts for parallel tests.

2. Using Thread.sleep() everywhere

Playwright provides auto-waiting for actions and web-first assertions. Prefer these features instead of fixed delays.

3. Not closing browser resources

Always close Browser, BrowserContext, and Playwright instances appropriately.

4. Writing all code inside test classes

Separate page actions, test logic, and browser configuration to make the framework reusable.

5. Hardcoding passwords

Use environment variables or secure CI/CD secrets for application credentials.

12. Frequently Asked Questions (FAQs)

1. What is Playwright Java TestNG integration?

Playwright Java TestNG integration means using the Playwright Java library with TestNG to develop and execute automated browser testing scripts.

Playwright controls browsers, while TestNG manages test execution, annotations, grouping, and reporting.

2. How do I get started with Playwright Java TestNG integration?

Follow these steps:

  1. Install JDK and Maven.
  2. Create a Maven project.
  3. Add Playwright and TestNG dependencies.
  4. Install Playwright browsers.
  5. Create testng.xml.
  6. Write Java test classes.
  7. Execute tests using mvn test.

3. What are the benefits of Playwright Java TestNG integration?

The main benefits include:

  • Cross-browser automation.
  • Data-driven testing.
  • Parallel execution.
  • Test grouping and prioritization.
  • Reusable automation frameworks.
  • CI/CD integration.
  • Better test reporting.

4. Can we use TestNG with Playwright Java?

Yes. The official Playwright Java library can be integrated with TestNG through Maven dependencies.

5. How do you execute Playwright TestNG tests?

Use:

mvn clean test

This executes the TestNG suite configured in the Maven Surefire plugin.

6. Does Playwright Java support DataProvider?

Yes. TestNG DataProvider can supply multiple sets of test data to the same Playwright automation test.

7. Can we execute Playwright Java tests in parallel?

Yes. TestNG supports parallel execution through testng.xml using settings such as parallel=”classes” and thread-count.

Each parallel test must use independent browser resources.

8. What is the difference between Playwright Java and Playwright Test?

Playwright Java is the browser automation library for Java. Playwright Test is a separate test runner primarily used with JavaScript and TypeScript.

Java projects commonly integrate Playwright with JUnit or TestNG.

Leave a Comment

Your email address will not be published. Required fields are marked *