End-to-end testing with Playwright

01Where E2E fits in the testing pyramid

The testing pyramid has many fast unit tests at the bottom, fewer integration tests in the middle, and a small number of E2E tests at the top. E2E tests are the most realistic but also the slowest and most expensive to maintain, so use them for critical journeys: sign up, log in, search, add to cart, checkout, password reset, key admin actions. Do not test every validation message through the browser; that belongs in unit or component tests. A healthy suite has tens to a few hundred E2E tests that run in minutes in parallel, and each one protects something that would hurt users or revenue if it broke.

02Setup and your first test

Install with npm init playwright@latest, which creates a config, an example test and a GitHub Actions workflow, and downloads browsers. A test is an async function receiving fixtures; the most important is page, a fresh browser tab in an isolated browser context (like a new incognito profile) for every test. Locate elements with user-facing locators such as getByRole, getByLabel and getByText, act on them, and assert with expect. Playwright waits automatically for elements to be visible, enabled and stable before clicking, and web-first assertions such as toBeVisible and toHaveURL retry until they pass or time out. You almost never need manual waits.

1import { test, expect } from "@playwright/test";
2 
3test("user can search and open a product", async ({ page }) => {
4  await page.goto("/");
5  await page.getByRole("searchbox", { name: "Search" }).fill("running shoes");
6  await page.getByRole("button", { name: "Search" }).click();
7 
8  const results = page.getByRole("listitem").filter({ hasText: "Trail" });
9  await expect(results.first()).toBeVisible();
10 
11  await results.first().getByRole("link").click();
12  await expect(page).toHaveURL(/\/products\//);
13  await expect(page.getByRole("heading", { level: 1 })).toContainText("Trail");
14});

03Locators that survive redesigns

Flaky and brittle tests usually come from bad selectors. A CSS path like div > div:nth-child(3) > button breaks when a designer adds a wrapper. Prefer locators that reflect what users and assistive technology see: getByRole with an accessible name first, then getByLabel for form fields, getByPlaceholder, getByText, and getByTestId as an explicit contract when nothing else is stable. Locators are lazy and strict: they are re-evaluated on each action, and if one matches several elements, Playwright throws instead of clicking the wrong one. Chain and filter locators to scope them, for example a row containing a specific order number. A bonus: role-based locators push the app toward better accessibility.

• Good: page.getByRole("button", { name: "Place order" })
• Good: page.getByLabel("Email")
• Avoid: page.locator(".btn.btn-primary:nth-child(2)")

04Configuration, projects and authentication

playwright.config.ts defines the base URL, browsers (projects), retries, reporters and how to start the app. A common pattern is a setup project that logs in once and saves the browser storage state (cookies and localStorage) to a file; other projects reuse it, so most tests start already authenticated without repeating the login UI. webServer starts your app before tests and waits for it. Keep traces for failed retries, which gives you a full recording to debug CI failures. Do not commit the saved auth file; add the folder to .gitignore.

1import { defineConfig, devices } from "@playwright/test";
2 
3export default defineConfig({
4  testDir: "./e2e",
5  fullyParallel: true,
6  forbidOnly: !!process.env.CI,
7  retries: process.env.CI ? 2 : 0,
8  reporter: [["html"], ["list"]],
9  use: { baseURL: "http://localhost:3000", trace: "on-first-retry" },
10  projects: [
11    { name: "setup", testMatch: /.*\.setup\.ts/ },
12    { name: "chromium", dependencies: ["setup"],
13      use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/user.json" } },
14    { name: "mobile", dependencies: ["setup"],
15      use: { ...devices["iPhone 15"], storageState: "playwright/.auth/user.json" } },
16  ],
17  webServer: { command: "npm run start", url: "http://localhost:3000", reuseExistingServer: !process.env.CI },
18});

05Fixtures and page objects

Fixtures are Playwright's dependency injection: a test declares what it needs (page, request, or your own fixture such as a logged-in admin or a seeded product) and Playwright sets it up and tears it down around the test. Custom fixtures replace beforeEach chains and keep tests short. Page object models wrap the locators and actions of a page in a class, so a UI change is fixed in one place. Keep page objects thin: they expose actions in user language (addToCart, checkout) and leave assertions to tests. Use the request fixture to create test data through the API, which is much faster than clicking through the UI.

1import { test as base, expect } from "@playwright/test";
2 
3type Fixtures = { product: { slug: string } };
4 
5export const test = base.extend<Fixtures>({
6  product: async ({ request }, use) => {
7    const res = await request.post("/api/test/products", { data: { name: "E2E shoe", price: 50 } });
8    const product = await res.json();
9    await use(product);                                   // run the test
10    await request.delete("/api/test/products/" + product.slug); // clean up
11  },
12});
13 
14test("product page shows price", async ({ page, product }) => {
15  await page.goto("/products/" + product.slug);
16  await expect(page.getByTestId("price")).toHaveText("$50.00");
17});

06Debugging and CI

Playwright ships strong tools. npx playwright test --ui opens UI mode with a watch mode and time-travel through each step. --debug opens the inspector to step through actions. codegen records your clicks into a test, a good starting point you then clean up. The trace viewer shows every action, DOM snapshot, network request and console log of a failed test, which is how you debug CI failures without reproducing them locally. In CI, install browsers with npx playwright install --with-deps, run in parallel with workers, split large suites across machines with --shard, and upload the HTML report and traces as artifacts. The official Docker image contains all browser dependencies.

1# .github/workflows/e2e.yml (steps)
2- uses: actions/checkout@v4
3- uses: actions/setup-node@v4
4  with: { node-version: 22, cache: npm }
5- run: npm ci
6- run: npx playwright install --with-deps
7- run: npx playwright test --shard=${{ matrix.shard }}/4
8- uses: actions/upload-artifact@v4
9  if: ${{ !cancelled() }}
10  with: { name: report-${{ matrix.shard }}, path: playwright-report/ }

07How Playwright drives browsers

Playwright runs your test code in Node.js and talks to browsers over a persistent connection: the Chrome DevTools Protocol for Chromium and its own patched protocols for Firefox and WebKit. This out-of-process design lets one test control several pages, contexts and even browsers, and observe network traffic directly. Browser contexts are cheap, isolated sessions inside one browser process, which is why each test can get a fresh context in milliseconds. Playwright pins specific browser builds to each release; since 1.57 it uses Chrome for Testing builds for Chromium, and you install them with npx playwright install. You can also run against branded Chrome or Edge with the channel option for extra confidence.

08Network control: mocking, HAR and API testing

page.route intercepts requests matching a URL pattern so you can fulfil them with fixed data, modify them, or abort them to simulate failures. That is how you test “payment provider is down” without breaking a real provider. routeFromHAR replays recorded traffic for stable demos or offline tests. The request fixture is a full HTTP client that shares cookies with the browser context if you want, so you can create data, call internal endpoints, or write pure API tests in the same framework. Combine them: create an order through the API, then verify the UI shows it, which is fast and checks both layers.

1test("shows a friendly error when payments fail", async ({ page }) => {
2  await page.route("**/api/payments/intent", (route) =>
3    route.fulfill({ status: 503, json: { error: "unavailable" } }),
4  );
5  await page.goto("/checkout");
6  await page.getByRole("button", { name: "Pay now" }).click();
7  await expect(page.getByRole("alert")).toContainText("try again");
8});

09Visual regression testing

expect(page).toHaveScreenshot() captures a screenshot and compares it with a stored baseline pixel by pixel, failing if the difference exceeds a threshold. The first run creates the baseline; update it intentionally with --update-snapshots. Screenshots differ across operating systems and font rendering, so generate and compare baselines in the same environment, usually the official Playwright Docker image in CI. Reduce noise: mask dynamic areas (dates, ads, avatars) with the mask option, disable animations, wait for fonts, and screenshot specific components instead of full pages where possible. Accessibility snapshots with toMatchAriaSnapshot compare the accessibility tree as text, which is less brittle than pixels and catches structural regressions.

1await expect(page).toHaveScreenshot("checkout.png", {
2  fullPage: true,
3  mask: [page.getByTestId("order-date"), page.locator(".promo-banner")],
4  animations: "disabled",
5  maxDiffPixelRatio: 0.01,
6});

10Scaling a suite: parallelism, sharding and flakiness control

Playwright runs test files in parallel across worker processes by default; fullyParallel also parallelises tests within a file. Each worker gets its own browser, so tests must not share mutable data: create unique records per test or use worker-scoped fixtures that create one account per worker (testInfo.workerIndex helps). In CI, shard across machines with --shard=1/4 and merge the blob reports with npx playwright merge-reports into one HTML report. Track flakiness: a test that passes on retry is reported as flaky; review that list weekly and fix the root cause, usually shared state, missing awaits or animations. --repeat-each and --fail-on-flaky-tests help reproduce and enforce. Recent versions also offer AI-assisted test agents that plan, generate and heal tests, which still need review.