Skip to content
javahacks.dev
Testing

Playwright for Java End to End Testing Guide for Web Apps

A complete guide to Playwright for Java: locators, auto waiting, JUnit fixtures, Spring Boot setup, page objects, auth, tracing, CI and flakiness.

28 min read
Summarize in AI
Flat illustration of a test report with one failing test, with the OpenJDK, Spring Boot, Docker and Selenium logos.

End to end tests have a deserved reputation: slow, brittle and trusted by nobody. The tests that drive a browser are where regressions in real user journeys get caught, such as the checkout that no unit test can see is broken because a button is covered by a banner, and they are where teams give up after the hundredth intermittent failure. Most of that brittleness comes from tools that make you manage timing yourself, with explicit waits, sleeps and retries scattered through the code. Playwright was designed to remove that class of problem. It controls Chromium, Firefox and WebKit through one API, waits automatically for elements to be ready before acting and retries assertions until they hold. It has an official Java binding, so tests live in your Maven or Gradle build beside the application and run with JUnit. This guide takes you from the first test to a maintainable suite: setup, locators, actions and assertions, JUnit lifecycle, Spring Boot integration with a real database, page objects, authentication, network control, debugging with traces, parallel execution and continuous integration. Every section has code, and the final sections cover what makes suites flaky and when a browser test is the wrong tool.

The line to remember: a good end to end test describes what a user does in the words a user would use, and lets the tool worry about timing. The sections below are how to follow it in Java. For the tests that should be the bulk of your suite, see the test pyramid for Java services and unit versus integration tests.

Setup

Add the dependency to the test scope of the project:

pom.xmlXML
<dependency>
    <groupId>com.microsoft.playwright</groupId>
    <artifactId>playwright</artifactId>
    <version>1.49.0</version>
    <scope>test</scope>
</dependency>

Playwright needs browser binaries, which it downloads on first use into a cache directory. Install them explicitly in CI and on a new machine so a test run does not spend its first minute downloading:

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

The --with-deps flag also installs the operating system libraries the browser needs, which matters on a bare Linux container. Drop the browser name to install all three. The Java library, the driver it runs and the browsers are version locked, so upgrading the dependency means reinstalling the browsers.

The first test

The smallest useful test creates a Playwright instance, launches a browser, opens a page, acts and asserts:

src/test/java/dev/javahacks/e2e/FirstPlaywrightTest.javajava
package dev.javahacks.e2e;

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

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

class FirstPlaywrightTest {

    @Test
    void searchShowsMatchingResults() {
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().launch(new BrowserType.LaunchOptions().setHeadless(true));
            BrowserContext context = browser.newContext();
            Page page = context.newPage();

            page.navigate("https://shop.example.test");
            page.getByPlaceholder("Search products").fill("java book");
            page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Search")).click();

            assertThat(page.getByRole(AriaRole.HEADING, new Page.GetByRoleOptions().setName("Results for java book")))
                    .isVisible();
            assertThat(page.locator(".product-card")).hasCount(12);
        }
    }
}

Four objects form a hierarchy. Playwright owns the driver process. A Browser is one browser instance. A **BrowserContext** is an isolated session inside it, like an incognito profile, with its own cookies and storage, cheap to create. A Page is one tab. The structure matters because it dictates test isolation: a fresh context per test costs milliseconds and guarantees that one test's login does not leak into the next, where launching a fresh browser per test costs seconds.

Notice what the test does not contain: no sleep, no explicit wait, no WebDriverWait. Clicking waits for the button to exist, be visible, be stable (not animating) and receive events. assertThat(...).hasCount(12) retries for up to five seconds until the count is 12 and fails with a message showing the last observed value if it never is.

Locators: find what users see

A locator describes how to find an element and is evaluated fresh each time it is used, so it never goes stale like a Selenium WebElement can. Playwright's locator methods are ranked by how closely they match what a user perceives:

LocatorFindsPrefer for
getByRole(role, name)Elements by ARIA role and accessible nameButtons, links, headings, form fields: the first choice
getByLabel("Email")Form controls by their labelInputs
getByPlaceholderBy placeholder textInputs without labels
getByText("Welcome back")By visible textStatic text and messages
getByAltText, getByTitleBy alt text or titleImages, tooltips
getByTestId("checkout-total")By a data-testid attributeWhen no user visible handle exists
locator("css or xpath")By CSS or XPathLast resort
java
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Add to basket")).click();
page.getByLabel("Email").fill("[email protected]");
page.getByRole(AriaRole.ROW, new Page.GetByRoleOptions().setName("Java Book"))
        .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Remove")).click();

