Playwright

The shop’s twelve journeys in Playwright on one screen — the mechanism each one leans on

Nobody opens a page about Playwright for its history. They open it with a suite to write or a suite to fix, and the useful question is concrete: what does each journey need from the tool, and which part of the tool supplies it? Below are the twelve journeys from the End-to-end testing page — the same online shop, the same times — as the shop writes them in Playwright. The fourth column names the mechanism each journey leans on. The sections after the table explain where each mechanism comes from, and they cite the journeys by number and the config below by line.

The table says what each journey does. The config below says how all twelve run: where, in which browsers, how many at once, and what happens when one fails. Each line is a decision the shop made on purpose, and each has a section further down.

1. 1.Where it runs

   1. 1.1baseURL comes from the environment built for this merge from the artefact that ships — never a shared test server.
   2. 1.2timezoneId and locale are fixed, so a date and a price in euros format the same on every machine.
   3. 1.3Analytics, maps and the marketing chat are blocked with context.route() in a shared fixture: browser requests no journey’s outcome depends on.

2. 2.Projects

   1. 2.1setup signs the support agent in and saves the state to playwright/.auth/agent.json, which is in .gitignore.
   2. 2.2chromium runs all twelve journeys on every merge, after setup.
   3. 2.3webkit runs journey 2 on every merge and all twelve at night; firefox runs only at night.

3. 3.How many at once

   1. 3.1One journey per file, fullyParallel: true, workers: 4 on CICI/CDContinuous Integration / Continuous Delivery — automatic build, test and deliveryEvery commit is built and put through the tests automatically (CI), and a build that passes travels to the servers the same way (CD). The point is not automation for its own sake: it is that a breakage shows up in minutes instead of on release day.Full article →All terms — the size the test environment is built for.
   2. 3.2forbidOnly: true on CI, so a forgotten test.only fails the run instead of quietly skipping eleven journeys.

4. 4.When one fails

   1. 4.1retries: 1 on CI with retryStrategy: 'isolated', so a retry runs alone at the end, not beside the next journey.
   2. 4.2trace: 'on-first-retry', and the trace is uploaded as a build artefact.
   3. 4.3A journey reported flakyflakypasses and fails on the same codeA test that passes and fails on unchanged code. The real damage is not the failed run but what follows: once a suite has a few, people start re-running until green, and the suite stops being evidence of anything.Full article →All terms twice in a week goes to quarantine, the rule from Regression testing.
   4. 4.4@playwright/test is pinned to an exact version and upgraded in a change of its own, because an upgrade changes the browsers too.

One connection, out of process — and which browsers you are actually testing

Your test runs in a Node.js process of its own. Playwright launches a browser beside it and keeps one connection to that browser open for the whole run. For a browser it launched itself, the connection is a pipe between the two processes; to reach a browser on another machine, it is a WebSocketWebSocketa connection kept open both waysA connection that stays open in both directions: unlike HTTP, the server can send a message on its own without waiting to be asked. Chats and live feeds are built on it, and so is most of what looks like the page updating by itself.All terms. Every instruction goes down that connection, and every event comes back up it. For Chromium the language on the wire is the Chrome DevTools ProtocolChrome DevTools Protocolhow tools drive ChromeThe protocol Chrome’s developer tools use to inspect and control the browser, open to any program that connects to it. Test tools such as Playwright and Puppeteer drive Chromium through it, so they see the browser’s state directly rather than through the page.All terms. For Firefox and WebKit, Playwright ships builds of its own, patched to speak its protocol.

That one arrangement explains the tool’s best-known properties. Because the driver sees the browser’s state directly rather than through the page, it can inspect an element before acting on it and wait until acting makes sense — section 3. Because everything crosses one connection, the whole run can be recorded and opened afterwards — section 6. And because the unit of isolation is a browser context rather than a browser, a clean session costs milliseconds instead of a browser launch, which is what makes real parallelism affordable — section 4.

The patches explain a fact that surprises people. Playwright does not drive the Firefox or the Safari installed on your machine: its documentation says it “doesn’t work with the branded version” of either, “since it relies on patches”. And “Chromium” means different binaries in different modes. The table is what actually runs.

