<!-- playwright-java: single artifact, bundles the Node.js runtime -->
<dependency>
    <groupId>com.microsoft.playwright</groupId>
    <artifactId>playwright</artifactId>
    <version>1.44.0</version>
</dependency>

<!-- TestNG for test runner (or use JUnit 5 — see section 15) -->
<dependency>
    <groupId>org.testng</groupId>
    <artifactId>testng</artifactId>
    <version>7.9.0</version>
    <scope>test</scope>
</dependency>

<!-- AssertJ for fluent non-Playwright assertions (optional) -->
<dependency>
    <groupId>org.assertj</groupId>
    <artifactId>assertj-core</artifactId>
    <version>3.25.3</version>
    <scope>test</scope>
</dependency>

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.2.5</version>
    <configuration>
        <!-- Point to TestNG XML for suite/parallel config -->
        <suiteXmlFiles>
            <suiteXmlFile>testng.xml</suiteXmlFile>
        </suiteXmlFiles>
    </configuration>
</plugin>

dependencies {
    testImplementation 'com.microsoft.playwright:playwright:1.44.0'
    testImplementation 'org.testng:testng:7.9.0'
}

test {
    useTestNG() // tell Gradle to run via TestNG
}

# Via Maven exec plugin:
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="install"

# Install only Chromium (smaller CI footprint):
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="install chromium"

# With system dependencies (needed on Ubuntu CI images):
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="install --with-deps"

my-playwright-project/
├── pom.xml
├── testng.xml                  ← suite configuration
└── src/
    ├── main/java/
    │   └── com/example/
    │       └── pages/          ← Page Object classes
    │           ├── BasePage.java
    │           ├── LoginPage.java
    │           └── DashboardPage.java
    └── test/java/
        └── com/example/
            ├── base/
            │   └── BaseTest.java   ← Playwright setup/teardown
            ├── tests/
            │   ├── LoginTest.java
            │   └── DashboardTest.java
            └── utils/
                └── TestUtils.java

import com.microsoft.playwright.*;
import com.microsoft.playwright.options.*;