The third line shows chaining: find the table row for one product, then the button inside that row only. Scoping like this replaces brittle indexed selectors such as button:nth-child(3). Role based locators have a second benefit: they pass only when the page is accessible, so a test that cannot find a button by its role is telling you the markup has an accessibility problem. If an element has no role, label or text a user can see, add a data-testid and configure Playwright to use it:

java
playwright.selectors().setTestIdAttribute("data-test");

Avoid selectors tied to layout or styling (div > div:nth-child(2) .btn-primary): they break whenever a designer moves something. Locators are strict by default: if one matches more than one element and you act on it, Playwright throws a strict mode violation, naming the matches, which is a feature, since an ambiguous locator would otherwise click an arbitrary element. Narrow it, or use first(), last() or nth(n) deliberately.

Actions and auto waiting

The actions you use most are click, fill, check, selectOption, press, hover and setInputFiles. Before each, Playwright runs actionability checks: the element must be attached to the DOM, visible, stable (not moving), enabled and receiving events at the click point, not covered by another element. It retries these until they pass or the action timeout (30 seconds by default) expires, then fails with a log of which check failed:

Text
com.microsoft.playwright.TimeoutError: Error {
  message='Timeout 30000ms exceeded.
Call log:
  - waiting for getByRole(AriaRole.BUTTON, name="Pay now")
  -   locator resolved to <button disabled class="btn">Pay now</button>
  -   attempting click action
  -   waiting for element to be visible, enabled and stable
  -     element is not enabled
  -   retrying click action

That call log is the main debugging aid: it states that the button was found but disabled, which points at the form validation, not at the test. Compare it with a Selenium NoSuchElementException, which says almost nothing.

Common actions:

java
page.getByLabel("Quantity").fill("3");
page.getByLabel("I accept the terms").check();
page.getByLabel("Country").selectOption("Vietnam");
page.keyboard().press("Enter");
page.getByLabel("Upload invoice").setInputFiles(Paths.get("src/test/resources/invoice.pdf"));
page.getByText("Order details").hover();

fill clears the field and sets the value, firing the input events a framework needs; use pressSequentially when a widget reacts to individual keystrokes, such as an autocomplete. Do not sleep: page.waitForTimeout(2000) exists, and each use in a test is a sign that a proper wait condition is missing.

Web first assertions

PlaywrightAssertions.assertThat takes a locator, a page or a response and offers assertions that retry until they pass:

java
assertThat(page).hasURL(Pattern.compile(".*/orders/\\d+"));
assertThat(page).hasTitle("Order confirmation");
assertThat(page.getByText("Thank you for your order")).isVisible();
assertThat(page.locator(".basket-count")).hasText("3");
assertThat(page.getByLabel("Email")).hasValue("[email protected]");
assertThat(page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Pay now"))).isEnabled();
assertThat(page.locator(".error")).hasCount(0);
assertThat(page.locator(".toast")).containsText("saved");

Contrast this with JUnit's assertEquals(3, Integer.parseInt(page.locator(".basket-count").textContent())), which reads the text once, immediately, and fails if the page has not finished updating: the classic flaky test. A web first assertion waits up to its timeout (5 seconds by default, assertThat(...).setTimeout-configurable) for the condition. Use them for anything the page changes. Use plain JUnit or AssertJ assertions for values that are static once read, such as a computed total from your own test data. Mixing the two is natural.

Two assertion habits are worth adopting. Assert on user visible outcomes, not implementation: the confirmation message, the URL, the new row in the table. And assert negatives with the matching retrying form, assertThat(locator).isHidden() or hasCount(0), not by checking that an element is absent once.

JUnit 5 structure

Launching a browser for every test is slow and wasteful. The standard arrangement is one Playwright and Browser per test class, a new BrowserContext and Page per test:

src/test/java/dev/javahacks/e2e/PlaywrightTest.javajava
package dev.javahacks.e2e;

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

public abstract class PlaywrightTest {
    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(!Boolean.getBoolean("headed")));
    }

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

    @BeforeEach
    void createContext() {
        context = browser.newContext(new Browser.NewContextOptions()
                .setViewportSize(1280, 800)
                .setLocale("en-US")
                .setTimezoneId("Asia/Ho_Chi_Minh"));
        context.setDefaultTimeout(10_000);
        page = context.newPage();
    }

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

Subclasses just use page. Run with -Dheaded=true to watch the browser while writing a test. Fix the locale, time zone and viewport in the context options so the tests do not depend on the machine they run on, since a date rendered in the developer's zone and in the CI server's zone is a classic source of "passes locally". Playwright objects are not thread safe: if tests run in parallel, each thread needs its own Playwright instance, so use a ThreadLocal holder or run test classes in separate JVM forks.

Testing your own Spring Boot application

For an application in the same repository, start it as part of the test, on a random port, with a real database in a container, and drive it through a browser:

src/test/java/dev/javahacks/e2e/CheckoutE2ETest.javajava
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@Testcontainers
class CheckoutE2ETest extends PlaywrightTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:17");

    @LocalServerPort
    int port;

    @Autowired
    TestData data;                         // helper that inserts fixtures through repositories

    @Test
    void aCustomerCanBuyABookAsAGuest() {
        Product book = data.product("Java Book", "29.00");

        page.navigate("http://localhost:" + port + "/");
        page.getByRole(AriaRole.LINK, new Page.GetByRoleOptions().setName("Java Book")).click();
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Add to basket")).click();
        page.getByRole(AriaRole.LINK, new Page.GetByRoleOptions().setName("Basket (1)")).click();

        assertThat(page.getByRole(AriaRole.ROW, new Page.GetByRoleOptions().setName("Java Book"))).isVisible();
        assertThat(page.getByTestId("basket-total")).hasText("$29.00");

        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Checkout")).click();
        page.getByLabel("Email").fill("[email protected]");
        page.getByLabel("Card number").fill("4242424242424242");
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Pay now")).click();

        assertThat(page.getByRole(AriaRole.HEADING, new Page.GetByRoleOptions().setName("Thank you for your order"))).isVisible();
        assertThat(data.ordersFor("[email protected]")).hasSize(1);           // verify the side effect in the database
    }
}

