Skip to content
FrontDepth, Home

Testing

End-to-end tests with Playwright

What an end-to-end test proves and what it costs, and how to write Playwright tests that stay reliable: user-facing locators, auto-waiting and web-first assertions, isolated contexts and fixtures, signing in once with storageState, page.route, projects and CI, and debugging with traces.

JuniorMiddleSeniorUpdated 16 November 2026

Reading level

Shows sections up to the selected level.

This topic starts at Junior level.

JuniorConcept

What an end-to-end test proves

An drives the real app in a real browser, the way a user does: it opens a URL, clicks, types and checks what appears. Between the test and the result sits everything a user depends on: the production build, the router, the CSS, the browser itself, cookies and redirects, the API and the database behind it.

That is what makes E2E tests valuable. They catch problems that unit tests and in jsdom cannot see:

  • a button covered by a sticky banner or hidden by CSS, so a click never reaches it;
  • a broken route, a missing environment variable, a build that leaves out a chunk;
  • a form whose request the backend rejects because a field name differs;
  • a session cookie the browser does not send because of its SameSite or Secure attribute;
  • a feature that works in Chromium and breaks in WebKit, the engine behind Safari.

And it is what makes them expensive:

  • Slow. A browser starts, the app loads, real requests travel. A test takes seconds, not milliseconds, and a suite of hundreds takes minutes even in parallel.
  • More moving parts. Data in the database, network timing, animations and third-party scripts can all fail a test for reasons unrelated to the change. This is where most come from.
  • Vague failures. "The checkout test failed" can mean a bug in the UI, the API, the data or the test.
  • Setup. The app must run with a backend and test data, locally and in CI.

So E2E tests cover user journeys, not every case: signing in, the main flows that users come for (create, edit, pay, publish) and the paths that cross several systems. One test per journey proves that the parts are wired together. The edge cases of validation, formatting and error codes belong in faster tests. The test pyramid, which Martin Fowler describes, and Kent C. Dodds' testing trophy disagree about the middle layers, but both put E2E tests at the top: few of them, each one expensive.

An E2E test is worth the most when it fails rarely and for a real reason. The rest of this topic is about getting there: locators that find what users see, waiting that does not guess, and tests that cannot leak into each other.

JuniorFramework

A first test with Playwright Test

Shell
npm init playwright@latest

The command adds @playwright/test, a playwright.config.ts, an example test and, if you choose, a GitHub Actions workflow. npx playwright test runs the tests, by default headless and in parallel in Chromium, Firefox and WebKit; npx playwright show-report opens the HTML report.

TypeScript
// tests/tasks.spec.ts
import { test, expect } from "@playwright/test";

test("adds a task", async ({ page }) => {
  await page.goto("/tasks");

  await page.getByLabel("New task").fill("Write the release notes");
  await page.getByRole("button", { name: "Add task" }).click();

  await expect(page.getByRole("listitem").filter({ hasText: "Write the release notes" })).toBeVisible();
  await expect(page.getByRole("status")).toHaveText("1 task left");
});
  • page is a fixture: a fresh page that Playwright creates for this test.
  • page.goto("/tasks") takes a path when use.baseURL is set in the config (for example "http://localhost:3000"); the webServer option can start the app before the tests.
  • Locators describe how to find an element the way a user would. Playwright recommends getByRole (by role and ), getByLabel for form fields, getByText, getByPlaceholder, getByAltText, getByTitle, and getByTestId (the data-testid attribute) when nothing user-facing fits.
  • getByRole("button", { name: "Add task" }) matches the name as a case-insensitive substring by default; exact: true asks for a whole, case-sensitive match.
  • Locators are lazy: nothing is looked up until an action or assertion uses them, and every use finds the element again, so a re-render in between does no harm.
  • Locators are strict: an action on a locator that matches more than one element throws. Narrow it with filter({ hasText }) or by chaining (row.getByRole("button", { name: "Delete" })) instead of reaching for first().
  • Actions are methods on the locator: click(), fill(), check(), selectOption(), press(), hover(), setInputFiles().

Why roles and labels rather than CSS selectors: classes and DOM structure change with every redesign, while roles, names and labels change only when the UI the user sees changes. A role query also fails when a control has no accessible name, which is a real bug. npx playwright codegen <url> records your clicks as test code with role, text and test id locators; treat its output as a draft.

JuniorConcept

Auto-waiting and web-first assertions