public class HelloPlaywright {
    public static void main(String[] args) {

        // try-with-resources auto-closes Playwright (and all children)
        try (Playwright playwright = Playwright.create()) {

            // Launch Chromium in headless mode (default)
            Browser browser = playwright.chromium().launch();

            // Create an isolated browsing session
            BrowserContext context = browser.newContext();

            // Open a new tab
            Page page = context.newPage();

            // Navigate to URL — blocks until navigation completes
            page.navigate("https://playwright.dev");

            // Print page title
            System.out.println(page.title());
            // → "Fast and reliable end-to-end testing..."

            // Close in reverse order (though try-with-resources handles this)
            context.close();
            browser.close();
        } // Playwright.close() called here automatically
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE suite SYSTEM "http://testng.org/testng-1.0.dtd">
<suite name="Playwright Suite"
       parallel="tests"    <!-- each <test> runs in its own thread -->
       thread-count="4">

    <test name="Chrome Tests">
        <parameter name="browser" value="chromium"/>
        <classes>
            <class name="com.example.tests.LoginTest"/>
            <class name="com.example.tests.DashboardTest"/>
        </classes>
    </test>

    <test name="Firefox Tests">
        <parameter name="browser" value="firefox"/>
        <classes>
            <class name="com.example.tests.LoginTest"/>
        </classes>
    </test>
</suite>

// Interface: com.microsoft.playwright.Playwright
// Implements: AutoCloseable

Playwright pw = Playwright.create();        // spawns Node.js process
Playwright pw2 = Playwright.create(
    new Playwright.CreateOptions()
        .setEnv(Map.of("PLAYWRIGHT_BROWSERS_PATH", "/custom/path"))
);

// Access browser types:
BrowserType chromium = pw.chromium();   // Chromium-based
BrowserType firefox  = pw.firefox();    // Gecko engine
BrowserType webkit   = pw.webkit();     // WebKit (Safari engine)

pw.close();  // kills Node process, closes all browsers

Browser.NewContextOptions ctxOptions = new Browser.NewContextOptions()
    // ── Viewport ──────────────────────────────────────────────────
    .setViewportSize(1920, 1080)      // set browser window size
    .setViewportSize(null)             // null = no viewport (real browser size)

    // ── Auth: Basic HTTP ──────────────────────────────────────────
    .setHttpCredentials("user", "pass") // for HTTP Basic Auth popups

    // ── Ignore HTTPS errors ────────────────────────────────────────
    .setIgnoreHTTPSErrors(true)         // ignore SSL cert errors

    // ── Locale / Timezone ──────────────────────────────────────────
    .setLocale("en-US")
    .setTimezoneId("America/New_York")

    // ── Geolocation ───────────────────────────────────────────────
    .setGeolocation(new Geolocation(40.7128, -74.0060)) // NYC
    .setPermissions(List.of("geolocation"))

    // ── User Agent ────────────────────────────────────────────────
    .setUserAgent("Mozilla/5.0 (custom bot)")

    // ── Record Video ─────────────────────────────────────────────
    .setRecordVideoDir(Paths.get("videos/"))
    .setRecordVideoSize(1280, 720)

    // ── Load saved auth state ─────────────────────────────────────
    .setStorageStatePath(Paths.get("auth.json")) // reuse login session

    // ── Extra HTTP headers for all requests ───────────────────────
    .setExtraHTTPHeaders(Map.of("X-Test-Header", "playwright"));

BrowserContext context = browser.newContext(ctxOptions);

// Create multiple pages in same context (share cookies/storage)
Page page1 = context.newPage();
Page page2 = context.newPage();

// List all pages in this context
List<Page> pages = context.pages();

// Cookie management
context.addCookies(List.of(
    new Cookie("session_id", "abc123")
        .setDomain("example.com")
        .setPath("/")
        .setHttpOnly(true)
));
List<Cookie> cookies = context.cookies("https://example.com");
context.clearCookies();

// Save storage state (cookies + localStorage) for auth reuse
context.storageState(new BrowserContext.StorageStateOptions()
    .setPath(Paths.get("auth.json")));

// Set default navigation timeout for all pages in this context
context.setDefaultNavigationTimeout(30000);
context.setDefaultTimeout(10000);        // all other timeouts

// ── Basic navigate ────────────────────────────────────────────
page.navigate("https://example.com");

// ── With options ──────────────────────────────────────────────
page.navigate("https://example.com", new Page.NavigateOptions()
    .setTimeout(60000)        // override default 30s timeout
    .setWaitUntil(WaitUntilState.NETWORKIDLE)
    // WaitUntilState options:
    // COMMIT     → wait for network response received (fastest)
    // DOMCONTENTLOADED → HTML parsed, scripts not yet loaded
    // LOAD       → all resources loaded (default)
    // NETWORKIDLE → no network requests for 500ms (slowest, fragile)
);

// ── Browser history ───────────────────────────────────────────
page.goBack();                              // like pressing browser Back
page.goBack(new Page.GoBackOptions().setTimeout(5000));
page.goForward();
page.reload();
page.reload(new Page.ReloadOptions().setWaitUntil(WaitUntilState.DOMCONTENTLOADED));

// URL and title
String url   = page.url();          // current URL
String title = page.title();       // <title> tag content
boolean closed = page.isClosed();  // has page been closed?

// Full page HTML content
String html = page.content();      // returns full HTML string

// Set HTML directly (great for testing static HTML)
page.setContent("<h1>Hello</h1>");
page.setContent(htmlString, new Page.SetContentOptions()
    .setWaitUntil(WaitUntilState.LOAD));

// Viewport
page.setViewportSize(1280, 720);
ViewportSize vp = page.viewportSize();
System.out.println(vp.width + "x" + vp.height);

// Close this tab (not the browser)
page.close();

// The BrowserContext this page belongs to
BrowserContext ctx = page.context();

// evaluate() — runs JS, returns a serializable Java value
Object result = page.evaluate("() => document.title");
String title = (String) result;

// Pass arguments to the JS function
Object sum = page.evaluate("([a, b]) => a + b", Arrays.asList(3, 4));
// → 7

// evaluateHandle() — returns a JSHandle (reference to JS object in page)
// Use when the return value is not serializable (DOM node, complex object)
JSHandle handle = page.evaluateHandle("() => window");

// Get an ElementHandle from evaluateHandle
ElementHandle el = (ElementHandle) page.evaluateHandle(
    "() => document.querySelector('#submit-btn')"
);

// addScriptTag() — inject a script file or content into the page
page.addScriptTag(new Page.AddScriptTagOptions()
    .setContent("window.myHelper = () => 'hello';")
);
page.addScriptTag(new Page.AddScriptTagOptions()
    .setUrl("https://cdn.example.com/script.js")
);

// addInitScript() — runs BEFORE page loads (on every navigation)
// Perfect for mocking APIs before page code runs
page.addInitScript("Object.defineProperty(navigator, 'webdriver', {get: () => false})");

// Expose a Java function to the page's JavaScript context
page.exposeFunction("sha256", args -> {
    // args is Object[] from JS, return value goes back to JS
    return computeHash((String) args[0]);
});

// Console messages from the page (console.log, .error, etc.)
page.onConsoleMessage(msg -> {
    System.out.println("CONSOLE [" + msg.type() + "] " + msg.text());
    // msg.type() → "log", "warn", "error", "debug", "info"
});

// Uncaught JS errors in the page
page.onPageError(error -> {
    System.err.println("JS Error: " + error.message());
});

// New page opened (popup or window.open)
page.onPopup(popup -> {
    popup.waitForLoadState();
    System.out.println("New page: " + popup.url());
});

// Download events
page.onDownload(download -> {
    Path savedPath = download.saveAs(Paths.get("downloads/" + download.suggestedFilename()));
});

// Network request/response events
page.onRequest(req  -> System.out.println("→ " + req.url()));
page.onResponse(res -> System.out.println("← " + res.status() + " " + res.url()));

// Wait for navigation to complete (use AFTER triggering navigation)
page.waitForNavigation(() -> {
    page.click("#submit");  // action that triggers navigation
});

// With options:
page.waitForNavigation(new Page.WaitForNavigationOptions()
    .setWaitUntil(WaitUntilState.NETWORKIDLE)
    .setUrl("**/dashboard**"),   // glob pattern — wait for this URL
    () -> page.click("#login-btn")
);

// Wait for URL to match (simpler than waitForNavigation)
page.waitForURL("**/dashboard");
page.waitForURL(Pattern.compile("https://example.com/user/\\d+"));

// Wait for load state (DOMContentLoaded, load, networkidle)
page.waitForLoadState();                        // default: LOAD
page.waitForLoadState(LoadState.DOMCONTENTLOADED);
page.waitForLoadState(LoadState.NETWORKIDLE);

// Wait for a custom JS condition to be truthy
page.waitForFunction("() => window.myApp.loaded === true");
page.waitForFunction("selector => !!document.querySelector(selector)",
    "#dynamic-content");

// Wait for a network request matching pattern
Request req = page.waitForRequest("**/api/users", () -> {
    page.click("#load-users");
});

// Wait for a network response
Response resp = page.waitForResponse("**/api/data", () -> {
    page.click("#fetch-data");
});
System.out.println(resp.status()); // 200

// Basic CSS — same syntax as document.querySelector
Locator btn    = page.locator("button");
Locator byId   = page.locator("#submit-btn");
Locator byClass = page.locator(".primary-btn");
Locator byAttr = page.locator("input[type='email']");
Locator child  = page.locator("form .submit-row button");

// Playwright CSS extensions (not in standard CSS)
// :has() — element that contains another
Locator rowWithCheck = page.locator("tr:has(input[type='checkbox']:checked)");

// :has-text() — element containing specific text
Locator deleteBtn = page.locator("button:has-text('Delete')");

// :text() — shorthand for text content match
Locator saveBtn = page.locator(":text('Save Changes')");

// :text-is() — exact text match
Locator exactBtn = page.locator(":text-is('Save')"); // won't match "Save Changes"

// :visible — only visible elements
Locator visible = page.locator("button:visible");

// :nth-match() — pick nth element from selector group (1-indexed)
Locator second = page.locator(":nth-match(.item, 2)");

// Prefix with "xpath=" to use XPath syntax
Locator byXpath = page.locator("xpath=//button[@id='submit']");
Locator byText  = page.locator("xpath=//button[contains(text(),'Login')]");
Locator parent  = page.locator("xpath=//input[@name='email']/ancestor::form");

// XPath shorthand (no prefix needed if starts with //)
Locator shortXp = page.locator("//div[@class='container']//button");

// AVOID overly brittle XPath like:
// /html/body/div[1]/div[2]/button[3]  ← breaks on DOM changes

// page.getByRole(AriaRole, options)
// AriaRole mirrors ARIA roles: BUTTON, LINK, HEADING, CHECKBOX, etc.

Locator submitBtn = page.getByRole(AriaRole.BUTTON,
    new Page.GetByRoleOptions().setName("Submit"));
    // matches: <button>Submit</button> or <button aria-label="Submit">

Locator nav = page.getByRole(AriaRole.NAVIGATION);

Locator link = page.getByRole(AriaRole.LINK,
    new Page.GetByRoleOptions().setName("Home"));

Locator exactHeading = page.getByRole(AriaRole.HEADING,
    new Page.GetByRoleOptions()
        .setName("Sign in")
        .setExact(true)        // exact match (case-sensitive)
        .setLevel(1));         // h1 only

// Common ARIA roles:
// BUTTON, LINK, CHECKBOX, RADIO, TEXTBOX, COMBOBOX
// HEADING, BANNER, NAVIGATION, MAIN, DIALOG
// LIST, LISTITEM, TABLE, ROW, CELL
// MENUITEM, TAB, TABPANEL, OPTION

// getByText() — matches visible text content (substring by default)
Locator msg     = page.getByText("Welcome back");
Locator exact   = page.getByText("Sign in", new Page.GetByTextOptions().setExact(true));
Locator byRegex = page.getByText(Pattern.compile("Welcome.*"));

// getByLabel() — finds form input associated with a <label>
// Works with: for/id association, aria-label, aria-labelledby, wrapper label
Locator email = page.getByLabel("Email address");
Locator pwd   = page.getByLabel("Password");
email.fill("[email protected]");

// getByPlaceholder() — match by placeholder attribute
Locator search = page.getByPlaceholder("Search products...");

// getByAltText() — for <img alt="...">
Locator logo = page.getByAltText("Company Logo");

// HTML: <button data-testid="submit-order">Place Order</button>
Locator orderBtn = page.getByTestId("submit-order");

// Default test ID attribute is "data-testid"
// Change it globally in BrowserContext options:
BrowserContext ctx = browser.newContext(new Browser.NewContextOptions()
    .setTestIdAttribute("data-cy")  // for Cypress-style test IDs
);

// Find all rows, then filter to only those containing "John"
Locator johnRow = page.getByRole(AriaRole.ROW)
    .filter(new Locator.FilterOptions().setHasText("John"));

// Filter by contained locator (has another element inside)
Locator checkedItems = page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHas(page.getByRole(AriaRole.CHECKBOX,
            new Page.GetByRoleOptions().setChecked(true))));

// Combine: items containing text "Active" AND having a checked checkbox
Locator activeChecked = page.locator(".item")
    .filter(new Locator.FilterOptions().setHasText("Active"))
    .filter(new Locator.FilterOptions()
        .setHas(page.locator("input:checked")));

// Find a button WITHIN a specific form (scoped search)
Locator form      = page.locator("#login-form");
Locator submitBtn = form.locator("button[type='submit']");
// ↑ Only searches within #login-form, not entire page

// Find a row and then a cell within that row
Locator row      = page.getByRole(AriaRole.ROW).nth(1);
Locator nameCell = row.getByRole(AriaRole.CELL).first();

// and() — additional constraints on same element
Locator visibleBtn = page.getByRole(AriaRole.BUTTON)
    .and(page.locator(":visible"));

Locator items = page.locator(".product-card");

// first(), last(), nth(index) — 0-based index
Locator first  = items.first();
Locator last   = items.last();
Locator third  = items.nth(2);  // 0-indexed, so 2 = third item

// Count matched elements
int count = items.count();

// Iterate over all matched elements
for (int i = 0; i < items.count(); i++) {
    String text = items.nth(i).innerText();
    System.out.println("Item " + i + ": " + text);
}

Locator btn = page.locator("#submit");

// Basic click (left click, single)
btn.click();

// Click with options
btn.click(new Locator.ClickOptions()
    .setButton(MouseButton.RIGHT)    // RIGHT, MIDDLE, or LEFT (default)
    .setClickCount(2)              // double click via click count
    .setDelay(100)                  // ms delay between mousedown/mouseup
    .setPosition(new Position(10, 20)) // click at offset from element top-left
    .setModifiers(List.of(KeyboardModifier.SHIFT)) // Shift+click
    .setForce(true)                // skip actionability checks (use carefully!)
    .setTimeout(5000));             // override wait timeout

// Dedicated methods for common click types
btn.dblclick();                    // double click
btn.dblclick(new Locator.DblclickOptions().setDelay(50));

page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Context Menu"))
    .click(new Locator.ClickOptions().setButton(MouseButton.RIGHT)); // right-click

// tap() — for touch/mobile scenarios
btn.tap();

Locator emailInput = page.getByLabel("Email");

// fill() — atomic: clears then sets value using native input events
emailInput.fill("[email protected]");
emailInput.fill("");   // clear the field

// pressSequentially() — simulates real keystroke by keystroke
// Good for autocomplete, masked inputs, key listeners
emailInput.pressSequentially("[email protected]",
    new Locator.PressSequentiallyOptions().setDelay(50));  // 50ms between keys

// clear() — clears the input field
emailInput.clear();

// inputValue() — get current value of input/textarea/select
String currentVal = emailInput.inputValue();

// Getting text content
String innerText  = page.locator("h1").innerText();   // visible text
String innerHTML  = page.locator("div").innerHTML();  // HTML content
String textContent = page.locator("p").textContent(); // all text including hidden

// getAttribute() — read any attribute
String href = page.locator("a.logo").getAttribute("href");

// press() on a locator — press key while element is focused
page.getByRole(AriaRole.TEXTBOX).press("Enter");
page.locator("input").press("Tab");            // move to next field
page.locator("input").press("Control+A");    // select all
page.locator("input").press("Control+C");    // copy
page.locator("input").press("Backspace");     // delete last char
page.locator("input").press("Escape");       // dismiss
page.locator("input").press("ArrowDown");    // navigate list

// page.keyboard — low-level keyboard control
page.keyboard().press("F5");              // refresh page
page.keyboard().press("Control+Shift+I"); // DevTools
page.keyboard().down("Shift");           // hold Shift
page.keyboard().press("ArrowRight");      // while Shift held
page.keyboard().up("Shift");             // release Shift
page.keyboard().type("Hello World");     // type text (focused element)

// Key names (Playwright follows DOM KeyboardEvent.key convention):
// Single chars: "a", "A", "1", "@"
// Special: "Enter", "Tab", "Escape", "Space", "Backspace", "Delete"
// Arrows: "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"
// Function: "F1" - "F12"
// Modifiers: "Control", "Shift", "Alt", "Meta" (Cmd on Mac)
// Combinations: "Control+A", "Shift+Tab", "Meta+Enter"

// hover() — move mouse over element (triggers :hover CSS, tooltip, etc.)
page.locator(".menu-item").hover();
page.locator("#tooltip-trigger").hover(new Locator.HoverOptions()
    .setPosition(new Position(5, 5))  // hover at offset
    .setForce(true));                 // skip actionability checks

// focus() / blur() — programmatically focus/unfocus an element
page.locator("input[name='email']").focus();
page.locator("input[name='email']").blur();  // triggers blur/focusout events

// Scroll into view
page.locator("#footer-section").scrollIntoViewIfNeeded();

// page.mouse — low-level mouse control
page.mouse().move(400, 300);     // move to (x, y)
page.mouse().down();              // press left button
page.mouse().up();                // release
page.mouse().wheel(0, 300);       // scroll down 300px
page.mouse().click(400, 300);    // click at absolute coords

// Method 1: dragTo() — simplest, drag one locator to another
Locator source = page.locator("#drag-item");
Locator target = page.locator("#drop-zone");
source.dragTo(target);

// With options:
source.dragTo(target, new Locator.DragToOptions()
    .setSourcePosition(new Position(10, 10))   // grab point on source
    .setTargetPosition(new Position(20, 20))   // drop point on target
    .setForce(true));                           // skip actionability checks

// Method 2: Manual drag using page.mouse (for complex DnD libraries)
BoundingBox srcBox = source.boundingBox();  // get element coordinates
BoundingBox tgtBox = target.boundingBox();
page.mouse().move(srcBox.x + srcBox.width/2, srcBox.y + srcBox.height/2);
page.mouse().down();
// Slow move — triggers dragover events
page.mouse().move(tgtBox.x + tgtBox.width/2, tgtBox.y + tgtBox.height/2,
    new Mouse.MoveOptions().setSteps(10));  // move in 10 steps (smooth)
page.mouse().up();

// ── Checkboxes ────────────────────────────────────────────────
Locator checkbox = page.getByRole(AriaRole.CHECKBOX,
    new Page.GetByRoleOptions().setName("Terms and Conditions"));
checkbox.check();           // check (no-op if already checked)
checkbox.uncheck();         // uncheck (no-op if already unchecked)
checkbox.setChecked(true); // set to specific state
boolean checked = checkbox.isChecked();

// ── Select / Dropdown ─────────────────────────────────────────
Locator dropdown = page.locator("select#country");

// Select by value attribute
dropdown.selectOption("US");

// Select by visible label text
dropdown.selectOption(new SelectOption().setLabel("United States"));

// Select by index (0-based)
dropdown.selectOption(new SelectOption().setIndex(2));

// Select multiple options (for multi-select)
dropdown.selectOption(new String[]{ "US", "CA", "GB" });

// Get selected value(s)
List<String> selected = dropdown.inputValue() != null
    ? List.of(dropdown.inputValue()) : List.of();

// Method 1: setInputFiles() — directly set on <input type="file">
page.locator("input[type='file']").setInputFiles(Paths.get("test-files/invoice.pdf"));

// Multiple files
page.locator("input[type='file']").setInputFiles(new Path[] {
    Paths.get("file1.jpg"),
    Paths.get("file2.jpg")
});

// Upload from byte array (when file is in memory, not disk)
page.locator("input[type='file']").setInputFiles(new FilePayload(
    "test.txt",              // filename
    "text/plain",            // mimeType
    "File content here".getBytes()
));

// Clear file input
page.locator("input[type='file']").setInputFiles(new Path[0]);

// Method 2: Use filechooser event for hidden file inputs
FileChooser fileChooser = page.waitForFileChooser(() -> {
    page.getByText("Upload Document").click();
});
fileChooser.setFiles(Paths.get("document.pdf"));

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

Locator btn = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Submit"));

// ── Visibility ────────────────────────────────────────────────
assertThat(btn).isVisible();          // element is visible in DOM
assertThat(btn).isHidden();           // element is not visible (hidden or not in DOM)
assertThat(btn).isAttached();         // element exists in DOM (may be hidden)
assertThat(btn).not().isVisible();   // negation: NOT visible

// ── Enabled/Disabled State ────────────────────────────────────
assertThat(btn).isEnabled();          // not disabled
assertThat(btn).isDisabled();         // has disabled attribute
assertThat(btn).isEditable();         // input/textarea not readonly

// ── Text Content ──────────────────────────────────────────────
assertThat(page.locator("h1")).hasText("Welcome");
// hasText: normalizes whitespace, substring match on single element

assertThat(page.locator("h1")).hasText(Pattern.compile("Welc.*")); // regex

assertThat(page.locator("p.intro")).containsText("hello");
// containsText: substring match (vs hasText which is full match for single)

// For a locator matching MULTIPLE elements, pass an array:
assertThat(page.locator(".todo-item")).hasText(new String[] {
    "Buy groceries", "Walk dog", "Read book"
}); // asserts all 3 items in order

assertThat(page.locator(".tag")).containsText(new String[] { "Java", "UI" });

// ── Form Values ───────────────────────────────────────────────
assertThat(page.getByLabel("Email")).hasValue("[email protected]");
assertThat(page.getByLabel("Email")).hasValue(Pattern.compile(".*@.*\\.com"));

// For multi-select, checkbox groups:
assertThat(page.locator("select#size")).hasValues(new String[] { "M", "L" });

// ── Checkbox state ────────────────────────────────────────────
assertThat(page.getByRole(AriaRole.CHECKBOX)).isChecked();
assertThat(page.getByRole(AriaRole.CHECKBOX)).not().isChecked();

// ── Count ─────────────────────────────────────────────────────
assertThat(page.locator(".product-card")).hasCount(6);
assertThat(page.locator(".error-msg")).hasCount(0); // assert none exist

// ── Attributes & CSS ──────────────────────────────────────────
assertThat(page.locator("a.home")).hasAttribute("href", "/home");
assertThat(page.locator("a.home")).hasAttribute("href", Pattern.compile(".*home.*"));

assertThat(page.locator("button.danger")).hasClass("btn btn-danger");
assertThat(page.locator("div")).hasCSS("display", "flex");
assertThat(page.locator("p")).hasCSS("color", "rgb(255, 0, 0)");

// URL assertions — most commonly needed after navigation
assertThat(page).hasURL("https://example.com/dashboard");
assertThat(page).hasURL(Pattern.compile(".*dashboard.*"));
assertThat(page).hasURL("**/dashboard");  // glob pattern

// Title assertion
assertThat(page).hasTitle("My App — Dashboard");
assertThat(page).hasTitle(Pattern.compile(".*Dashboard.*"));

APIResponse response = page.request().get("https://api.example.com/users");
assertThat(response).isOK();           // status code 200-299
assertThat(response).hasStatus(200);   // exact status code
assertThat(response).hasURL("**/users");
assertThat(response).hasHeader("content-type", "application/json");

// Change timeout for one assertion (default: 5000ms)
assertThat(page.locator("#spinner")).isHidden(
    new LocatorAssertions.IsHiddenOptions().setTimeout(15000)
);

// Change global assertion timeout (affects all assertThat calls)
PlaywrightAssertions.setDefaultAssertionTimeout(10000); // 10 seconds

import com.microsoft.playwright.assertions.SoftAssertions;

@Test
public void validateOrderSummaryPage() {
    page.navigate("https://shop.example.com/order/12345");

    // Create soft assertions scoped to this test
    SoftAssertions softly = SoftAssertions.create();

    // All of these run even if one fails
    softly.assertThat(page).hasTitle("Order #12345");
    softly.assertThat(page.locator(".order-status")).hasText("Confirmed");
    softly.assertThat(page.locator(".item-count")).hasText("3 items");
    softly.assertThat(page.locator(".total-price")).hasText("$149.99");
    softly.assertThat(page.locator("#shipping-address")).isVisible();
    softly.assertThat(page.locator("#tracking-number")).isVisible();

    // assertAll() throws with ALL failures aggregated if any failed
    softly.assertAll();
    // Error message lists EVERY failed assertion, not just the first
}

// DOMCONTENTLOADED → HTML parsed, sync scripts run, deferred scripts queued
// LOAD             → all resources (images, scripts) fetched (default)
// NETWORKIDLE      → no network activity for 500ms (use with caution)

page.navigate("https://app.example.com");
page.waitForLoadState(LoadState.NETWORKIDLE); // wait for SPA to finish loading

// After a click that triggers async content load:
page.locator("#load-more").click();
page.waitForLoadState(LoadState.DOMCONTENTLOADED);

// Frame-level wait:
page.frameLocator("#my-iframe").locator("body").waitFor();

// Wait for element to appear (default state = VISIBLE)
page.locator("#success-message").waitFor();

// Wait for specific state:
page.locator("#spinner").waitFor(
    new Locator.WaitForOptions()
        .setState(WaitForSelectorState.HIDDEN)  // wait to disappear
        .setTimeout(10000)
);
// WaitForSelectorState options:
// ATTACHED  — element in DOM (may be hidden)
// DETACHED  — element removed from DOM
// VISIBLE   — element visible (default)
// HIDDEN    — element not visible or not in DOM

// Equivalent using assertThat (preferred — gives better error messages):
assertThat(page.locator("#spinner")).isHidden(
    new LocatorAssertions.IsHiddenOptions().setTimeout(10000));

// Wait for a specific API call to complete, then act on the response
Response apiResp = page.waitForResponse(
    resp -> resp.url().contains("/api/checkout") && resp.status() == 200,
    () -> page.locator("#checkout-btn").click()   // action that triggers request
);
// Parse response body as JSON
JsonObject body = apiResp.json().getAsJsonObject();

// Simpler form with glob URL pattern:
Response r = page.waitForResponse("**/api/checkout", () -> {
    page.locator("#checkout-btn").click();
});

// Wait for request to be SENT (not response received):
Request req = page.waitForRequest("**/api/search*", () -> {
    page.getByPlaceholder("Search...").fill("playwright");
    page.keyboard().press("Enter");
});
// Inspect what was sent:
System.out.println(req.url());           // URL with query params
System.out.println(req.postData());      // POST body (if any)

// Wait until a JavaScript expression returns truthy
// Playwright polls this every 100ms until truthy or timeout
page.waitForFunction("() => window.appReady === true");

// With timeout:
page.waitForFunction("() => document.querySelectorAll('.item').length > 5",
    null, new Page.WaitForFunctionOptions()
        .setTimeout(15000)
        .setPollingInterval(500)  // check every 500ms (default: raf = every animation frame)
);

// Pass a Java value as argument to JS:
page.waitForFunction("(count) => document.querySelectorAll('.row').length >= count", 10);

// ── Block all image requests (speed up tests) ──────────────────
page.route("**/*.{png,jpg,jpeg,gif,webp,svg}", route -> route.abort());

// ── Mock a specific API endpoint ──────────────────────────────
page.route("**/api/users", route -> {
    route.fulfill(new Route.FulfillOptions()
        .setStatus(200)
        .setContentType("application/json")
        .setBody("""
            [
              {"id": 1, "name": "Alice", "role": "admin"},
              {"id": 2, "name": "Bob",   "role": "user"}
            ]
            """)
    );
});
page.navigate("https://app.example.com");
// → page receives mocked user data, not real API response

// ── Modify an outgoing request (add auth header) ──────────────
page.route("**/api/**", route -> {
    Map<String, String> headers = new HashMap<>(route.request().headers());
    headers.put("Authorization", "Bearer test-token");
    route.continue(new Route.ContinueOptions().setHeaders(headers));
});

// ── Simulate error response ───────────────────────────────────
page.route("**/api/payment", route -> {
    route.fulfill(new Route.FulfillOptions()
        .setStatus(503)
        .setBody("{\"error\": \"Service Unavailable\"}")
    );
});

// ── Simulate network failure ──────────────────────────────────
page.route("**/api/slow-endpoint", route -> route.abort("connectionreset"));
// abort() error types: "aborted", "accessdenied", "connectionclosed",
//   "connectionfailed", "connectionrefused", "connectionreset",
//   "failed", "timedout"

// Fetch from real server, then modify the response
page.route("**/api/products", route -> {
    // Let the real request go through
    APIResponse realResponse = route.fetch();

    // Parse JSON
    String body = realResponse.text();

    // Modify it (e.g., inject a test product)
    String modified = body.replace("]",
        ",{\"id\":9999,\"name\":\"Test Product\",\"price\":0}]");

    // Return modified response
    route.fulfill(new Route.FulfillOptions()
        .setResponse(realResponse)   // inherit status/headers from real
        .setBody(modified)            // but override body
    );
});

// Remove a route handler
Consumer<Route> handler = route -> route.continue();
page.route("**/api/**", handler);
page.unroute("**/api/**", handler);  // remove specific handler
page.unrouteAll();                     // remove all routes

// Route once (fires only for the next matching request)
page.routeOnce("**/api/login", route -> {
    route.fulfill(new Route.FulfillOptions().setStatus(401));
});

// Apply to all pages in this context
context.route("**/api/**", route -> {
    Map<String, String> headers = new HashMap<>(route.request().headers());
    headers.put("X-Test-Mode", "true");
    route.continue(new Route.ContinueOptions().setHeaders(headers));
});

// Block all analytics/tracking (good base for all tests)
context.route("**/{analytics,tracking,telemetry}/**", route -> route.abort());

// Get APIRequestContext from page (shares cookies/auth with browser)
APIRequestContext api = page.request();

// Or create standalone context (no browser needed)
APIRequestContext standaloneApi = playwright.request().newContext(
    new APIRequest.NewContextOptions()
        .setBaseURL("https://api.example.com")
        .setExtraHTTPHeaders(Map.of(
            "Authorization", "Bearer " + token,
            "Accept", "application/json"
        ))
);

// ── GET request ───────────────────────────────────────────────
APIResponse getResp = standaloneApi.get("/users");
assertThat(getResp).isOK();
String body = getResp.text();

// ── POST request ──────────────────────────────────────────────
APIResponse postResp = standaloneApi.post("/users",
    RequestOptions.create()
        .setData(Map.of("name", "Alice", "email", "[email protected]"))
);
assertThat(postResp).hasStatus(201);

// ── PUT / PATCH / DELETE ──────────────────────────────────────
standaloneApi.put("/users/1", RequestOptions.create().setData(Map.of("name", "Bob")));
standaloneApi.patch("/users/1", RequestOptions.create().setData(Map.of("role", "admin")));
standaloneApi.delete("/users/1");

// ── Query parameters ──────────────────────────────────────────
APIResponse filtered = standaloneApi.get("/products",
    RequestOptions.create()
        .setQueryParam("category", "electronics")
        .setQueryParam("page", 1)
);
// → GET /products?category=electronics&page=1

// ── File upload via API ────────────────────────────────────────
standaloneApi.post("/upload",
    RequestOptions.create().setMultipart(
        FormData.create()
            .append("file", Paths.get("test.pdf"))
            .append("description", "Test document")
    )
);

standaloneApi.dispose(); // clean up the context

// ── Basic iframe access ────────────────────────────────────────
// HTML: <iframe id="payment-frame" src="https://payment.example.com">
FrameLocator payFrame = page.frameLocator("#payment-frame");

// Now interact with elements INSIDE the iframe:
payFrame.getByLabel("Card Number").fill("4111 1111 1111 1111");
payFrame.getByLabel("Expiry").fill("12/25");
payFrame.getByLabel("CVV").fill("123");
payFrame.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Pay")).click();

// ── Find frame by URL (useful for dynamic IDs) ─────────────────
FrameLocator byUrl = page.frameLocator("iframe[src*='payment']");

// ── Nested frames ──────────────────────────────────────────────
// Page → iframe#outer → iframe#inner
FrameLocator inner = page
    .frameLocator("#outer-frame")
    .frameLocator("#inner-frame");
inner.getByRole(AriaRole.TEXTBOX).fill("nested iframe content");

// ── Use locator().contentFrame() for Frame object ──────────────
// When you need the Frame object (not FrameLocator)
Frame frame = page.locator("iframe#my-frame").contentFrame();
String frameUrl = frame.url();
frame.waitForLoadState(LoadState.LOAD);

// Get all frames in the page
List<Frame> frames = page.frames();

// Get frame by name attribute: <iframe name="checkout">
Frame byName = page.frame("checkout");

// Get frame by URL
Frame byUrl = page.frameByUrl("**/checkout/**");

// Main frame (the page itself)
Frame main = page.mainFrame();

// Frame info
System.out.println(frame.name());    // iframe name attribute
System.out.println(frame.url());     // frame's current URL
System.out.println(frame.title());   // frame's document title
System.out.println(frame.parentFrame() == null ? "main" : "child");

// ── Alert (only dismiss/accept, no input) ─────────────────────
page.onDialog(dialog -> {
    System.out.println("Alert says: " + dialog.message());
    dialog.accept(); // dismiss the alert (OK)
});
page.locator("#trigger-alert").click();

// ── Confirm dialog ────────────────────────────────────────────
page.onDialog(dialog -> {
    System.out.println("Dialog type: " + dialog.type()); // "confirm"
    System.out.println("Message: "     + dialog.message());
    dialog.dismiss(); // Click "Cancel"
    // dialog.accept(); → Click "OK"
});
page.locator("#delete-btn").click();

// ── Prompt dialog (has text input) ───────────────────────────
page.onDialog(dialog -> {
    System.out.println("Default value: " + dialog.defaultValue());
    dialog.accept("My custom input"); // type into prompt and confirm
});

// ── dialog.type() possible values ───────────────────────────
// "alert"   → window.alert("message")
// "confirm" → window.confirm("message") → true/false
// "prompt"  → window.prompt("message", "default") → string
// "beforeunload" → triggered on page close

// ── One-time dialog handler ───────────────────────────────────
// Use once() to auto-remove after first dialog
page.once("dialog", dialog -> dialog.accept());

// Method 1: waitForPopup() — clean synchronous approach
Page popup = page.waitForPopup(() -> {
    page.locator("a[target='_blank']").click(); // link opens new tab
});
popup.waitForLoadState(LoadState.LOAD);
assertThat(popup).hasURL("**/terms");
popup.close();

// Method 2: onPopup() event listener
page.onPopup(newPage -> {
    newPage.waitForLoadState();
    System.out.println("Popup URL: " + newPage.url());
    // interact with the popup...
    newPage.close();
});
page.locator("#open-help").click();

// Multiple pop-ups — handle each via context
// New pages also appear in context.pages()
List<Page> allPages = context.pages();
// allPages.get(0) → original page
// allPages.get(1) → first popup
// allPages.get(2) → second popup

// context.waitForPage() — similar to page.waitForPopup() but on context level
Page newTab = context.waitForPage(() -> {
    page.keyboard().press("Control+T"); // open new tab via keyboard
});

// waitForDownload() — use BEFORE the download-triggering action
Download download = page.waitForDownload(() -> {
    page.locator("#export-csv").click();
});

// File info
System.out.println(download.suggestedFilename());  // "report.csv"
System.out.println(download.url());               // download URL

// Save to specific path
download.saveAs(Paths.get("downloads/report.csv"));

// Get path in temp folder (available until context closes)
Path tempPath = download.path();

// Cancel in-progress download
download.cancel();

// Delete temp file (cleanup)
download.delete();

// ── Full page screenshot (scrolls entire page) ────────────────
page.screenshot(new Page.ScreenshotOptions()
    .setPath(Paths.get("screenshots/full-page.png"))
    .setFullPage(true)
);

// ── Viewport screenshot (just visible area) ───────────────────
page.screenshot(new Page.ScreenshotOptions()
    .setPath(Paths.get("screenshots/viewport.png"))
);

// ── Element-level screenshot ──────────────────────────────────
page.locator("#order-summary").screenshot(new Locator.ScreenshotOptions()
    .setPath(Paths.get("screenshots/order-summary.png"))
);

// ── Screenshot as byte array (for test reporters / base64) ────
byte[] screenshotBytes = page.screenshot(
    new Page.ScreenshotOptions().setType(ScreenshotType.JPEG).setQuality(80)
);
// Attach to TestNG report or allure:
Reporter.log("<img src='data:image/jpeg;base64," +
    Base64.getEncoder().encodeToString(screenshotBytes) + "'/>");

// ── Clip to specific region ───────────────────────────────────
page.screenshot(new Page.ScreenshotOptions()
    .setClip(new Clip(0, 0, 800, 400))   // x, y, width, height
    .setPath(Paths.get("header-only.png"))
);

// ── Screenshot options ────────────────────────────────────────
// .setType(ScreenshotType.PNG)    ← default, lossless
// .setType(ScreenshotType.JPEG)   ← smaller files, lossy
// .setQuality(80)                 ← JPEG quality 0-100
// .setOmitBackground(true)        ← transparent background (PNG only)
// .setAnimations(AnimationsPolicy.DISABLED)  ← stop CSS animations
// .setCaret(CaretVisibility.HIDE) ← hide text cursor
// .setScale(ScreenshotScale.CSS)  ← CSS pixels (default) or DEVICE
// .setTimeout(5000)               ← max wait for screenshot

BrowserContext context = browser.newContext(
    new Browser.NewContextOptions()
        .setRecordVideoDir(Paths.get("videos/"))
        .setRecordVideoSize(1280, 720)     // optional resolution
);

Page page = context.newPage();
// ... run your test ...

// Video is finalized when page OR context is closed
// Save path BEFORE closing (path() returns null after close)
Path videoPath = page.video().path();
page.close();

// After page close, the video is written to disk
// Rename/move it:
page.video().saveAs(Paths.get("videos/test-login.webm"));
page.video().delete();  // delete temp file

// ── Start tracing ─────────────────────────────────────────────
context.tracing().start(new Tracing.StartOptions()
    .setScreenshots(true)    // capture screenshot on each action
    .setSnapshots(true)      // capture DOM snapshot (enables timeline inspection)
    .setSources(true)        // include source files in trace
    .setTitle("Login Test")   // label in Trace Viewer
);

Page page = context.newPage();
// ... run test ...

// ── Stop and save trace ───────────────────────────────────────
context.tracing().stop(new Tracing.StopOptions()
    .setPath(Paths.get("traces/login-test.zip"))
);

// ── Chunks: start once, take snapshot per test ────────────────
context.tracing().start(new Tracing.StartOptions().setScreenshots(true).setSnapshots(true));

// Before each test:
context.tracing().startChunk(new Tracing.StartChunkOptions().setTitle("Test 1"));
// ... test runs ...
context.tracing().stopChunk(new Tracing.StopChunkOptions().setPath(Paths.get("traces/test1.zip")));

context.tracing().startChunk(new Tracing.StartChunkOptions().setTitle("Test 2"));
// ... next test ...
context.tracing().stopChunk(new Tracing.StopChunkOptions().setPath(Paths.get("traces/test2.zip")));

# Open trace file in Playwright Trace Viewer (opens a browser):
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="show-trace traces/login-test.zip"

# Or online (no install needed):
# Go to https://trace.playwright.dev and drag-drop your .zip file

// Add cookies to context (affects all pages)
context.addCookies(List.of(
    new Cookie("session_token", "abc123xyz")
        .setDomain("example.com")
        .setPath("/")
        .setHttpOnly(true)
        .setSecure(true)
        .setSameSite(SameSiteAttribute.LAX)
        .setExpires(-1)   // -1 = session cookie (no expiry)
));

// Read cookies (optionally filtered by URL)
List<Cookie> cookies = context.cookies();
List<Cookie> forSite = context.cookies(List.of("https://example.com"));
cookies.forEach(c -> System.out.println(c.name + "=" + c.value));

// Clear all cookies
context.clearCookies();

// localStorage persists across browser sessions (for a given origin)
// sessionStorage lives only for the current tab session

// Set localStorage item
page.evaluate("() => localStorage.setItem('theme', 'dark')");
page.evaluate("([key, val]) => localStorage.setItem(key, val)",
    Arrays.asList("user_prefs", "{\"lang\":\"en\"}"));

// Get localStorage item
String theme = (String) page.evaluate("() => localStorage.getItem('theme')");

// Clear all localStorage
page.evaluate("() => localStorage.clear()");

// sessionStorage — same API
page.evaluate("() => sessionStorage.setItem('token', 'xyz')");

// ── Step 1: Create auth.json once (run before your test suite) ─
public void saveAuthState() {
    try (Playwright pw = Playwright.create()) {
        Browser browser = pw.chromium().launch();
        BrowserContext context = browser.newContext();
        Page page = context.newPage();

        // Perform login once
        page.navigate("https://app.example.com/login");
        page.getByLabel("Email").fill("[email protected]");
        page.getByLabel("Password").fill("securepassword");
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Login")).click();
        assertThat(page).hasURL("**/dashboard");

        // Save cookies + localStorage to file
        context.storageState(new BrowserContext.StorageStateOptions()
            .setPath(Paths.get("auth.json"))
        );
        // auth.json contains: {"cookies":[...], "origins":[{"origin":"...","localStorage":[...]}]}
    }
}

// ── Step 2: Load saved state in every test ────────────────────
public BrowserContext createLoggedInContext() {
    return browser.newContext(new Browser.NewContextOptions()
        .setStorageStatePath(Paths.get("auth.json"))  // inject saved auth
    );
    // Test opens already-logged-in — no login page needed
}

// Context-level proxy (affects all requests from this context)
BrowserContext context = browser.newContext(new Browser.NewContextOptions()
    .setProxy(new Proxy("http://proxy.example.com:8080")
        .setUsername("proxyUser")
        .setPassword("proxyPass")
        .setBypass("localhost,127.0.0.1")  // bypass proxy for these
    )
);

// Launch-level proxy (for all contexts)
Browser browser = playwright.chromium().launch(
    new BrowserType.LaunchOptions()
        .setProxy(new Proxy("socks5://proxy:1080"))
);

Browser.NewContextOptions opts = new Browser.NewContextOptions()
    // Viewport: window size seen by the page's CSS media queries
    .setViewportSize(1440, 900)

