1. Introduction
Modern web applications require reliable and continuous testing. Manual testing alone can take considerable time, especially when teams need to validate login workflows, forms, shopping carts, and other important features after every release.
Browser automation helps QA teams execute these repetitive checks faster. Selenium has been a popular choice for Java automation testers, but Playwright is another modern option worth learning.
This Playwright Java tutorial explains how to automate web applications using the official Playwright Java library. You will learn to launch browsers, interact with web elements, write automated test scripts, validate application behavior, and execute tests using JUnit.
If you are a fresher, Java automation tester, or Selenium professional transitioning to modern browser automation, this guide will help you build practical skills.
2. What Is Playwright Java?
Playwright Java is an open-source browser automation library maintained by Microsoft. It allows developers and QA engineers to control browsers using Java code.
You can use it to automate user interactions, validate application behavior, perform cross-browser testing, and execute regression testing.
Key features of Playwright Java
- Cross-browser support: Automate Chromium, Firefox, and WebKit.
- Automatic waiting: Playwright waits for elements to become actionable before performing supported actions.
- Modern locators: Locate elements using roles, labels, text, placeholders, and test IDs.
- Browser contexts: Create isolated browser sessions for independent tests.
- Screenshots: Capture screenshots for test evidence and debugging.
- Network handling: Monitor requests and responses and work with API requests.
- Debugging: Use headed mode, slow motion, and Playwright Inspector.
Playwright Java architecture
Playwright Java follows a client-driver-browser communication model. Your Java program uses the Playwright API, which communicates with the Playwright driver to control the selected browser.
The basic workflow is:
- Create a Playwright instance.
- Launch a browser.
- Create a browser context.
- Open a page.
- Locate and interact with elements.
- Validate the expected result.
- Close browser resources.
Supported browsers
| Browser | Description |
| Chromium | Supports Chromium-based browser automation |
| Firefox | Automates Firefox |
| WebKit | Automates the WebKit browser engine |
You can use the same Java automation code with different browser engines, subject to browser-specific behavior and application compatibility.
Playwright Java vs Playwright Test
An important point for beginners: Playwright Java and Playwright Test are not the same thing.
| Feature | Playwright Java | Playwright Test |
| Programming language | Java | JavaScript / TypeScript |
| Browser automation | Yes | Yes |
| Test execution | JUnit or TestNG, for example | Built-in test runner |
| Dependency management | Maven or Gradle | npm |
| Assertions | Playwright assertions or Java assertions | Playwright Test expect |
| Reporting | JUnit/TestNG and reporting integrations | Built-in reporters |
Java developers generally combine the Playwright Java library with an external test runner such as JUnit or TestNG.
3. Prerequisites
Before following this Playwright Java tutorial, install the following:
| Tool | Purpose |
| Java JDK 8 or later | Executes Java programs |
| Maven | Manages dependencies and test execution |
| IntelliJ IDEA or Eclipse | Java development environment |
| Internet connection | Downloads dependencies and browsers |
| Supported operating system | Runs Playwright browsers |
For a new project, Java 17 or a newer supported JDK is a practical choice.
Verify your installation:
java -version
mvn -version
Both commands should display installed version information.
4. Installation and Project Setup
Let’s create a Maven project for browser automation.
Step 1: Create a Maven project
Open IntelliJ IDEA and create a new Maven project named PlaywrightJavaTutorial.
Use this folder structure:
PlaywrightJavaTutorial
│
├── pom.xml
└── src
├── main
│ └── java
│ └── org.example
│ └── App.java
└── test
└── java
├── pages
│ └── LoginPage.java
└── tests
└── LoginTest.java
Step 2: Add Playwright Maven dependency
Open pom.xml and add the official Playwright Java dependency.
<dependencies>
<dependency>
<groupId>com.microsoft.playwright</groupId>
<artifactId>playwright</artifactId>
<version>1.64.0</version>
</dependency>
</dependencies>
The version shown is the current example version in the official installation documentation. Check the official documentation when starting a new project for the latest release.
Step 3: Add JUnit 5 dependency
JUnit 5 provides annotations and test execution capabilities.
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.11.4</version>
<scope>test</scope>
</dependency>
Configure Maven Surefire to execute JUnit 5 tests:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.5.2</version>
</plugin>
</plugins>
</build>
Step 4: Download browser binaries
Run the following command to install the browser binaries required by Playwright:
mvn exec:java -D exec.mainClass=”com.microsoft.playwright.CLI” -D exec.args=”install”
On Linux CI environments, you can install browser system dependencies as well:
mvn exec:java -D exec.mainClass=”com.microsoft.playwright.CLI” -D exec.args=”install –with-deps chromium”
If Maven cannot find the Exec plugin, add org.codehaus.mojo:exec-maven-plugin to your build plugins or use the complete Maven command with its plugin coordinates.
5. First Java Automation Script
Let’s create a simple program that opens a browser, navigates to a website, and verifies its page title.
Create App.java:
package org.example;
import com.microsoft.playwright.*;
import java.util.regex.Pattern;
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
public class App {
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
Browser browser = playwright.chromium().launch();
Page page = browser.newPage();
page.navigate(“https://playwright.dev/”);
System.out.println(“Page Title: ” + page.title());
assertThat(page).hasTitle(
Pattern.compile(“Playwright”)
);
browser.close();
}
}
}
Run the program using your IDE or configure the Maven Exec plugin and execute:
mvn compile exec:java -D exec.mainClass=”org.example.App”
Expected result: The Chromium browser opens in headless mode, navigates to the Playwright website, and prints its page title. The assertion passes if the title contains the expected text.
To display the browser window during execution:
Browser browser = playwright.chromium().launch(
new BrowserType.LaunchOptions().setHeadless(false)
);
This is a useful first Playwright Java tutorial example because it introduces browser launch, navigation, and verification.
6. Locators and Browser Actions
Locators identify elements on a web page. Playwright provides several locator methods for interacting with buttons, text fields, links, and other controls.
Common locator strategies
| Locator | Java example |
| CSS selector | page.locator(“#username”) |
| Text | page.getByText(“Welcome”) |
| Role | page.getByRole(AriaRole.BUTTON) |
| Label | page.getByLabel(“Email”) |
| Placeholder | page.getByPlaceholder(“Enter email”) |
| Test ID | page.getByTestId(“submit-button”) |
Prefer role-based and other user-facing locators when possible. Use CSS selectors when the application provides stable attributes.
Click action
page.locator(“#login-button”).click();
Fill action
page.locator(“#username”).fill(“testuser”);
Keyboard action
page.locator(“#password”).fill(“password123”);
page.locator(“#password”).press(“Enter”);
Role-based button action
page.getByRole(
AriaRole.BUTTON,
new Page.GetByRoleOptions().setName(“Login”)
).click();
These methods make automated test scripts readable and easier to maintain.
7. Assertions and Test Runner
Assertions verify whether the application produces the expected result.
Playwright Java provides web-first assertions through PlaywrightAssertions.assertThat(). These assertions automatically retry until the expected condition is satisfied or the timeout is reached.
For example:
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
assertThat(page.locator(“#dashboard”)).isVisible();
assertThat(page).hasTitle(“My Application”);
For test organization, use JUnit or TestNG. The following example uses JUnit 5.
Common JUnit annotations include:
- @Test – Marks a test method.
- @BeforeAll – Runs once before all tests.
- @BeforeEach – Runs before each test.
- @AfterEach – Runs after each test.
- @AfterAll – Runs once after all tests.
Execute the tests with:
mvn test
Maven Surefire stores test results under:
target/surefire-reports/
8. Real-World Login Test Example
Now let’s build a reusable login automation example using the SauceDemo practice website.
Test website: https://www.saucedemo.com/
Practice credentials:
- Username: standard_user
- Password: secret_sauce
These are public practice-site credentials intended for demonstration.
Step 1: Create a LoginPage class
Create LoginPage.java:
package pages;
import com.microsoft.playwright.*;
public class LoginPage {
private final Page page;
private final Locator username;
private final Locator password;
private final Locator loginButton;
public LoginPage(Page page) {
this.page = page;
username = page.locator(“#user-name”);
password = page.locator(“#password”);
loginButton = page.locator(“#login-button”);
}
public void open() {
page.navigate(“https://www.saucedemo.com/”);
}
public void login(String user, String pass) {
username.fill(user);
password.fill(pass);
loginButton.click();
}
}
This class follows the Page Object Model. It separates page locators and reusable actions from test logic.
Step 2: Create the JUnit test
Create LoginTest.java:
package tests;
import com.microsoft.playwright.*;
import org.junit.jupiter.api.*;
import pages.LoginPage;
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
public class LoginTest {
static Playwright playwright;
static Browser browser;
BrowserContext context;
Page page;
@BeforeAll
static void setupBrowser() {
playwright = Playwright.create();
browser = playwright.chromium().launch();
}
@BeforeEach
void setupTest() {
context = browser.newContext();
page = context.newPage();
}
@Test
void validLoginTest() {
LoginPage loginPage = new LoginPage(page);
loginPage.open();
loginPage.login(
“standard_user”,
“secret_sauce”
);
assertThat(page.locator(“#inventory_container”))
.isVisible();
assertThat(page)
.hasURL(“https://www.saucedemo.com/inventory.html”);
}
@AfterEach
void closeContext() {
context.close();
}
@AfterAll
static void closeBrowser() {
browser.close();
playwright.close();
}
}
Step 3: Execute the login test
Run:
mvn test
Expected execution flow:
- Playwright launches Chromium.
- A new browser context and page are created.
- The SauceDemo login page opens.
- The test enters the username and password.
- The login button is clicked.
- The inventory page is verified.
- JUnit reports the test result.
If the application displays the inventory page and the URL matches the expected address, the test passes.
This example gives beginners a foundation for building a Playwright Java Framework using reusable page objects.
9. Screenshots, Reporting, and Debugging
Screenshots provide visual evidence of application behavior and help investigate test failures.
Add a screenshot to your test:
import java.nio.file.Files;
import java.nio.file.Paths;
Files.createDirectories(Paths.get(“target/screenshots”));
page.screenshot(
new Page.ScreenshotOptions()
.setPath(Paths.get(“target/screenshots/login.png”))
);
Debugging Playwright Java tests
Use headed mode to see browser interactions:
Browser browser = playwright.chromium().launch(
new BrowserType.LaunchOptions()
.setHeadless(false)
.setSlowMo(500)
);
The setSlowMo() option adds a delay between browser operations, making local debugging easier.
You can also use Playwright Inspector and the official debugging tools to inspect locators and understand test failures.
Reporting
JUnit and Maven Surefire generate test result files. For richer HTML reports, you can integrate Allure with JUnit.
A practical reporting workflow is:
- Execute the test suite.
- Collect passed and failed test results.
- Capture screenshots when required.
- Generate an HTML report.
- Share the report with the development and QA teams.
10. Best Practices and Common Mistakes
| Best practice | Benefit |
| Prefer role and label locators | Creates more resilient tests |
| Avoid fixed Thread.sleep() | Reduces unnecessary delays |
| Create a separate context per test | Improves test isolation |
| Close browser resources | Prevents resource leaks |
| Use Page Object Model | Encourages reusable code |
| Keep test data separate | Simplifies maintenance |
| Use meaningful assertions | Makes failures easier to understand |
Common mistakes to avoid
Using fixed waits
Avoid:
Thread.sleep(5000);
Prefer condition-based assertions:
assertThat(page.locator(“#inventory_container”)).isVisible();
Using unstable selectors
Long CSS and XPath expressions can break when developers change the page structure. Prefer accessible locators or stable test IDs.
Sharing browser sessions between tests
A browser context stores cookies and session data. Use independent contexts to prevent one test from affecting another.
Forgetting browser cleanup
Close the context after each test and close the browser and Playwright instance after the suite finishes.
11. CI/CD Integration
A Playwright Java project can run automatically through Jenkins or GitHub Actions. This helps teams execute browser automation during pull requests and code releases.
Here is a basic GitHub Actions workflow:
name: Playwright Java Tests
on:
push:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
– name: Checkout code
uses: actions/checkout@v4
– name: Set up Java
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: ’17’
cache: maven
– name: Compile project
run: mvn -B compile
– name: Install Chromium
run: >
mvn exec:java
-D exec.mainClass=”com.microsoft.playwright.CLI”
-D exec.args=”install –with-deps chromium”
– name: Execute tests
run: mvn test
This workflow checks out the project, installs Java, compiles the code, installs Chromium and its Linux dependencies, and runs the tests.
For Jenkins, create equivalent pipeline stages for source checkout, Java setup, browser installation, Maven test execution, and report publishing.
12. Playwright Java Interview Questions and FAQs
Q1. What is Playwright Java?
Playwright Java is a Microsoft-maintained Java library for automating web browsers. It supports Chromium, Firefox, and WebKit.
Q2. What is a Playwright Java tutorial?
A Playwright Java tutorial is a learning guide that explains how to use the Java library for browser automation, including installation, locators, actions, assertions, and test execution.
Q3. How do I get started with Playwright Java?
Install Java and Maven, create a Maven project, add the Playwright dependency, install browser binaries, and write a simple browser navigation program.
Q4. Is Playwright Java suitable for beginners?
Yes. Beginners with basic Java knowledge can start with browser launch and navigation, then learn locators, assertions, JUnit, and framework development.
Q5. Does Playwright Java support JUnit and TestNG?
Yes. You can integrate Playwright Java with JUnit or TestNG to organize and execute automated tests.
Q6. What is BrowserContext?
BrowserContext represents an isolated browser session. It helps tests use separate cookies, storage, and session information.
Q7. What is the difference between Selenium and Playwright?
Both tools support browser automation. Playwright provides browser contexts, modern locator APIs, and built-in actionability checks. Selenium remains widely used and supports a broad ecosystem of browser automation integrations.