Pages change asynchronously: a request finishes, a component renders, an animation ends. Playwright waits for the right condition instead of a fixed time.

before actions. Before click(), Playwright checks that the locator resolves to exactly one element and that the element is:

  • visible: it has a non-empty bounding box and no visibility: hidden;
  • stable: the same bounding box for at least two consecutive animation frames, so not mid-animation;
  • receiving events: it is the element the click would really hit, not something under an overlay;
  • enabled: not disabled.

fill() checks fewer things: visible, enabled and editable (not read-only). If the checks do not pass in time, the action fails with a TimeoutError. The force: true option skips the non-essential checks; use it rarely, because it can click through an overlay that would stop a real user.

Web-first assertions. await expect(locator).toBeVisible() does not check once: it retries until the condition holds or the expect timeout runs out, 5 seconds by default. The same is true of toHaveText, toContainText, toHaveValue, toHaveCount, toBeChecked, toHaveURL, toHaveTitle and the other locator and page assertions.

TypeScript
// Retries until the message appears, or 5 seconds pass
await expect(page.getByRole("status")).toHaveText("Task saved");

// Checks once, right now: flaky
expect(await page.getByRole("status").isVisible()).toBe(true);

The second line reads the state at one moment and compares a plain boolean, which never retries. Playwright's best practices show exactly this line as the one not to write.

Fixed waits are a smell. await page.waitForTimeout(2000) is too short on a slow CI machine and wasted time everywhere else. Playwright's API docs say it should only be used for debugging, because tests that wait for time are inherently flaky. Wait for something meaningful instead: an element, a text, a URL (await expect(page).toHaveURL(/\/tasks\/\d+/)) or a response.

Await every Playwright call. A forgotten await lets the test finish before the action or assertion runs, so it can pass without checking anything. Playwright's best practices recommend the @typescript-eslint/no-floating-promises lint rule to catch it.

The timeouts to know: a test has 30 seconds by default, an assertion 5 seconds, and an action has no timeout of its own, so it is limited by the test's.

MiddleFramework

Test isolation, browser contexts and fixtures

Every test gets a new browser context, which Playwright compares to a brand-new browser profile, with its own cookies and storage. The browser process is shared to save resources; the context is not. So tests do not see each other's sessions and can run in any order and in parallel. Test files run in parallel in separate worker processes (by default, half the logical CPU cores); the tests inside one file run in order unless fullyParallel is on. Workers cannot talk to each other.

A context isolates the browser, not your backend. If two tests edit the same record in the same database, they interfere however many contexts there are. Each test should create the data it needs, with unique names, and assume nothing that another test left behind.

Fixtures give a test what it needs. The built-in ones are page, context (the page's isolated context), browser (shared), browserName and request, an isolated API client for HTTP calls. Your own fixtures, made with test.extend, keep setup and teardown together, run only for the tests that ask for them, and can depend on other fixtures:

TypeScript
// tests/fixtures.ts
import { test as base, expect } from "@playwright/test";

type Project = { id: string; name: string };

export const test = base.extend<{ project: Project }>({
  project: async ({ request }, use) => {
    // Setup: create the data through the API, not the UI
    const response = await request.post("/api/projects", {
      data: { name: `Release ${crypto.randomUUID()}` },
    });
    expect(response.ok()).toBe(true);
    const project = (await response.json()) as Project;

    await use(project);

    // Teardown: runs after the test, even when it failed
    await request.delete(`/api/projects/${project.id}`);
  },
});

export { expect };
TypeScript
// tests/project.spec.ts
import { test, expect } from "./fixtures";

test("renames a project", async ({ page, project }) => {
  await page.goto(`/projects/${project.id}`);
  await page.getByRole("button", { name: "Rename" }).click();
  await page.getByLabel("Project name").fill("Q4 launch");
  await page.getByRole("button", { name: "Save" }).click();

  await expect(page.getByRole("heading", { level: 1 })).toHaveText("Q4 launch");
});

Code before await use(...) is the setup, code after it the teardown. The request fixture resolves paths against baseURL, like page.goto. Creating data through the API takes milliseconds instead of a dozen clicks, and the screen that creates projects gets its own test.

MiddleExample

Signing in once with storageState

Signing in through the form in every test is slow, and it makes the login form a single point of failure for the whole suite. Playwright's recommended approach is to sign in once in a setup project, save the browser's state to a file and start every test from it:

TypeScript
// tests/auth.setup.ts
import path from "node:path";
import { test as setup, expect } from "@playwright/test";

const authFile = path.join(__dirname, "../playwright/.auth/user.json");

setup("sign in", async ({ page }) => {
  await page.goto("/login");
  await page.getByLabel("Email").fill(process.env.E2E_EMAIL!);
  await page.getByLabel("Password").fill(process.env.E2E_PASSWORD!);
  await page.getByRole("button", { name: "Sign in" }).click();

  await expect(page).toHaveURL("/tasks");
  await expect(page.getByRole("button", { name: "Account" })).toBeVisible();

  await page.context().storageState({ path: authFile });
});
TypeScript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  use: { baseURL: "http://localhost:3000" },
  projects: [
    { name: "setup", testMatch: /.*\.setup\.ts/ },
    {
      name: "chromium",
      use: { ...devices["Desktop Chrome"], storageState: "playwright/.auth/user.json" },
      dependencies: ["setup"],
    },
  ],
});
  • The setup project runs first because chromium depends on it. Every test then gets a new context created from the saved state, so it starts signed in and still isolated.
  • storageState() saves cookies and local storage, and IndexedDB when you pass indexedDB: true. Session storage is not saved; Playwright has no API to persist it.
  • The file holds real session cookies that could be used to act as the test account: add playwright/.auth to .gitignore, and delete the file when the session expires.
  • Tests of the signed-out experience reset the state for their file: test.use({ storageState: { cookies: [], origins: [] } }).
  • Several roles: sign in once per role in the setup project (admin.json, user.json) and choose per file with test.use({ storageState: ... }). A test that needs two users at once, such as an admin approving what a user submitted, creates two contexts with browser.newContext({ storageState }).
  • One account per worker. A shared account is fine while tests do not change server-side state that others read. When they do, Playwright recommends a worker-scoped fixture that signs in a separate account for each worker, keyed by test.info().parallelIndex.