    // Device Scale Factor (2.0 = Retina / HiDPI)
    .setDeviceScaleFactor(2.0)

    // isMobile: adds mobile UA, touch events, meta viewport tag
    .setIsMobile(true)
    .setHasTouch(true)

    // Locale: affects Accept-Language header, date/number formats
    .setLocale("fr-FR")

    // Timezone: affects Date() objects in the page
    .setTimezoneId("Europe/Paris")
    // Full list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

    // Color scheme: prefers-color-scheme media query
    .setColorScheme(ColorScheme.DARK)
    // Options: DARK, LIGHT, NO_PREFERENCE

    // Reduced motion: prefers-reduced-motion media query
    .setReducedMotion(ReducedMotion.REDUCE)

    // Forced colors: Windows high-contrast mode
    .setForcedColors(ForcedColors.ACTIVE);

// Emulate print media
page.emulateMedia(new Page.EmulateMediaOptions()
    .setMedia(Media.PRINT));

// Timeout hierarchy (lower overrides higher):
// PlaywrightAssertions global → Context → Page → Per-call

// Global assertion timeout (default 5000ms)
PlaywrightAssertions.setDefaultAssertionTimeout(10000);

// Context-level: all pages inherit these
context.setDefaultTimeout(15000);           // all operations (click, fill, etc.)
context.setDefaultNavigationTimeout(30000); // navigate/goto only

// Page-level (overrides context)
page.setDefaultTimeout(10000);
page.setDefaultNavigationTimeout(20000);

// Per-operation (overrides all above)
page.locator("#slow-element").click(
    new Locator.ClickOptions().setTimeout(5000)
);

package com.example.base;

import com.microsoft.playwright.*;
import org.testng.annotations.*;
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

public class BaseTest {