Auto-waiting: six checks before every action, and the two things they cannot fix

The commonest reason a browser test is unreliable is that it acted or checked before the application was ready. In 2021 Romano and colleagues read 235 flaky UIUIUser Interface — what the user seesEverything the user sees and operates: screens, buttons, fields, states. UI is how the interaction looks; whether the interaction makes sense in the first place is a UX question, and the two get confused constantly.All terms tests from 62 web and Android projects and traced each to its cause. 105 of them, 45.1%, were waiting problems, and in the web projects alone the share was 52%. Older tools answered this with sleeps and hand-written waits, which is a guess dressed up as code. Playwright answers it with checks it runs before every action, against the element as it is at that moment, and repeats until they pass or the action times out.

The second half of the model is the locator. A locator is not an element. It is a description of how to find one, resolved again every time it is used, so on a page that re-renders underneath the test it finds the current element rather than holding a node that no longer exists. Assertions on a locator work the same way: they retry until the condition holds, for five seconds by default. For a condition that is not on the page at all — an email in a test inbox, a record in the warehouse — expect.poll repeats a function until its result passes, which is how journeys 3 and 9 wait without a single sleep.

Contexts, workers and the four-minute run

Every test gets a fresh browser context by default: no shared cookie, no leftover storage, no order dependency between journeys. This is the quiet reason Playwright suites stay stable as they grow. The commonest source of “it passes alone and fails in the suite” is removed by the default rather than by discipline.

Parallelism comes from workers. A worker is an operating-system process with its own browser; workers cannot talk to each other, and one is shut down after any test failure, so the next test never inherits a broken browser. Test files run in parallel across workers, while the tests inside one file run in order in one worker — unless fullyParallel is on. The shop keeps one journey per file and turns it on anyway (config line 3.1), so the unit the scheduler hands out is one journey.

• Sign in once, reuse everywhere

  A setup project signs in and saves the storage state; tests that need that identity start with it. The documentation recommends it for tests that do not change server-side state, and one account per worker for tests that do.

• Fixtures instead of setup code

  A fixture is a named thing a test asks for — a signed-in page, a seeded order, an API client. It is built on demand and torn down after, so a journey declares what it needs instead of arranging it.

• Locks for what cannot be shared

  Since 1.63 a test can hold a named lock: tests that share it never run at the same time, across files, workers and projects, while everything else stays parallel. It is for the one external account that cannot take two writers.

• Shards, and shuffling to find a dependency

  The same suite splits across CI machines with --shard=1/3, and the reports merge afterwards. Since 1.64, --shuffle runs tests in a random order with a seed to repeat it, which flushes out a test that quietly depends on another.

What a test can reach besides the page — and where the reach ends

Three capabilities beyond clicking change what belongs in a journey at all. The first is the API client. The request fixture sends requests from the test, and page.request shares the browser context’s cookies in both directions, so a journey can arrange its state over the API in fifty milliseconds and then check one thing in the browser. The second is network routing: requests the page makes can be observed, delayed, answered from a recorded HAR file or blocked. The third is the clock, which replaces the page’s Date, timers and animation frames with a clock the test controls.

A failure you can open: traces, retries and the flaky label

The expensive part of an end-to-end failure is rarely the failure. It is the hour spent trying to reproduce it on a laptop where it does not happen. The trace is the answer, and it is the setting worth getting right before any other. A trace records every action with a snapshot of the page before and after it, the network log, the console and the source line. The shop records one on the first retry (config line 4.2) and uploads it with the build. It opens locally or at trace.playwright.dev, which, the documentation says, loads the trace entirely in the browser and transmits nothing.

The trace in the diagram is journey 9 on a Tuesday. Its first attempt failed; the retry passed, so the report says flaky — and the retry is the run the shop records a trace for. It shows the refund on the page at 1.4 seconds, so the shop did its job. It shows the inbox poll coming back empty eight times and the email arriving at 4.6 seconds, against the poll’s default limit of 5.0. The first attempt simply ran out of those last 0.4 seconds. Nobody had to reproduce anything, and the diagnosis is the timeout, not the product. The fix is a limit written for the condition — 15 seconds, because the email pipeline’s 99th percentile is about nine — and never a sleep in front of the poll.