If the app can sign in with an API request, the setup can use request instead of the form; the login form then gets one ordinary test of its own.

MiddleFramework

Mocking the network with page.route, or not

An E2E test exists to check the real integration, so by default do not mock your own backend: a test that fakes your API is a slower component test, and it can drift from the real API like any mock. Playwright's best practices draw the line at what you do not control: avoid testing third-party dependencies and mock their responses with page.route. Mock when:

  • the dependency belongs to someone else: a payment provider, maps, a chat or analytics script; its outage should not fail your suite;
  • the state is hard to produce with the real backend: a 503, a dropped connection, a slow response.
TypeScript
test("shows a banner when the tasks API fails", async ({ page }) => {
  await page.route("**/api/tasks", (route) =>
    route.fulfill({ status: 503, json: { message: "Maintenance" } }),
  );

  await page.goto("/tasks");

  await expect(page.getByRole("alert")).toHaveText("Tasks are unavailable. Try again later.");
});

Register the route before page.goto(); requests sent earlier are not intercepted. What a handler can do:

  • route.fulfill({ status, json, headers, body }) answers without the network; json also sets the content type, and the status defaults to 200;
  • route.abort(errorCode) fails the request like a network error ("failed" by default, or codes such as "timedout" and "internetdisconnected");
  • route.continue() sends the request to the network, optionally with changed headers, method or URL;
  • route.fetch() performs the real request, so you can change the real response and pass it on with route.fulfill({ response, json }).

When several routes match, the one registered last runs first. route.fallback() hands the request to the next matching route, while route.continue() sends it straight to the network and skips the rest. Page routes take precedence over context routes, and { times: 1 } makes a route apply once. For a whole set of recorded responses, page.routeFromHAR() replays a HAR file.

Two caveats from the API docs. Enabling routing disables the HTTP cache, so a test of caching behaviour must not route those requests. And page.route does not see requests that a Service Worker intercepts; Playwright recommends serviceWorkers: "block" in use when you rely on interception. That matters if the app registers its own Service Worker, or if a mocking worker such as MSW's was left enabled in the build under test.

If you find yourself routing most of the app's API, the test has stopped being end-to-end. Move that case into a component test with network mocks and keep the E2E test on the real backend.

SeniorWeb platform

Projects, parallelism and CI

Projects run the same tests with different settings: browsers, emulated devices, or a setup step first. A typical config, with the CI settings Playwright's docs show:

TypeScript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "tests",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: process.env.CI ? "blob" : "html",
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
    { name: "mobile-safari", use: { ...devices["iPhone 12"] } },
  ],
  webServer: {
    command: "npm run start",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
  },
});