Three points about this design. The database is real, through Testcontainers' service connection, so the test exercises the real persistence layer. Fixtures are created through application code or SQL (TestData) rather than by clicking through screens, because a test should drive the UI only for the behaviour under test, not for its preconditions. And the final assertion checks the database, since a UI that says "thank you" without saving an order is the bug that matters. External services, the card processor above, should be stubbed at the HTTP level, with WireMock as in mocking external APIs with WireMock, never called for real.

Page objects

A test that spells out every locator is hard to maintain: changing the label of one button means editing twenty tests. The page object pattern wraps a page's locators and actions in a class named for what the page offers:

src/test/java/dev/javahacks/e2e/pages/BasketPage.javajava
public class BasketPage {
    private final Page page;

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

    public BasketPage open(String baseUrl) {
        page.navigate(baseUrl + "/basket");
        return this;
    }

    public BasketPage removeItem(String productName) {
        page.getByRole(AriaRole.ROW, new Page.GetByRoleOptions().setName(productName))
                .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Remove")).click();
        return this;
    }

    public CheckoutPage checkout() {
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Checkout")).click();
        return new CheckoutPage(page);
    }

    public void assertContains(String productName) {
        assertThat(page.getByRole(AriaRole.ROW, new Page.GetByRoleOptions().setName(productName))).isVisible();
    }

    public void assertTotal(String expected) {
        assertThat(page.getByTestId("basket-total")).hasText(expected);
    }
}

The test now reads as the user journey:

java
new BasketPage(page).open(baseUrl).removeItem("Old Book").checkout().payAs("[email protected]", "4242424242424242");

Keep assertions about the page's state in the page object (assertTotal), and the expectations of the scenario in the test. Methods that navigate return the next page object, so the compiler guides you through the flow. Do not over abstract: a page object per significant page or component is enough, and a helper that is used once is not worth the indirection.

Authentication without logging in every time

Most tests need a logged in user, and logging in through the form in every test is slow and tests the login screen hundreds of times. Log in once, save the browser state and reuse it:

java
static final Path AUTH_STATE = Paths.get("target/auth/ana.json");