Retries are where a suite quietly lies. Playwright labels a test that failed and then passed on retry as “flaky” rather than “passed”, and by default the run still exits green; --fail-on-flaky-tests makes it red. The shop keeps one retry, runs it alone at the end with retryStrategy: 'isolated' so a retry does not compete with the next journey for the environment, and counts the flaky labels as a signal of their own (config lines 4.1 and 4.3). Since 1.57 the HTML report also has a Speedboard tab that sorts tests by slowness — the first place to look when four minutes becomes seven.

• Use the interactive mode, --ui, while writing a journey: the run pauses, the locator under the cursor is highlighted, and another one can be tried against the live page.
• Treat recorded code as a draft. Recording a flow produces working locators fast, and they are almost always more brittle than the ones you would choose deliberately.
• Since 1.56 Playwright ships three agent definitions for coding assistants: a planner that explores the app and writes a test plan, a generator that turns the plan into tests, and a healer that runs the suite and repairs failing tests.

Four changes underneath working suites

None of these is a scandal. Each is a dated change in Playwright or in the browsers under it, published by the people who made it, and each one sorted the suites that had pinned and upgraded on purpose from the ones that had not. They are here because a browser test depends on more than its own code, and these four show where.

Where it does not help, and how it compares

Playwright is the reasonable default for a new browser suite in 2026, and a default deserves its caveats stated plainly rather than discovered in month three.

• WebKit is not Safari. It is the same engine, patched and built from WebKit’s main branch, without Apple’s browser around it — it catches engine differences, and not everything specific to the Safari customers run.
• Mobile emulation is a screen size, a user agent and touch — not a device. It finds layout problems and will not find a bug in a real mobile browser.
• Its reach ends at the browser’s side of the network. Calls between servers and the server’s own clock belong to the environment, not to the test.
• It does not test native desktop or mobile applications, and it is not a load testing tool, however tempting a hundred parallel contexts look.
• It makes flaky tests less likely; it does not make a badly chosen suite good. Four hundred end-to-end cases are wrong here for exactly the reasons they are wrong anywhere else.

Anti-patterns worth naming

• Explicit waits “just in case” on top of auto-waiting, which slow the suite and hide the real timing question.
• Locators by CSS class or DOM position because the recorder produced them, which turns every redesign into a day of test repair.
• One context reused across tests to save time, which brings back the order dependency the tool was designed to remove.
• Retries raised until the pipeline is green, which converts real intermittent defects into passing runs.
• An unpinned @playwright/test, so the browsers change on a day nobody chose.
• Unit-level logic moved into browser tests because the tooling is pleasant — the most expensive way there is to be thorough.

When to use it

Related pages

• QACypressCypress is an open-source test runner for web applications that runs the test inside the browser, in the same tab and event loop as the application. The page opens with the twelve journeys from End-to-end testing as the shop would write them in Cypress — seven native, five that need a workaround, and the one thing all five have in common — then covers the tab and the four trade-offs Cypress calls permanent, the command queue, retry-ability as it has worked since Cypress 12, isolation and the Node side, parallelism by spec file, four changes underneath working suites, and where it does not help.
• QASeleniumSelenium is an open-source set of browser automation tools built on W3C WebDriver, a standard that browser vendors implement in drivers of their own. The page opens with the twelve journeys from End-to-end testing written in Selenium — who supplies each — and the one run only Selenium can add to the shop’s suite: the browsers customers actually install, Safari on an iPhone included. Then the protocol and its drivers, waiting, sessions and the lane one Mac sets, WebDriver BiDi, the grid and its open door, five changes underneath working suites, and where it does not help.
• QAEnd-to-end testingEnd-to-end testing walks a business process through the assembled system from start to finish, the way a customer would, in conditions close to production. The page opens with one shop’s whole suite — twelve journeys, the seam only each one proves, and what is real and what is replaced — then covers what no lower level can prove, the shapes a portfolio takes, what a red journey costs, how to choose journeys and keep them trustworthy, and three failures where a test stopped one step short.