npx playwright test --project=webkit runs one project. A device entry sets the browser, viewport and user agent of that device; it is emulation, not a real phone.

  • forbidOnly fails the run if a test.only was committed by accident.
  • retries: failing tests are not retried by default. With retries, a test that fails and then passes is reported as flaky, not as passed, and a failure discards the worker process and its browser and starts a fresh one. Read "flaky" as a bug report: retries keep the pipeline moving, they do not fix anything.
  • workers: 1 on CI: Playwright's CI guide recommends it to prioritize stability and reproducibility. Teams with powerful CI machines run more workers.
  • Sharding spreads the suite across machines: npx playwright test --shard=1/4 up to --shard=4/4, each in its own CI job. With fullyParallel: true tests are distributed one by one; without it, whole files. Each shard writes a blob report, and npx playwright merge-reports --reporter html ./all-blob-reports turns them into one HTML report.
  • webServer starts the app before the tests; reuseExistingServer: !process.env.CI reuses your running server locally and always starts a fresh one on CI.
  • In the CI job, install the browsers with npx playwright install --with-deps (or only the ones you test, npx playwright install chromium --with-deps) and upload playwright-report/ as an artifact, so the report and its traces outlive the job.

Which browsers run on every pull request is a cost decision: often one on each pull request and the full matrix nightly. Include WebKit somewhere: it is Safari's engine, and its bugs are easy to miss when everyone develops in Chromium.

SeniorFramework

Debugging failures: traces, screenshots and UI mode

A red E2E test on CI usually says something like "Timed out 5000ms waiting for expect(locator).toBeVisible()". The question is why the element never appeared, and the answer is usually in the trace.

Traces record every action with DOM snapshots before, during and after it, plus network requests, console messages, errors and the source line. The trace option in use:

  • "on-first-retry": record when a failed test is retried for the first time; the setting in Playwright's examples, free while tests pass;
  • "on-all-retries": record every retry;
  • "retain-on-failure": record every test, keep the trace only when it failed;
  • "on": every test, which the docs call performance-heavy.

Open the HTML report (npx playwright show-report) and click the trace icon, or run npx playwright show-trace path/to/trace.zip. trace.playwright.dev opens a trace in the browser; it loads the file locally and sends no data anywhere.

What to look at, in this order:

  1. The failing action and its snapshots. Was the element there? Covered by a dialog? Behind a spinner? Still showing the old text?
  2. The Network tab. A 500, a slow API call or a request that never went out explains most missing elements.
  3. The Console tab. A JavaScript error that stopped rendering.
  4. The locator. The Actions tab shows the locator each action used; a locator that matched something else is a common cause.

screenshot: "only-on-failure" and video: "retain-on-failure" add pictures to the report, but Playwright's best practices prefer the trace viewer for CI failures: it shows the DOM, the network and the code, not only pixels.

Flaky failures need a different trace. With "on-first-retry", the trace comes from the retry; if the retry passed, you are looking at a passing run. Switch the test to "retain-on-failure" and run it many times, locally with npx playwright test --repeat-each=20 or on CI, until it fails with a trace. Compare the failing trace with a passing one: the difference is usually a response that arrived later, an element that re-rendered, or data another test changed.

Locally:

  • npx playwright test --ui opens UI mode: run and filter tests, watch mode, time travel through each step, pick a locator by hovering over the snapshot, and the network and console tabs.
  • npx playwright test --debug runs with the Playwright Inspector, so you can step through actions.
SeniorConcept

Keeping the E2E suite small and trustworthy

An E2E suite fails its purpose in two ways: it gets too slow to run on every change, or so flaky that a red run is ignored. Both are design decisions, not bad luck.

What stays out. Every validation message, every formatting rule, every API error code and every permission combination belongs in component tests with network mocks or in unit tests, where each case runs in milliseconds. An E2E test of a form checks that a valid submission goes through the whole stack and that one invalid input shows an error; the other rules are tested below. Third-party services, the internals of libraries and pixel-level styling (unless you run dedicated visual tests) stay out as well.

Data you own. Tests that share records interfere in parallel and break when the order changes. Create what each test needs in a fixture, through the API, with unique names, and delete it in the teardown. Run against an environment you control, such as a local stack or a dedicated test database, rather than a shared staging server that people change by hand. Avoid chaining tests with test.describe.configure({ mode: "serial" }): when one test fails, the rest of the group is skipped, and the whole group is retried together.