@BeforeAll
static void loginOnce() {
    try (BrowserContext login = browser.newContext()) {
        Page page = login.newPage();
        page.navigate(baseUrl + "/login");
        page.getByLabel("Email").fill("[email protected]");
        page.getByLabel("Password").fill("correct horse battery");
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in")).click();
        page.waitForURL("**/dashboard");
        login.storageState(new BrowserContext.StorageStateOptions().setPath(AUTH_STATE));
    }
}

@BeforeEach
void createAuthenticatedContext() {
    context = browser.newContext(new Browser.NewContextOptions().setStorageStatePath(AUTH_STATE));
    page = context.newPage();
}

storageState saves cookies and local storage to a JSON file, and a new context created from it starts already signed in. Keep the login scenario itself as one dedicated test that exercises the form. For token based APIs, authenticate with the APIRequestContext (below) and inject the token, which is faster still. The credentials are test data, created by the test setup and never real ones; store them in test configuration, not in source files that might be mistaken for production secrets.

Controlling the network

Playwright can intercept requests, which is useful in three ways. Stub an external call so the page does not depend on a third party:

java
page.route("**/api/exchange-rates", route -> route.fulfill(new Route.FulfillOptions()
        .setStatus(200)
        .setContentType("application/json")
        .setBody("{\"USD\": 1.0, \"VND\": 25000.0}")));

Simulate a failure to test error handling, which is hard to trigger otherwise:

java
page.route("**/api/orders", route -> route.fulfill(new Route.FulfillOptions().setStatus(503)));
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Pay now")).click();
assertThat(page.getByText("We could not place your order. Please try again.")).isVisible();

Wait for a specific request when the assertion should follow an API call:

java
Response response = page.waitForResponse("**/api/orders", () ->
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Pay now")).click());
assertThat(response.status()).isEqualTo(201);

Be sparing with stubbing: a test that stubs the entire back end tests only the front end, which is a legitimate component test, though not an end to end one. For the back end checks, an APIRequestContext makes HTTP calls with the same cookies as the browser context, so a test can set up or verify state through the API without the UI:

java
APIRequestContext api = playwright.request().newContext(new APIRequest.NewContextOptions().setBaseURL(baseUrl));
APIResponse created = api.post("/api/test/orders", RequestOptions.create().setData(Map.of("sku", "BK-1", "qty", 2)));
assertThat(created.ok()).isTrue();

Debugging: traces, screenshots and the inspector

A failing UI test in CI is useless without evidence. Playwright's best tool is the trace: a recording of every action with a DOM snapshot before and after, the network requests, the console and a timeline. Record one per test and keep it when the test fails:

java
@BeforeEach
void startTracing() {
    context.tracing().start(new Tracing.StartOptions().setScreenshots(true).setSnapshots(true).setSources(true));
}

@AfterEach
void saveTraceOnFailure(TestInfo info, TestReporter reporter) {
    boolean failed = /* determine from a TestWatcher extension */ testFailed;
    context.tracing().stop(failed
            ? new Tracing.StopOptions().setPath(Paths.get("target/traces/" + info.getDisplayName() + ".zip"))
            : new Tracing.StopOptions());
    context.close();
}

Open a trace with the viewer, which shows the steps on the left and a time travelling DOM on the right:

Shell
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="show-trace target/traces/checkout.zip"

Upload the target/traces folder as a CI artifact and a failed run becomes a replay. Determining pass or fail in @AfterEach needs a JUnit TestWatcher or TestExecutionExceptionHandler extension that records the outcome, covered in the JUnit extension model. Screenshots and video are simpler: page.screenshot(new Page.ScreenshotOptions().setPath(...).setFullPage(true)) on failure, and setRecordVideoDir(Paths.get("target/videos")) on the context options.

For writing a test, the Inspector is the fastest route. Run with the environment variable PWDEBUG=1 and the browser opens in step mode with a locator picker, and page.pause() in a test stops there so you can try locators live. The codegen tool records your clicks and prints Java code you can paste as a starting point:

Shell
mvn exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="codegen https://shop.example.test"

Treat generated code as a draft: tidy the locators and move repeated steps into page objects.

Parallel execution and speed

A suite of fifty browser tests at fifteen seconds each is twelve minutes serially. Playwright tests are isolated by context, so they parallelise well, with the thread safety rule: one Playwright instance per thread. With JUnit 5, either configure parallel execution and give each thread its own Playwright and Browser, or fork the JVM in Surefire so each fork runs some test classes:

pom.xmlXML
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-failsafe-plugin</artifactId>
    <configuration>
        <forkCount>4</forkCount>
        <reuseForks>true</reuseForks>
        <includes><include>**/*E2ETest.java</include></includes>
    </configuration>
</plugin>

Parallel tests must not share mutable state: a database fixture one test deletes breaks another that reads it. Give each test its own data (a unique email, its own tenant), as in deterministic tests with time and randomness. Beyond parallelism, speed comes from fewer end to end tests: skip UI setup by seeding data directly, reuse authentication state, stub slow third parties and keep each test to one journey.

Continuous integration

A CI job needs the browsers and their system dependencies, headless mode and artifacts for failures. In GitHub Actions:

.github/workflows/e2e.ymlYAML
name: e2e
on:
  pull_request:
jobs:
  e2e:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 25
          cache: maven
      - name: Install browsers
        run: mvn -B exec:java -e -D exec.mainClass=com.microsoft.playwright.CLI -D exec.args="install --with-deps chromium"
      - name: Run end to end tests
        run: mvn -B verify -Pe2e
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-traces
          path: target/traces

Docker is available on GitHub's hosted runners, so Testcontainers works. Cache the browser download directory (~/.cache/ms-playwright) to save a minute per run. Run the suite on pull requests for critical journeys and the full set nightly if it is large. Playwright also publishes Docker images with the browsers preinstalled (mcr.microsoft.com/playwright/java), which suit CI systems that build their own containers.

Iframes, popups, downloads and dialogs

Real applications have corners that a first tutorial skips, and Playwright handles each with a specific API instead of a workaround.

Iframes. Content inside an iframe is a separate document, reached through a FrameLocator. A payment widget embedded from a provider is the typical case:

java
FrameLocator card = page.frameLocator("iframe[name='card-fields']");
card.getByLabel("Card number").fill("4242424242424242");
card.getByLabel("Expiry").fill("12/30");
card.getByLabel("CVC").fill("123");

The frame locator waits for the frame to load, like any locator waits for its element.

New tabs and popups. An action that opens a window returns it through an event, which you must listen for before triggering the action, or the event is missed:

java
Page popup = page.waitForPopup(() ->
        page.getByRole(AriaRole.LINK, new Page.GetByRoleOptions().setName("Terms and conditions")).click());
assertThat(popup.getByRole(AriaRole.HEADING, new Page.GetByRoleOptions().setName("Terms"))).isVisible();

The lambda passed to waitForPopup performs the action, and the call returns the new Page once it opens.

Downloads. The same pattern captures a file download, and you can check where it landed and what it contains:

java
Download download = page.waitForDownload(() ->
        page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Export CSV")).click());
Path saved = download.path();
assertThat(Files.readString(saved)).startsWith("order_id,customer,total");
assertThat(download.suggestedFilename()).isEqualTo("orders.csv");

Native dialogs. alert, confirm and prompt dialogs are dismissed automatically unless you register a handler. Register one before the action when the test must accept or inspect it:

java
page.onDialog(dialog -> {
    assertThat(dialog.message()).contains("Delete this order?");
    dialog.accept();
});

Clipboard, geolocation and permissions are granted per context (context.grantPermissions(List.of("geolocation")), setGeolocation(...)), which allows deterministic tests of features that normally prompt the user.

Walking through the design of one journey

It helps to see the decisions behind a single test, since the skill of end to end testing is mostly in choosing what to put in a test. Take the journey "a returning customer reorders a previous purchase". A first draft clicks through registration, shopping, checkout and then the reorder. That draft is slow, and a failure anywhere before the reorder tells you nothing about reordering.

Redesign it by asking what the test is about. It is about the reorder feature, so everything before it is precondition, created directly: the test inserts a customer with a past order through the repository, loads the saved authentication state for that customer and opens the order history page. The browser then does only what the feature involves: find the past order, click "Reorder", check that the basket contains the same items and that the prices shown are the current prices, not the historic ones, and finish by paying. The result is a test that takes a few seconds, fails only when reordering is broken and reads as a description of the feature.

The second decision is the assertion at the end. A UI check, "thank you page visible", is necessary and weak on its own; an application can show a thank you page and fail to create the order. The test also asks the database, through the test data helper, whether a new order exists for the customer with the expected lines, and whether a payment record was created through the stubbed gateway exactly once. The exactly once matters in a journey with retries and double clicks, and it is the sort of defect that only an end to end test with a real database can show.

The third decision is what to leave out. The test does not check the footer, the header links or the exact wording of marketing text. Anything not about the journey would make the test fail for unrelated reasons, and the more assertions a test contains, the more reasons it has to fail. A test should fail for one reason, which should be the reason in its name.

Configuration per environment

The same tests are useful against several environments: the application started by the test itself, a shared staging deployment and, with care, a production smoke check. Parameterise the base URL and the browser, and keep secrets out of the code:

src/test/java/dev/javahacks/e2e/E2eConfig.javajava
public final class E2eConfig {
    private E2eConfig() {}

    public static String baseUrl(int localPort) {
        String configured = System.getProperty("e2e.baseUrl", System.getenv("E2E_BASE_URL"));
        return configured != null ? configured : "http://localhost:" + localPort;
    }

    public static BrowserType browserType(Playwright playwright) {
        return switch (System.getProperty("e2e.browser", "chromium")) {
            case "firefox" -> playwright.firefox();
            case "webkit" -> playwright.webkit();
            default -> playwright.chromium();
        };
    }
}
Shell
mvn verify -Pe2e -De2e.baseUrl=https://staging.example.test -De2e.browser=firefox

Running the critical journeys on all three engines nightly, and on Chromium for each pull request, catches the rare browser specific bug without tripling the cost of every build. Tests against a shared environment need extra care: use test accounts, unique data and cleanup, and never run destructive journeys against production.

Reading three typical failures

Knowing how failures look makes them quicker to fix.

The disabled button. The trace shows the click waiting on "Pay now" and the log says the element is not enabled. The usual cause is a form field that never became valid, because the test typed an invalid value or the form validates on blur and the test never left the field. The fix belongs in the test data or in a missing action such as press("Tab"), not in a longer timeout.

The strict mode violation. The error lists several matching elements: a page with two "Add to basket" buttons, one in the product card and one in the recommendations strip. The locator was too broad. Scope it to the container that identifies the product, rather than taking first(), which would click the wrong one the day the layout changes.

The assertion that passes locally and fails in CI. The trace shows the page, in CI, rendering an empty list for two seconds before the data arrives, and the assertion hasCount(12) timed out at five. The CI machine is slower and the back end is cold. Two legitimate fixes: raise the assertion timeout in CI through configuration, or make the page show a loading state that the test can wait for. A third, tempting fix, Thread.sleep(3000), hides the problem and slows every run.

The common thread is that the evidence, a trace with DOM snapshots, answers the question "what did the page look like at that moment" without rerunning anything, which is why recording it is the first thing to set up.

Moving from Selenium

Teams with an existing Selenium suite often ask what the translation looks like. The concepts map one to one, the differences are in waiting and element handling:

SeleniumPlaywright for Java
WebDriver driver = new ChromeDriver()browser.newPage() or a context's newPage()
driver.findElement(By.id("email")).sendKeys("x")page.getByLabel("Email").fill("x")
new WebDriverWait(driver, ...).until(visibilityOf(...))Not needed; actions and assertThat wait
WebElement (can go stale)Locator (re-resolved on each use)
driver.switchTo().frame(...)page.frameLocator(...)
Actions class for hover and draglocator.hover(), locator.dragTo(...)
Selenium GridRun Playwright in parallel forks, or a hosted browser service
Implicit waitsDefault action timeouts

Migrate incrementally. Write new tests in Playwright, move the flakiest Selenium tests first, since they gain the most from auto waiting and traces, and retire the old ones as journeys are covered. Run both in CI during the transition, and avoid translating line by line: a Selenium test full of explicit waits and page object workarounds is better rewritten from the user journey than mechanically converted.

Why browser tests flake, and the cures

Most flakiness has a known cause.

CauseSymptomCure
Fixed sleepsPass on fast machines, fail on slow onesDelete them; use auto waiting and web first assertions
Assertions that read onceassertEquals on textContent() fails intermittentlyUse assertThat(locator) that retries
Shared test dataA test fails only after another ranUnique data per test; clean up in the test
Dependence on time or random valuesFails near midnight or on a different localeFix the clock in the application, set locale and time zone in the context
Animations and transitionsClicks land on a moving elementActionability checks handle it; disable animations in test mode if needed
Real third party callsFails when the vendor is slowStub at the network or server level
Ambiguous locatorsClicks the wrong elementUse role and name; scope with chaining
Order dependencePasses alone, fails in the suiteIsolate state; run in random order
Resource starvation on CITimeouts only in CIFewer parallel forks, more CPU, longer action timeout in CI

Track flaky tests explicitly: a test that fails and passes on rerun is a bug report, and a policy of retrying it silently hides the bug. Set a retry of one in CI for diagnosis, and treat any test that needs it as broken. A longer treatment of the causes and fixes is in fixing flaky tests in Java.

Accessibility checks and visual concerns

Because locators are role based, accessibility is partly tested for free. For a more systematic check, the axe engine can be injected into a page and its findings asserted, with a Java wrapper such as axe-core through page.evaluate, and failures reported with the selectors involved. Visual regression, comparing screenshots against a baseline, is available in the JavaScript test runner and is not built into the Java library; for Java teams, tools such as Percy or a screenshot comparison library fill the gap, with the usual cost of baselines that must be reviewed and updated. Emulate devices by context options for a viewport, user agent and touch support:

java
BrowserContext mobile = browser.newContext(new Browser.NewContextOptions()
        .setViewportSize(390, 844)
        .setDeviceScaleFactor(3)
        .setIsMobile(true)
        .setHasTouch(true)
        .setUserAgent("Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"));

Test data that does not fight back

Most of the maintenance cost of an end to end suite lives in data. A few rules keep it manageable.

Create what the test needs, with names that cannot collide. Generate the identifying values: "ana-" + UUID.randomUUID() + "@example.test". Two tests running at once, or a test rerun after a crash that did not clean up, then never meet. A fixed email such as [email protected] works until the first rerun against a database that was not reset, and fails with a duplicate key that has nothing to do with the feature.

Build a small builder for the test data. A TestData class with methods like customer(), product(name, price) and orderFor(customer, product) makes fixtures a line each and gives you one place to change when a column is added. Back it with the application's repositories so it uses the real constraints, or with SQL scripts where speed matters most.

java
public record TestData(CustomerRepository customers, ProductRepository products, OrderRepository orders) {

    public Customer customer() {
        return customers.save(new Customer("ana-" + UUID.randomUUID() + "@example.test", passwordEncoder.encode("correct horse")));
    }

    public Order orderFor(Customer customer, Product... items) {
        return orders.save(Order.paid(customer, items));
    }
}

Decide how state is reset. A container per test class gives a clean database cheaply when the schema loads quickly. For a heavier schema, share one container and clean the tables the test touched in @AfterEach, or wrap each test in a database snapshot where the engine supports it. What you must avoid is a suite that passes only when run in a particular order against a database left dirty by earlier runs. Randomised order in CI exposes it early, which is why the JUnit setting junit.jupiter.testmethod.order.default=org.junit.jupiter.api.MethodOrderer$Random is worth turning on.

Keep time under control. Journeys that depend on dates, trial periods or schedules need a clock you can set. Expose a test only endpoint or a configuration hook that fixes the application clock, as in replacing java.util.Date with java.time and injecting a Clock, and set the browser's time zone and locale in the context.

Keyboard and accessibility checks in the same suite

Because Playwright interacts with the page as a user does, it can verify the parts of accessibility that are about interaction without extra tooling. A form that works only with a mouse is a defect for keyboard users, and a short test finds it:

java
@Test
void theLoginFormCanBeCompletedWithTheKeyboardOnly() {
    page.navigate(baseUrl + "/login");

    page.keyboard().press("Tab");
    assertThat(page.getByLabel("Email")).isFocused();
    page.keyboard().type("[email protected]");
    page.keyboard().press("Tab");
    assertThat(page.getByLabel("Password")).isFocused();
    page.keyboard().type("correct horse battery");
    page.keyboard().press("Enter");

    assertThat(page).hasURL(Pattern.compile(".*/dashboard"));
}