    // ── Thread-local storage for parallel test safety ──────────────────
    // ThreadLocal means each thread (test) gets its own isolated instance
    private static ThreadLocal<Playwright> playwrightTL = new ThreadLocal<>();
    private static ThreadLocal<Browser> browserTL       = new ThreadLocal<>();
    private static ThreadLocal<BrowserContext> contextTL = new ThreadLocal<>();
    private static ThreadLocal<Page> pageTL             = new ThreadLocal<>();

    // Convenience accessors for subclasses
    protected Page           page()    { return pageTL.get(); }
    protected BrowserContext context() { return contextTL.get(); }
    protected Browser        browser() { return browserTL.get(); }

    // ── One browser per thread (created once per test/thread) ─────────
    @BeforeMethod(alwaysRun = true)
    @Parameters({"browser"})   // optional: read from testng.xml
    public void setUp(@Optional("chromium") String browserName) {
        Playwright pw = Playwright.create();
        playwrightTL.set(pw);

        // Select browser from parameter
        BrowserType browserType;
        switch (browserName.toLowerCase()) {
            case "firefox": browserType = pw.firefox(); break;
            case "webkit":  browserType = pw.webkit();  break;
            default:       browserType = pw.chromium(); break;
        }

        Browser browser = browserType.launch(
            new BrowserType.LaunchOptions()
                .setHeadless(Boolean.parseBoolean(
                    System.getProperty("headless", "true")
                ))
        );
        browserTL.set(browser);

        // New isolated context per test
        BrowserContext context = browser.newContext(
            new Browser.NewContextOptions()
                .setViewportSize(1280, 720)
                .setIgnoreHTTPSErrors(true)
        );
        contextTL.set(context);

        // Start tracing for every test
        context.tracing().start(new Tracing.StartOptions()
            .setScreenshots(true).setSnapshots(true));

        Page page = context.newPage();
        pageTL.set(page);
    }