Flakiness is a bug. A test reported as flaky is telling you about a race: a missing wait for a response, an animation, shared data, a dependency on the clock or on the order of tests. Find it in the trace and fix the test or the app. A test you cannot fix now is quarantined openly, for example with test.fixme and a ticket, not left to fail at random until everyone stops reading the results.

Speed is a feature. Sign in once with storageState, create data through request instead of the UI, run with fullyParallel and shard on CI. If the suite takes longer than the team is willing to wait for a pull request, people start skipping it, and then it protects nothing.

One assertion of intent per journey. A test that checks fifteen things on the way is hard to read and fails for fifteen reasons. Assert what the journey is for (the order is placed, the invitation arrives), plus what the user must see along the way to get there.

The signs of a healthy suite: a red run is believed, a failure points to one journey, and a new feature adds one or two E2E tests, not ten.

SeniorInterview tips

Interview tips

A 30-second answer. "An E2E test runs the real app in a real browser, so it proves the pieces work together: build, routing, CSS, cookies, the API. It is slow and has more ways to fail, so I keep E2E tests for the critical journeys and test edge cases lower down. With Playwright I use role and label locators, rely on auto-waiting and web-first assertions instead of fixed waits, give each test fresh data through API fixtures, sign in once with storageState, and mock only third parties or hard-to-produce failures with page.route. On CI I record traces on the first retry and treat every flaky result as a bug."

Questions you are likely to get

  • Why not test everything end to end? Cost: seconds per test, more causes of flakiness, vague failures. Journeys in E2E, cases in faster tests.
  • How does Playwright avoid timing problems? Actionability checks before each action (visible, stable, receives events, enabled, editable), and assertions that retry until the expect timeout, 5 seconds by default. waitForTimeout is for debugging only.
  • How do you keep tests independent? A new browser context per test; unique data created through the API in fixtures; no reliance on test order or shared records.
  • How do you handle login? A setup project that signs in and saves storageState; projects depend on it; the file is git-ignored; per-worker accounts when tests change server-side state.
  • Do you mock the network in E2E? Not your own backend by default; third-party services and hard-to-produce failures with page.route, registered before navigation.
  • How do you debug a test that fails only on CI? The trace: snapshots, network, console, the locator used. For flaky tests, record with retain-on-failure and repeat until it fails.

Mistakes that cost points

  • waitForTimeout or expect(await locator.isVisible()).toBe(true) in examples.
  • CSS or XPath selectors when a role or label exists.
  • Calling retries a fix for flakiness.
  • Logging in through the UI in every test, or sharing one mutable account between parallel workers.

Senior signal

Talk about the suite, not only the test: which journeys deserve E2E coverage and which do not, how test data is created and cleaned up, which browsers run on every pull request and which nightly, how long the suite may take before people stop waiting for it, and how a flaky test is tracked until it is fixed.

JuniorReview checklist

What to check when reviewing end-to-end tests

Use this list when you review Playwright tests you did not write: a teammate's pull request, an example from a library, an AI assistant's suggestion. A weak E2E test rarely fails at once; it fails later, at random, on CI, and costs more time than it saves.

  • Are there fixed waits or one-shot checks? Search for waitForTimeout, isVisible() inside expect(...) and manual polling loops; replace them with web-first assertions such as await expect(locator).toBeVisible() or toHaveURL, which retry until the expect timeout.
  • Is every Playwright call awaited? A missing await lets the test end before the action or assertion runs; the @typescript-eslint/no-floating-promises rule and tsc on CI catch it.
  • Do the locators describe what the user sees? Prefer getByRole with a name, getByLabel and getByText over CSS classes, XPath or nth(); run the test after a harmless markup change in your head: would it still find the element?
  • Does each test create its own data? Look for records shared between tests, reliance on test order or mode: "serial"; data should come from a fixture or API call with unique names and be removed in teardown.
  • Does it sign in through the UI every time? Login belongs in a setup project with storageState; check that playwright/.auth is in .gitignore, because the file contains session cookies.
  • Is the network mocked only where it should be? page.route on your own API turns the test into a slow component test; it belongs on third-party services and hard-to-produce failures, registered before page.goto().
  • Does the test check a journey, not every edge case? Validation rules and error codes belong in faster tests; an E2E test should assert the outcome the user came for.

Check your understanding

  • Practice

    Predict-output and open interview questions with self-assessment.

    3 predict-output · 4 open

  • Quiz

    Multiple-choice questions with explanations and a score.

    7 questions