The test asserts the tab order and the submit on Enter, which are exactly the things that break when someone replaces a <button> with a styled <div>. Role based locators make a related check implicit: if getByRole(BUTTON, name = "Sign in") finds nothing, the element is not exposed to assistive technology as a button. For a broader automated scan, inject the axe-core script and evaluate it on the page, then assert that the list of violations is empty or matches an agreed baseline. Automated tools find a minority of accessibility problems, those with machine checkable rules such as missing labels and insufficient contrast, so treat the result as a floor, not a certification, and combine it with manual checks by someone who uses a screen reader.

Keeping the suite healthy over time

An end to end suite decays unless someone owns it. Four habits slow the decay.

Review a test failure as a product question first: did the application break, or did the intended behaviour change? A deliberate redesign that breaks fifteen tests is the signal to have fewer, higher level tests, since tests that mirror the DOM structure break with every layout change while tests that follow user intent survive.

Track the suite's health with numbers the team can see: total run time, failure rate per test over the last month and the list of tests that were retried. A test that fails once in twenty runs is costing more in distrust than it earns in coverage; fix it or delete it. Deleting a flaky test whose journey is covered elsewhere is a perfectly good outcome.

Treat the page objects and helpers as production code in review. A page object with copy pasted locators, or a helper with a hidden sleep, spreads the same defect into every test that uses it.