    @AfterMethod(alwaysRun = true)
    public void tearDown(org.testng.ITestResult result) {
        try {
            // Save trace only on failure (saves disk space)
            if (!result.isSuccess()) {
                String traceName = result.getName() + "-" + System.currentTimeMillis() + ".zip";
                contextTL.get().tracing().stop(
                    new Tracing.StopOptions().setPath(Paths.get("traces/" + traceName)));
            } else {
                contextTL.get().tracing().stop(); // stop without saving
            }
        } finally {
            // Always clean up in reverse order
            contextTL.get().close();
            browserTL.get().close();
            playwrightTL.get().close();
            // Remove from ThreadLocal to avoid memory leaks
            contextTL.remove(); browserTL.remove(); playwrightTL.remove(); pageTL.remove();
        }
    }
}

package com.example.tests;

import com.example.base.BaseTest;
import org.testng.annotations.Test;
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;

public class LoginTest extends BaseTest {

    @Test(description = "Valid credentials navigate to dashboard")
    public void validLoginNavigatesToDashboard() {
        page().navigate("https://app.example.com/login");

        page().getByLabel("Email").fill("[email protected]");
        page().getByLabel("Password").fill("password123");
        page().getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Login")).click();

        assertThat(page()).hasURL("**/dashboard");
        assertThat(page().getByRole(AriaRole.HEADING)).containsText("Dashboard");
    }

