Playwright Java Cheat Sheet: Locators, Actions, Assertions, Waiting, Network and CLI

A complete Playwright Java cheat sheet: everything from launching a browser to network mocking and API testing, with the Java method names and options objects you'll actually type. It ends with a one-page quick reference card you can print. For the TypeScript version, see the Playwright cheat sheet.

PLAYWRIGHT (JAVA)

Complete API Reference & Cheat-Sheet

Every locator, action, assertion, option & command in one place

Playwright 1.63 | Java 17 | JUnit 5 & TestNG | Maven & Gradle

Java Bindings vs the TypeScript Test Runner — Read This First

Most Playwright content online uses the TypeScript "Playwright Test" runner. The Java binding is the SAME browser-automation library but does NOT include that runner — you use JUnit 5 or TestNG instead. Knowing this prevents a lot of confusion and is a common interview trap.

Setup & CLI Commands

CLI mainClass is com.microsoft.playwright.CLI — full form:

mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install"

Core Objects — Key Methods

Playwright / BrowserType / Browser

BrowserContext

Locators — Creation

All of these exist on both Page (page.getBy...) and Locator (for scoping inside another locator).

getByRole options

new Page.GetByRoleOptions()
    .setName("Login")        // accessible name (String or Pattern)
    .setExact(true)          // exact name match
    .setChecked(true)        // checkbox/radio state
    .setPressed(true)        // toggle buttons
    .setSelected(true)       // options
    .setExpanded(true)       // expandable widgets
    .setLevel(2)             // heading level h2
    .setDisabled(false);

Refining & combining locators

Selector Engines & Pseudo-Classes

// Configure the test-id attribute name (default: data-testid)
playwright.selectors().setTestIdAttribute("data-qa");

Locator Actions (all auto-wait)

Locator State & Info (no auto-wait)

These return immediately — use for reading data or branching, NOT for assertions (use web-first assertions for those).

Web-First Assertions (auto-retrying)

import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

Locator assertions

Page & APIResponse assertions; negation & timeout

assertThat(page).hasTitle("Swag Labs");
assertThat(page).hasURL(Pattern.compile(".*inventory.*"));
assertThat(apiResponse).isOK();                 // 2xx

// Negation with not()
assertThat(page.getByText("Error")).not().isVisible();

// Per-assertion timeout
assertThat(locator).isVisible(
    new LocatorAssertions.IsVisibleOptions().setTimeout(10000));

// Global assertion timeout
PlaywrightAssertions.setDefaultAssertionTimeout(10000);

Waiting & Timeouts

Page — Advanced APIs

Running JavaScript (the JavascriptExecutor equivalent)

// Return a value from the page
String title = (String) page.evaluate("() => document.title");
int height = (int) page.evaluate("() => document.body.scrollHeight");

// Pass arguments
page.evaluate("([a, b]) => a + b", java.util.List.of(2, 3));

// Operate on a specific element
page.getByTestId("row").evaluate("el => el.scrollIntoView()");

// Run script on EVERY new document (e.g. stub a global before app loads)
page.addInitScript("window.isAutomated = true;");

// Wait until a JS condition holds
page.waitForFunction("() => document.querySelectorAll('.row').length > 10");

Page events (listen to the browser)

// Example: fail the test if the page logs a JS error
page.onPageError(err -> { throw new RuntimeException("JS error: " + err); });
page.onConsoleMessage(msg -> {
    if ("error".equals(msg.type())) System.out.println("Console error: " + msg.text());
});

Emulation, clock & misc

// Dark mode / print media
page.emulateMedia(new Page.EmulateMediaOptions()
    .setColorScheme(ColorScheme.DARK));

// Freeze / control time (clock API)
page.clock().install();
page.clock().setFixedTime(java.time.Instant.parse("2026-01-01T00:00:00Z"));
page.clock().fastForward("30:00");    // advance 30 minutes

page.setViewportSize(1280, 720);
page.addStyleTag(new Page.AddStyleTagOptions().setContent("* {animation:none!important}"));
page.bringToFront();

Keyboard & Mouse

Common keys: Enter, Tab, Escape, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, F1-F12. Modifiers: Control, Shift, Alt, Meta (e.g. "Control+Shift+K").

Options Objects (most-used setters)

LaunchOptions

new BrowserType.LaunchOptions()
    .setHeadless(false).setSlowMo(300)
    .setChannel("chrome")          // chrome / msedge
    .setArgs(List.of("--start-maximized"))
    .setProxy("http://proxy:8080")
    .setDownloadsPath(Paths.get("downloads"))
    .setTracesDir(Paths.get("traces"))
    .setTimeout(30000);

NewContextOptions

new Browser.NewContextOptions()
    .setViewportSize(1920, 1080)
    .setBaseURL("https://site.com")
    .setLocale("en-US").setTimezoneId("Asia/Kolkata")
    .setGeolocation(12.97, 77.59).setPermissions(List.of("geolocation"))
    .setColorScheme(ColorScheme.DARK)
    .setIsMobile(true).setHasTouch(true).setDeviceScaleFactor(2)
    .setUserAgent("...")
    .setHttpCredentials("user", "pass")   // basic auth
    .setOffline(true)
    .setStorageStatePath(Paths.get("auth/state.json"))
    .setRecordVideoDir(Paths.get("videos"))
    .setRecordHarPath(Paths.get("net.har"))
    .setIgnoreHTTPSErrors(true)
    .setExtraHTTPHeaders(Map.of("X-Env", "qa"));