Budget the run time. Decide what the pull request pipeline can afford, perhaps ten minutes, and keep the pull request suite inside it by selecting the critical journeys, moving the rest to a nightly job. A suite that takes forty minutes stops being run before merging, and a suite nobody runs before merging does not protect anything.

Running against a deployed environment

Everything above starts the application inside the test, which gives the most control. Teams also run a small set of journeys against a deployed environment after each release, a smoke suite, to prove that the deployment, its configuration and its real dependencies work together. Three adjustments make that safe. Use dedicated test accounts and tenants, isolated from real customers, and mark their data so a cleanup job can remove it. Limit the suite to read mostly or reversible journeys, a login, a search, adding to a basket without paying, because a test that places real orders in a shared environment pollutes reports and can trigger real emails. And make the suite quick, under two minutes, since it sits on the critical path of the deployment: its job is to answer "did the release break the front door", not to repeat the regression suite. A failure should block the rollout or trigger an automatic rollback, which is only credible if the suite is reliable, which brings us back to the rules on flakiness above.

What belongs in an end to end suite

Browser tests are the most expensive tests you have: slow to run, costly to maintain and diagnose. Spend them on a handful of critical user journeys: sign up, sign in, the main purchase or core workflow, and any journey whose failure would be a business incident. Cover rules, calculations and edge cases below the browser, with unit tests for logic and MockMvc or API tests for the web layer, as in testing controllers with MockMvc and testing REST APIs with REST Assured. A useful ratio is hundreds of unit tests, dozens of integration tests and ten to thirty browser journeys. When a browser test fails, the investigation should start from a trace, and the fix often belongs to a lower layer: add the missing unit test, and the browser test stays as the safety net.