    @Test(description = "Invalid credentials show error message")
    public void invalidLoginShowsError() {
        page().navigate("https://app.example.com/login");
        page().getByLabel("Email").fill("[email protected]");
        page().getByLabel("Password").fill("wrongpass");
        page().getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Login")).click();

        assertThat(page().getByRole(AriaRole.ALERT)).containsText("Invalid credentials");
        assertThat(page()).hasURL("**/login");
    }
}

import org.junit.jupiter.api.*;
import com.microsoft.playwright.*;

public class BaseTestJUnit5 {

    // @BeforeAll → @BeforeEach for full isolation (or share browser)
    static Playwright playwright;
    static Browser browser;
    BrowserContext context;
    Page page;

    @BeforeAll
    static void launchBrowser() {
        playwright = Playwright.create();
        browser = playwright.chromium().launch(
            new BrowserType.LaunchOptions().setHeadless(true)
        );
    }

    @BeforeEach
    void createContextAndPage() {
        context = browser.newContext();
        page = context.newPage();
    }

    @AfterEach
    void closeContext() {
        context.close();
    }

    @AfterAll
    static void closeBrowser() {
        browser.close();
        playwright.close();
    }
}

// Test class:
class DashboardTest extends BaseTestJUnit5 {

    @Test
    void dashboardLoads() {
        page.navigate("https://app.example.com/dashboard");
        assertThat(page.getByRole(AriaRole.HEADING)).isVisible();
    }
}

<!-- parallel="tests" → each <test> block in its own thread -->
<!-- parallel="methods" → each @Test method in its own thread -->
<!-- parallel="classes" → each test class in its own thread -->

<suite name="Playwright Suite" parallel="methods" thread-count="4">
    <test name="All Tests">
        <classes>
            <class name="com.example.tests.LoginTest"/>
            <class name="com.example.tests.ProductTest"/>
            <class name="com.example.tests.CheckoutTest"/>
        </classes>
    </test>
</suite>

package com.example.pages;

import com.microsoft.playwright.*;

public abstract class BasePage {