API Testing — APIRequestContext

APIRequestContext api = playwright.request().newContext(
    new APIRequest.NewContextOptions()
        .setBaseURL("https://api.site.com")
        .setExtraHTTPHeaders(Map.of("Authorization", "Bearer " + token)));

Network & Routing

route.fulfill(new Route.FulfillOptions()

.setStatus(200).setContentType("application/json")
.setBody("{\"ok\":true}"));    // or .setPath(file) / .setResponse(apiResp)

TestNG Reference (Selenium-shop favourite)

<!-- testng.xml — parallel across methods with a thread pool -->
<suite name="pw" parallel="methods" thread-count="4">
  <test name="regression">
    <classes><class name="tests.LoginTest"/></classes>
  </test>
</suite>
@DataProvider(name = "logins", parallel = true)
public Object[][] logins() {
    return new Object[][] {{"standard_user","secret_sauce"}, {"locked_out_user","secret_sauce"}};
}
@Test(dataProvider = "logins", retryAnalyzer = Retry.class)
public void login(String u, String p) { ... }

JUnit 5 Reference

# junit-platform.properties — parallel execution
junit.jupiter.execution.parallel.enabled = true
junit.jupiter.execution.parallel.mode.default = concurrent
junit.jupiter.execution.parallel.config.strategy = fixed
junit.jupiter.execution.parallel.config.fixed.parallelism = 4

Maven & Gradle

Maven — run commands

mvn clean test
mvn test -Dbrowser=firefox -Dheadless=true
mvn test -Dgroups=smoke              # JUnit tags via Surefire
mvn test -Dtest=LoginTest#validLogin # single method
mvn test -DsuiteXmlFile=testng.xml   # TestNG suite

Gradle — equivalent setup

// build.gradle
dependencies {
    implementation "com.microsoft.playwright:playwright:1.63.0"
    testImplementation "org.junit.jupiter:junit-jupiter:5.11.3"
}
test {
    useJUnitPlatform()
    systemProperty "browser", System.getProperty("browser", "chromium")
}
// Install browsers:
// gradle -q compileJava; then run the CLI main class, or use a Playwright Gradle exec task

One-Glance Cheat-Sheet

Locator picks (in priority order)

page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Save"))
page.getByLabel("Email")   page.getByPlaceholder("Search")   page.getByText("Products")
page.getByTestId("submit")
page.locator("#id")   page.locator("xpath=//a")   // last resort

Top assertions

assertThat(loc).isVisible();     assertThat(loc).hasText("x");
assertThat(loc).hasCount(3);     assertThat(loc).isEnabled();
assertThat(input).hasValue("x"); assertThat(page).hasURL(pattern);

Handle anything

Dropdown : loc.selectOption("value")

Checkbox : loc.check() / assertThat(loc).isChecked()

Dialog : page.onDialog(d -> d.accept()); // register BEFORE click

Frame : page.frameLocator("#f").getByRole(...)

Tab : Page p = page.waitForPopup(() -> click)

Upload : loc.setInputFiles(Paths.get("f.pdf"))

Download : page.waitForDownload(() -> click).saveAs(path)

Network : page.route("**/api", r -> r.fulfill(...))

JS : page.evaluate("() => document.title")

Trace : context.tracing().start(...) / stop(setPath("t.zip"))

Golden rules

• Prefer getByRole/getByTestId over XPath.
• Use web-first assertThat(...) for UI state; never Thread.sleep().
• One BrowserContext + Page per test; ThreadLocal for parallel.
• storageState() to skip logins; API to seed data.
• Debug failures with the Trace Viewer, not print statements.

Keep this open while you build. 📖

One-Page Quick Reference Card

PLAYWRIGHT (JAVA) — QUICK REFERENCE CARD

Playwright 1.63 | Java 17 | print & pin to your desk

CLI & RUN

BOOT (launch → act → assert)

Playwright pw = Playwright.create();
Browser b = pw.chromium().launch(new LaunchOptions().setHeadless(false));
Page page = b.newContext(new NewContextOptions().setBaseURL(url)).newPage();
page.navigate("/");
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Login")).click();
assertThat(page.getByText("Products")).isVisible();
LOCATORS  (priority: role → label/text → testId → css → xpath)

ACTIONS (all auto-wait)

WEB-FIRST ASSERTIONS (assertThat(...), auto-retry)

WAITING (never Thread.sleep)

HANDLE ANYTHING

FRAMEWORK SKELETON (JUnit 5)

@BeforeAll static  launch browser
@BeforeEach        context = browser.newContext(); page = context.newPage();
@Test              new LoginPage(page).loginAs(u,p); assertThat(...).isVisible();
@AfterEach         context.close();
@AfterAll static   browser.close(); playwright.close();

POM: locators as fields, actions as methods, return next page.

Parallel: ThreadLocal<Page/Context>. Skip login: storageState().

API (built-in)

APIRequestContext api = pw.request().newContext(opts.setBaseURL(base));
APIResponse r = api.post("/users", RequestOptions.create().setData(map));
assertEquals(201, r.status());  JsonNode j = mapper.readTree(r.text());

GOLDEN RULES: getByRole/testId over XPath • web-first assertThat over sleep • one Context+Page per test • debug with traces