A question teams ask: Playwright or Selenium? Selenium has the longest history, the widest language and grid ecosystem and the WebDriver standard behind it. Playwright's auto waiting, tracing, isolated contexts and a single API for three engines give a better experience for most new Java projects, with the trade-offs that its browser builds are Playwright's own patched versions and its ecosystem for large scale grid execution is younger. Existing Selenium suites that work are rarely worth rewriting; new suites should start with Playwright.

A checklist for a suite you can trust

  1. Locators use roles, labels and text; test ids only where nothing else works.
  2. No sleeps, anywhere. Assertions that read page state use assertThat(locator).
  3. One browser per class, a fresh context per test, fixed locale, time zone and viewport.
  4. Test data created through code or API, unique per test, never through the UI unless that is the test.
  5. External services stubbed; the database real and disposable.
  6. Authentication state reused; one test for the login form itself.
  7. Traces recorded and uploaded when a test fails; flaky tests treated as defects.
  8. Suite size controlled: critical journeys only, with the detail below the browser.

A last word on ownership

A browser test suite stays healthy when someone owns it. Name an owner for the suite, review new tests in the same pull requests as the features they cover and delete tests when the feature goes. Treat a test that has to be rerun as an open defect with a due date. These habits cost little and are the difference between a suite the team trusts and one that gets switched off after the third false alarm.

When this does not apply

If the application is a pure API with no front end, browser tests have no role, and API tests carry the weight. If the front end is a small amount of server rendered HTML with no JavaScript, a MockMvc plus HTML assertion test may give most of the value at a fraction of the cost. For teams whose front end is developed in JavaScript, the front end repository's own Playwright tests (in TypeScript) are likely to be where end to end tests live, and the Java suite can focus on the back end. For the primary references, read the Playwright for Java documentation, the guidance on best practices and the trace viewer guide.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.