    protected final Page page;

    public BasePage(Page page) {
        this.page = page;
    }

    // Utility: wait for page to fully load
    protected void waitForPageLoad() {
        page.waitForLoadState(LoadState.DOMCONTENTLOADED);
    }

    // Utility: get page title
    public String getTitle() {
        return page.title();
    }

    // Utility: take a screenshot for debugging
    public void takeScreenshot(String name) {
        page.screenshot(new Page.ScreenshotOptions()
            .setPath(Paths.get("screenshots/" + name + ".png")));
    }
}

package com.example.pages;

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

public class LoginPage extends BasePage {

    // ── Locators defined once, used many times ─────────────────────
    // Private final: locators are lazy — safe to define at field level
    private final Locator emailInput;
    private final Locator passwordInput;
    private final Locator loginButton;
    private final Locator errorMessage;
    private final Locator forgotPasswordLink;

    public LoginPage(Page page) {
        super(page);
        // All locators initialized here — lazy, no DOM query yet
        emailInput       = page.getByLabel("Email");
        passwordInput    = page.getByLabel("Password");
        loginButton      = page.getByRole(AriaRole.BUTTON,
                               new Page.GetByRoleOptions().setName("Login"));
        errorMessage     = page.locator("[role='alert']");
        forgotPasswordLink = page.getByText("Forgot password?");
    }

    // ── Navigation ────────────────────────────────────────────────
    public LoginPage navigate() {
        page.navigate("/login");
        return this; // fluent chaining
    }

    // ── Actions ───────────────────────────────────────────────────
    public LoginPage enterEmail(String email) {
        emailInput.fill(email);
        return this;
    }

    public LoginPage enterPassword(String password) {
        passwordInput.fill(password);
        return this;
    }

    public DashboardPage clickLoginExpectingSuccess() {
        loginButton.click();
        // Return the NEXT page object — models navigation flow
        return new DashboardPage(page);
    }

    public LoginPage clickLoginExpectingFailure() {
        loginButton.click();
        return this; // stay on login page on failure
    }

    // ── Compound action (full login flow) ─────────────────────────
    public DashboardPage loginAs(String email, String password) {
        return navigate()
            .enterEmail(email)
            .enterPassword(password)
            .clickLoginExpectingSuccess();
    }

    // ── Assertions (page-level verifications) ─────────────────────
    public LoginPage assertErrorMessageContains(String text) {
        assertThat(errorMessage).containsText(text);
        return this;
    }

    public LoginPage assertOnLoginPage() {
        assertThat(page).hasURL("**/login");
        assertThat(loginButton).isVisible();
        return this;
    }
}

public class LoginTest extends BaseTest {

