1. Introduction
Writing browser automation scripts is easy when an application has only a few pages. However, as an application grows, test scripts can become difficult to maintain. The same locators, login steps, and browser interactions may appear in multiple tests.
The Playwright Java Page Object Model solves this problem by separating page-specific actions from test logic. Instead of writing all browser interactions inside test methods, you create Java classes that represent application pages.
For example, a login page class contains username and password locators, along with methods to enter credentials and submit the form. Test classes use those methods to execute scenarios and verify results.
In this tutorial, you will build a practical Playwright Java POM framework using Java, Maven, Playwright, and JUnit 5. It is designed for freshers, QA automation engineers, SDETs, and Selenium professionals moving to Playwright.
2. What Is Playwright Java Page Object Model?
Page Object Model (POM) is a test automation design pattern in which each application page or reusable UI component is represented by a separate class.
A page class generally contains:
- Locators used to identify web elements.
- Methods for performing page actions.
- Navigation or page-specific behaviour.
- Reusable operations such as login, search, and logout.
Test classes contain the test scenarios and assertions. This separation makes automated test scripts easier to understand and update.
Playwright Java POM architecture
A typical framework follows this structure:
JUnit Test Classes
|
v
Page Object Classes
|
v
Playwright Locators and Actions
|
v
Browser / BrowserContext / Page
|
v
For example, a login test calls loginPage.login() instead of directly locating and filling every input field.
Playwright locators are particularly useful in POM because they support automatic waiting and re-resolve elements when actions are performed. <Cite refs={[“turn454319search1″,”turn454319search6”]}/>
3. Benefits of Playwright Java Page Object Model
| Benefit | Explanation |
| Reusability | Use the same page methods in multiple tests |
| Maintainability | Update a locator in one page class |
| Readability | Test methods describe business scenarios |
| Reduced duplication | Common actions are written once |
| Scalability | Add new page classes as the application grows |
| Collaboration | Team members can work on separate page objects |
Consider a login button used by ten test cases. Without POM, each test may contain its own selector. With POM, the selector is maintained in one class.
If the application’s HTML changes, you can update the locator in the page class instead of modifying every test.
4. Prerequisites and Maven Setup
Install the following tools before creating the framework:
- Java JDK 17 or later.
- Apache Maven.
- IntelliJ IDEA or Eclipse.
- Basic Java and OOP knowledge.
- Basic Playwright knowledge.
Add dependencies to pom.xml
Create a Maven project and configure the following dependencies. The example uses Playwright Java 1.64.0 and JUnit Jupiter 5.11.4.
<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
<modelVersion>4.0.0</modelVersion>
<groupId>com.techsarvam</groupId>
<artifactId>playwright-java-pom</artifactId>
<version>1.0</version>
<properties>
<maven.compiler.release>17</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<junit.version>5.11.4</junit.version>
</properties>
<dependencies>
<dependency>
<groupId>com.microsoft.playwright</groupId>
<artifactId>playwright</artifactId>
<version>1.64.0</version>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.13.0</version>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>3.5.2</version>
</plugin>
</plugins>
</build>
</project>
Install Playwright browser binaries:
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args=”install”
For Linux CI environments, install browser system dependencies too:
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args=”install –with-deps chromium”
5. Recommended Project Folder Structure
A clean folder structure helps separate page objects, tests, configuration, and utilities.
playwright-java-pom/
├── pom.xml
├── src/
│ ├── main/java/com/techsarvam/
│ │ ├── pages/
│ │ │ ├── LoginPage.java
│ │ │ └── SecureAreaPage.java
│ │ ├── components/
│ │ ├── config/
│ │ │ └── Config.java
│ │ └── utilities/
│ │ └── ScreenshotUtil.java
│ └── test/java/com/techsarvam/tests/
│ ├── BaseTest.java
│ └── LoginTest.java
| Folder | Responsibility |
| pages | Page classes and page-specific methods |
| components | Reusable UI components |
| config | Environment and application configuration |
| utilities | Screenshots and common helper methods |
| tests | Test scenarios and assertions |
This structure is suitable for a small project and can be extended as the framework grows.
6. Create Your First Playwright Java Page Class
A page class represents one application page. It receives a Playwright Page object and defines the locators and methods required to interact with that page.
Let’s create a login page class for a sample application.
LoginPage.java
package com.techsarvam.pages;
import com.microsoft.playwright.Page;
public class LoginPage {
private final Page page;
private final String username = “#username”;
private final String password = “#password”;
private final String loginButton = “button[type=’submit’]”;
public LoginPage(Page page) {
this.page = page;
}
public void open(String url) {
page.navigate(url);
}
public void enterUsername(String value) {
page.locator(username).fill(value);
}
public void enterPassword(String value) {
page.locator(password).fill(value);
}
public void clickLogin() {
page.locator(loginButton).click();
}
public void login(String user, String pass) {
enterUsername(user);
enterPassword(pass);
clickLogin();
}
}
Explanation:
- The constructor receives the current browser page.
- Locators identify the username, password, and login button.
- Individual methods perform specific actions.
- The login() method combines those actions into one reusable operation.
The test does not need to know how the login form works internally. It only needs to call the page object’s methods.
7. Implement the Playwright Java POM Framework
Now create a page class for the page displayed after a successful login.
SecureAreaPage.java
package com.techsarvam.pages;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Locator;
public class SecureAreaPage {
private final Page page;
private final Locator heading;
public SecureAreaPage(Page page) {
this.page = page;
this.heading = page.locator(“h2”);
}
public Locator heading() {
return heading;
}
public String getPageTitle() {
return page.title();
}
}
Notice that the page class provides access to the heading locator but does not decide whether the heading is correct. That verification belongs in the test.
This separation keeps page behaviour reusable and test expectations clear.
8. Real-World Login Test Example
Let’s connect the page objects to a JUnit test.
For this example, use the public demo login application:
The sample application provides these test credentials:
- Username: tomsmith
- Password: SuperSecretPassword!
Create BaseTest.java
The base test class manages browser setup and cleanup.
package com.techsarvam.tests;
import com.microsoft.playwright.*;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.AfterEach;
public class BaseTest {
protected Playwright playwright;
protected Browser browser;
protected BrowserContext context;
protected Page page;
@BeforeEach
void setUp() {
playwright = Playwright.create();
browser = playwright.chromium().launch(
new BrowserType.LaunchOptions()
.setHeadless(true)
);
context = browser.newContext();
page = context.newPage();
}
@AfterEach
void tearDown() {
if (context != null) context.close();
if (browser != null) browser.close();
if (playwright != null) playwright.close();
}
}
Each test receives a fresh browser context and page. This helps prevent cookies and session data from affecting other tests.
Create LoginTest.java
package com.techsarvam.tests;
import com.techsarvam.pages.LoginPage;
import com.techsarvam.pages.SecureAreaPage;
import org.junit.jupiter.api.Test;
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
public class LoginTest extends BaseTest {
@Test
void verifySuccessfulLogin() {
LoginPage loginPage = new LoginPage(page);
loginPage.open(
“https://the-internet.herokuapp.com/login”
);
loginPage.login(
“tomsmith”,
“SuperSecretPassword!”
);
SecureAreaPage secureAreaPage =
new SecureAreaPage(page);
assertThat(secureAreaPage.heading())
.hasText(“Secure Area”);
}
}
How this test works:
- JUnit calls setUp() before the test.
- Playwright launches Chromium and creates a new page.
- LoginPage opens the login application.
- The reusable login() method enters the credentials.
- SecureAreaPage represents the destination page.
- The test verifies the heading using a Playwright assertion.
- JUnit calls tearDown() to close browser resources.
Run the framework:
mvn clean test
Expected result: The test passes when the login succeeds and the page heading displays Secure Area. Maven Surefire stores test reports under target/surefire-reports.
Playwright’s web-first assertions retry until the expected condition is met or the timeout expires. This is useful for applications where page content updates asynchronously. <Cite refs={[“turn454319search2”]}/>
9. Advanced POM Features
Once the basic framework works, you can add reusable components, environment configuration, and common utilities.
Reusable components
Some UI elements appear on multiple pages, such as navigation bars, headers, side menus, and footers.
Instead of repeating their locators in several page classes, create component classes.
HeaderComponent.java
package com.techsarvam.components;
import com.microsoft.playwright.Locator;
import com.microsoft.playwright.Page;
public class HeaderComponent {
private final Locator header;
public HeaderComponent(Page page) {
header = page.locator(“header”);
}
public void clickHome() {
header.getByText(“Home”).click();
}
}
A page object can create and reuse this component. This makes the framework easier to maintain when shared UI elements change.
Environment configuration
Avoid hardcoding URLs in every test. Create a configuration class.
Config.java
package com.techsarvam.config;
public class Config {
public static String getBaseUrl() {
return System.getProperty(
“baseUrl”,
“https://the-internet.herokuapp.com”
);
}
}
Update the test to use:
loginPage.open(Config.getBaseUrl() + “/login”);
You can execute tests against another environment:
mvn clean test -DbaseUrl=https://staging.example.com
The system property takes precedence over the default URL.
Screenshot utility
Screenshots are useful when investigating failures.
package com.techsarvam.utilities;
import com.microsoft.playwright.Page;
import java.nio.file.Paths;
public class ScreenshotUtil {
public static void capture(Page page, String fileName) {
page.screenshot(
new Page.ScreenshotOptions()
.setPath(Paths.get(“target/screenshots/” + fileName))
.setFullPage(true)
);
}
}
Create the destination directory before using this utility. You can call it from a test or a failure-handling hook.
10. Reporting and CI/CD Integration
A maintainable Java test automation framework should produce useful execution reports.
Maven reporting
The Maven Surefire plugin executes JUnit tests and generates reports in:
target/surefire-reports/
These reports include test results and failure information. For richer HTML reporting, you can integrate a reporting library such as Allure or configure a Maven reporting plugin.
GitHub Actions example
The following workflow installs Java, installs Chromium and its Linux dependencies, and runs the Maven tests.
.github/workflows/playwright.yml
name: Playwright Java Tests
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
test:
runs-on: ubuntu-latest
steps:
– name: Checkout
uses: actions/checkout@v4
– name: Setup Java
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: ’17’
cache: maven
– name: Install Playwright browsers
run: >
mvn exec:java
-Dexec.mainClass=com.microsoft.playwright.CLI
-Dexec.args=”install –with-deps chromium”
– name: Run tests
run: mvn clean test
– name: Upload test reports
if: always()
uses: actions/upload-artifact@v4
with:
name: junit-reports
path: target/surefire-reports/
For a production pipeline, pin and review GitHub Actions versions according to your organisation’s security policy. Jenkins can use the same Maven commands: install browser dependencies on the agent, execute mvn clean test, and publish Surefire XML reports.
11. Best Practices and Common Mistakes
| Best practice | Why it matters |
| Use role, label, and test ID locators | Makes selectors more stable and readable |
| Keep assertions in tests | Separates verification from page behaviour |
| Use reusable page methods | Reduces duplicate actions |
| Create isolated contexts | Prevents session interference |
| Avoid fixed sleeps | Reduces slow and flaky tests |
| Keep configuration external | Supports multiple environments |
| Close browser resources | Prevents resource leaks |
| Avoid oversized page classes | Keeps responsibilities clear |
Common mistakes include putting every test scenario into one page class, creating duplicate locators across tests, using long XPath expressions, and sharing browser state between unrelated tests.
Do not create a page class for every tiny element. Use component classes for genuinely reusable UI sections, and keep the framework simple until the project needs additional layers.
For more architecture guidance, read the Playwright Framework Design guide.
12. Playwright Java POM Interview Questions and FAQs
Practical interview questions
1. What is Page Object Model in Playwright Java?
It is a design pattern where application pages are represented by Java classes containing locators and reusable page actions.
2. What is the main benefit of POM?
It improves maintainability and reusability by separating page interactions from test scenarios.
3. Should assertions be written inside page classes?
Usually, test-specific assertions belong in test classes. Page classes should expose locators or page information and provide reusable actions.
4. What is the role of the Page class in Playwright?
Page represents a browser tab or page and provides methods to navigate, locate elements, and interact with the application.
5. Why use a BaseTest class?
It centralises browser setup and cleanup so test classes do not repeat lifecycle code.
6. What is a reusable component in POM?
It is a class representing a UI section shared across pages, such as a header, navigation bar, or menu.
7. How do you run Playwright Java POM tests?
Use a Java test runner such as JUnit or TestNG and execute the Maven tests with mvn clean test.
Frequently asked questions
What is Playwright Java Page Object Model?
It is a framework design approach that uses Java page classes to store locators and reusable actions while test classes manage scenarios and assertions.
What are the benefits of Playwright Java Page Object Model?
The main benefits are code reusability, readability, reduced duplication, easier maintenance, and better support for growing automation suites.
How do I get started with Playwright Java Page Object Model?
Install Java and Maven, add the Playwright dependency, configure JUnit or TestNG, create a page class, and write a test that uses its methods. Start with a login scenario before adding reusable components and reporting.