    @Test
    public void successfulLogin() {
        new LoginPage(page())
            .loginAs("[email protected]", "password123")
            .assertOnDashboard();
        // Clean! No raw locators in test code.
    }

    @Test
    public void invalidCredentialsShowError() {
        new LoginPage(page())
            .navigate()
            .enterEmail("[email protected]")
            .enterPassword("wrongpass")
            .clickLoginExpectingFailure()
            .assertErrorMessageContains("Invalid credentials")
            .assertOnLoginPage();
    }
}

public class DataTableComponent {

    private final Locator root; // the table element

    // Takes scoped locator — searches only inside the table
    public DataTableComponent(Locator tableRoot) {
        this.root = tableRoot;
    }

    public int rowCount() {
        return root.locator("tbody tr").count();
    }

    public String getCellText(int row, int col) {
        return root.locator("tbody tr").nth(row)
                   .locator("td").nth(col)
                   .innerText();
    }

    public void clickAction(int row, String actionName) {
        root.locator("tbody tr").nth(row)
            .getByRole(AriaRole.BUTTON,
                new Page.GetByRoleOptions().setName(actionName))
            .click();
    }

    public void assertHasRow(String text) {
        assertThat(root.locator("tbody tr")
            .filter(new Locator.FilterOptions().setHasText(text)))
            .isVisible();
    }
}

// Usage in a page object:
public class UsersPage extends BasePage {
    public DataTableComponent usersTable() {
        return new DataTableComponent(page.locator("#users-table"));
    }
}

// Usage in test:
new UsersPage(page)
    .usersTable()
    .assertHasRow("Alice");

// playwright.devices() returns a Map of preset device descriptors
Map<String, DeviceDescriptor> devices = playwright.devices();

// Common device names:
// "iPhone 14", "iPhone 14 Pro", "iPhone 14 Pro Max"
// "iPad Pro 11", "iPad (gen 7)"
// "Pixel 7", "Galaxy S8"
// "Desktop Chrome", "Desktop Firefox", "Desktop Safari"

DeviceDescriptor iphone = playwright.devices().get("iPhone 14");

// Each DeviceDescriptor has: viewport, userAgent, deviceScaleFactor,
//   isMobile, hasTouch (all the right settings for that device)
BrowserContext mobileCtx = browser.newContext(
    new Browser.NewContextOptions()
        .setViewportSize(iphone.viewport().width, iphone.viewport().height)
        .setUserAgent(iphone.userAgent())
        .setDeviceScaleFactor(iphone.deviceScaleFactor())
        .setIsMobile(iphone.isMobile())
        .setHasTouch(iphone.hasTouch())
        .setLocale("en-US")
);

// Grant geolocation permission and set coordinates
BrowserContext ctx = browser.newContext(
    new Browser.NewContextOptions()
        .setGeolocation(new Geolocation(51.5074, -0.1278)) // London
        .setPermissions(List.of("geolocation"))
);

// Change geolocation mid-test
ctx.setGeolocation(new Geolocation(48.8566, 2.3522)); // Paris

// Grant permissions on context
ctx.grantPermissions(List.of("notifications"), "https://example.com");
ctx.grantPermissions(List.of("camera", "microphone"));

// Available permissions: "geolocation", "midi", "midi-sysex",
// "notifications", "push", "camera", "microphone",
// "background-sync", "clipboard-read", "clipboard-write"

ctx.clearPermissions(); // revoke all granted permissions

# Run test with Inspector (opens browser + inspector side-by-side)
PWDEBUG=1 mvn test -Dtest=LoginTest

# On Windows:
set PWDEBUG=1 && mvn test -Dtest=LoginTest

# PWDEBUG=console: log all Playwright calls to browser console
PWDEBUG=console mvn test -Dtest=LoginTest

# Slow motion via system property in your BaseTest:
# .setSlowMo(500) — adds 500ms delay after each action
mvn test -DslowMo=500

// Pause test execution — opens Inspector and waits for "Resume" click
page.pause(); // ← add to your test to pause at a specific point

// Set in headless=false + slowMo for visual debugging:
Browser browser = playwright.chromium().launch(
    new BrowserType.LaunchOptions()
        .setHeadless(false)
        .setSlowMo(500) // 500ms between each action — easy to follow visually
);

// Console message logging (catch JS errors):
page.onConsoleMessage(msg -> {
    if (msg.type().equals("error")) {
        System.err.println("Browser console error: " + msg.text());
    }
});

// Page errors (uncaught exceptions):
page.onPageError(e -> System.err.println("JS Exception: " + e.message()));

# Launch Codegen — browser + code panel side-by-side
# As you click/type in the browser, Java code is generated
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="codegen https://example.com"

# Save generated code to a file:
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="codegen --target java --output MyTest.java https://example.com"

# With viewport size:
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="codegen --viewport-size 1280,720 https://example.com"

# With saved auth state:
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI \
              -D exec.args="codegen --load-storage auth.json https://app.example.com"

name: Playwright Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'
          cache: 'maven'

      - name: Cache Playwright browsers
        uses: actions/cache@v4
        with:
          path: ~/.cache/ms-playwright
          key: playwright-${{ hashFiles('pom.xml') }}

      - name: Install Playwright browsers
        run: mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps chromium"

      - name: Run Playwright tests
        run: mvn test -Dheadless=true
        env:
          BASE_URL: https://staging.example.com
          TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
          TEST_USER_PASS: ${{ secrets.TEST_USER_PASS }}

      - name: Upload traces on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-traces
          path: traces/
          retention-days: 7

      - name: Upload test reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: surefire-report
          path: target/surefire-reports/

# Use Playwright's official base image (includes all browser deps)
FROM mcr.microsoft.com/playwright/java:v1.44.0-jammy

WORKDIR /app

COPY pom.xml .
COPY src ./src

# Install Maven
RUN apt-get update && apt-get install -y maven

# Download dependencies
RUN mvn dependency:go-offline -q

# Run tests
CMD ["mvn", "test", "-Dheadless=true"]

// ❌ ANTI-PATTERN 1: Hardcoded sleep
page.waitForTimeout(3000); // Makes test 3s slower always

// ✅ CORRECT: Wait for the condition that matters
assertThat(page.locator("#result")).isVisible();
// ↑ Waits up to 5s but returns immediately when visible

// ─────────────────────────────────────────────────────────────

// ❌ ANTI-PATTERN 2: One BrowserContext for all tests (no isolation)
static BrowserContext sharedContext; // shared across ALL tests → cookies pollute

// ✅ CORRECT: New context per test
@BeforeMethod void setUp() { context = browser.newContext(); }
@AfterMethod  void tearDown() { context.close(); }

// ─────────────────────────────────────────────────────────────

// ❌ ANTI-PATTERN 3: Storing ElementHandle (stale reference risk)
ElementHandle el = page.querySelector("button"); // snapshot of DOM
// ... DOM changes ...
el.click(); // May throw StaleElementException

// ✅ CORRECT: Use Locator (always re-queries)
Locator btn = page.locator("button"); // lazy, re-queries every time
btn.click(); // always fresh

// ─────────────────────────────────────────────────────────────

// ❌ ANTI-PATTERN 4: Using page.waitForSelector() (old API)
page.waitForSelector("#result"); // returns ElementHandle — legacy

// ✅ CORRECT: Locator.waitFor() or assertThat
page.locator("#result").waitFor();
// OR (better, with assertion message):
assertThat(page.locator("#result")).isVisible();

// ─────────────────────────────────────────────────────────────

// ❌ ANTI-PATTERN 5: Using NetworkIdle for all navigation
page.navigate("...", new Page.NavigateOptions().setWaitUntil(WaitUntilState.NETWORKIDLE));
// Adds seconds to every navigation if app has background requests

// ✅ CORRECT: Default LOAD + wait for specific element
page.navigate("..."); // waits for 'load' event
assertThat(page.getByRole(AriaRole.HEADING)).isVisible(); // wait for actual content