| | |

Playwright 01 ๐ŸŽญ Why Playwright โ€” Auto-waiting, fresh contexts & one API for three engines

โฑ๏ธ Estimated read: 10 min | |

Playwright exists because the two dominant E2E frameworks of the previous generation each solved one problem and left the other unsolved. Selenium gave cross-browser coverage but required manual waits and a separate driver per browser; Cypress gave an excellent developer experience but was Chromium-first and ran inside the browser’s event loop, which limited multi-tab and multi-origin scenarios. Playwright, released by Microsoft in 2020, combined the two: the cross-browser reach of WebDriver with the developer experience of a modern test runner, built on a browser automation protocol that can drive Chromium, Firefox, and WebKit from a single API.

This chapter covers the three properties that define Playwright’s position: the auto-waiting model that removes hard-coded timeouts, the browser-context isolation model that makes tests independent, and the single API that targets three rendering engines. The sections that follow walk through the mechanism behind each property and the failure mode it prevents.

Key point: Playwright’s value is not any single feature but the combination: a single API drives Chromium, Firefox, and WebKit; every action auto-waits for the element to be actionable; and every test runs in a fresh browser context that shares no cookies, storage, or cache with the next.


Why Playwright exists

The cross-browser problem. Selenium can drive Chromium, Firefox, and WebKit through the W3C WebDriver protocol, but each browser requires a separate driver and the API surface is the lowest common denominator. Cypress was Chromium-only for years, and its multi-browser support remains “improved” rather than native . Playwright was built against a single protocol that the Playwright team maintains for all three engines, so the same test code runs against Chromium, Firefox, and WebKit without driver configuration .

The flakiness problem. Hard-coded waitForTimeout calls are the primary source of flaky E2E tests. A test that sleeps for two seconds fails when the element takes three, and wastes two seconds when the element takes one. Playwright’s actions auto-wait for a set of actionability checks to pass before interacting, and its assertions auto-retry until the condition is met or the timeout expires . The test author writes what the user does, not how long to wait.

The isolation problem. A test that passes alone but fails in the suite is almost always leaking state from a previous testโ€”cookies, localStorage, a logged-in session, a cached response. Playwright’s test runner creates a fresh BrowserContext for every test by default. A context is equivalent to an incognito profile: its own cookies, storage, and cache, created in milliseconds and discarded when the test ends .


a. Auto-waiting and the actionability checks

Before Playwright performs an actionโ€”click, fill, selectโ€”it runs a set of checks on the target element. If any check fails, it waits and retries until the checks pass or the timeout expires. The checks are the definition of “actionable” .

For locator.click(), Playwright ensures that the locator resolves to exactly one element, the element is visible (non-empty bounding box, not visibility:hidden), stable (same bounding box for at least two animation frames), receives events (not obscured by an overlay), is enabled, and is not inert . A test that clicks a button while a loading overlay is present does not fail; Playwright waits for the overlay to disappear, then clicks.

// Without auto-waiting: a guess that may be too short or too long
await page.waitForTimeout(2000);
await page.click("#login");

// With Playwright: waits for the element to be visible, stable, and clickable
await page.getByRole("button", { name: "Login" }).click();

The same model applies to assertions. expect(locator).toBeVisible() is not a one-time check; it retries until the element is visible or the timeout expires . The combination of auto-waiting actions and auto-retrying assertions is what removes the waitForTimeout calls that make suites flaky.

The one case where auto-waiting is not enough is hydration. A server-rendered page can show an enabled button before the JavaScript that handles the click has loaded. Playwright will click it, and nothing will happen . The fix is to make interactive controls disabled until hydration completes, not to add a wait.


b. Browser contexts and test isolation

Playwright’s test runner creates a new BrowserContext for each test. A context is a lightweight, isolated environment inside the browserโ€”like an incognito windowโ€”with its own cookies, localStorage, sessionStorage, and cache . The browser process itself is reused across tests, so the cost of isolation is milliseconds rather than the seconds required to launch a new browser .

// What Playwright does for every test automatically:
const context = await browser.newContext(); // fresh, isolated
const page = await context.newPage();
// test runs here
await context.close(); // discarded

The isolation prevents the failure mode where a login test leaves a session cookie that makes the next test skip the login page. It also makes parallel execution safe: two tests running in parallel have separate contexts and cannot interfere with each other . The same mechanism supports multi-user scenarios in a single testโ€”a chat application can be tested with two contexts, one for each user, interacting independently .

The contrast is with a test suite that launches a new browser per test. That pattern is correct in its isolation but slow: launching Chromium, Firefox, or WebKit takes seconds, and repeating it for every test multiplies the suite’s runtime . The browser-per-worker, context-per-test pattern is the standard.


c. One API for three engines

Playwright’s API is identical across Chromium, Firefox, and WebKit. The same test file runs against all three by changing the projects configuration, not the test code . The engines are the rendering engines behind Chrome, Firefox, and Safari, so the cross-browser coverage includes WebKit, which Cypress and Selenium’s WebDriver approach support less reliably .

// playwright.config.ts
export default defineConfig({
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
});

The API includes device emulation for mobile viewports, permissions, locale, and color scheme, so the same test can run against a mobile Safari profile and a desktop Chrome profile without separate code . The trade-off is that the WebKit build Playwright ships is not identical to the Safari that ships with macOS; it is a framework-maintained build, and a bug that appears only in retail Safari may not reproduce . For teams that need to test against the exact browser the user has installed, Selenium remains the option that can drive a retail install .


Complete Example Session

// ============================================
// PART 1: THE TEST (SAME CODE FOR ALL ENGINES)
// ============================================
import { test, expect } from "@playwright/test";

test("user can log in and see the dashboard", async ({ page }) => {
  await page.goto("/login");

  // Auto-waits for the field to be visible and editable
  await page.getByLabel("Email").fill("user@example.com");
  await page.getByLabel("Password").fill("password123");

  // Auto-waits for the button to be stable and clickable
  await page.getByRole("button", { name: "Sign in" }).click();

  // Auto-retries until the dashboard heading appears
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
});

// ============================================
// PART 2: THE ISOLATION (AUTOMATIC)
// ============================================
// Test 1 logs in and sets a session cookie.
// Test 2 runs in a fresh context:
//   - no cookies from Test 1
//   - no localStorage from Test 1
//   - no cached responses from Test 1
// Test 2 cannot be affected by Test 1's state.

// ============================================
// PART 3: THE CROSS-BROWSER CONFIG
// ============================================
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
});
// The test file above runs three times, once per engine.

The example covered a test with no hard-coded waits, the automatic isolation between tests, and the configuration that runs the same test on three engines.


Quick Reference

The Three Properties

PropertyMechanismFailure It Prevents
Auto-waitingActionability checks before actionsFlaky waitForTimeout
Fresh contextsBrowserContext per testState leakage between tests
One APISame protocol for three enginesPer-browser driver config

Actionability Checks (click)

CheckMeaning
Resolves to one elementNo ambiguity
VisibleNon-empty box, not visibility:hidden
StableSame box for two animation frames
Receives eventsNot obscured by overlay
EnabledNo disabled attribute
Not inertNo inert ancestor

Isolation

AspectBrowserBrowserContext
What it isFull engine processIncognito-like profile
Cookies/storageSharedIsolated
CostSeconds to launchMilliseconds
UseOne per workerOne per test

Best Practices

โœ… Do This:

// Rely on auto-waiting
await page.getByRole("button", { name: "Submit" }).click();   // โœ…

// Use web-first assertions
await expect(page.getByText("Saved")).toBeVisible();          // โœ…

// Let the test runner create contexts
test("...", async ({ page }) => { ... });                     // โœ…

// Run the same test on three engines via config
projects: [chromium, firefox, webkit]                          // โœ…

โŒ Don’t Do This:

// Hard-coded waits
await page.waitForTimeout(2000); // flaky and slow              // โŒ

// Launch a browser per test
const browser = await chromium.launch(); // slow at scale      // โŒ

// Write per-engine test code
if (browserName === "firefox") { ... } // usually unnecessary   // โŒ

// Assume WebKit build equals retail Safari
// (it is a framework-maintained build)                       // โŒ

Common Pitfalls

PitfallWhy It HappensFix
Test passes alone, fails in suiteNo isolation (manual browser launch)Let the runner create contexts
Click does nothingPage not hydratedDisable controls until hydration
Test slower than expectedHard-coded waitsRemove waitForTimeout, use assertions
Safari-specific bug not caughtWebKit build differs from retailUse Selenium for retail Safari

Real-World Examples

1. Auto-waiting click

await page.getByRole("button", { name: "Login" }).click();

2. Auto-retrying assertion

await expect(page.getByText("Welcome")).toBeVisible();

3. Fresh context per test

test("...", async ({ page }) => { ... }); // context created automatically

4. Three-engine config

projects: [{ name: "chromium" }, { name: "firefox" }, { name: "webkit" }]

5. Multi-user in one test

const userContext = await browser.newContext();
const adminContext = await browser.newContext();

6. Device emulation

use: { ...devices["iPhone 15"] }

7. Locator with role

page.getByRole("heading", { name: "Dashboard" })

8. Avoid hard wait

// await page.waitForTimeout(1000) โ†’ await expect(...).toBeVisible()

9. Context isolation

// Each test: new cookies, new storage, new cache

10. Config for parallel

fullyParallel: true

Visual

Auto-Waiting Flow

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  locator.click()                                        โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Check: resolves to one element?                        โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Check: visible?                                        โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Check: stable? (two frames)                            โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Check: receives events?                                โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Check: enabled?                                        โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  Click                                                  โ”‚
โ”‚                                                         โ”‚
โ”‚  If any check fails: retry until timeout                โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Context Isolation

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  BROWSER (one per worker)                               โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”   โ”‚
โ”‚  โ”‚ Context A    โ”‚  โ”‚ Context B    โ”‚  โ”‚ Context C    โ”‚   โ”‚
โ”‚  โ”‚ Test 1       โ”‚  โ”‚ Test 2       โ”‚  โ”‚ Test 3       โ”‚   โ”‚
โ”‚  โ”‚ cookies: {}  โ”‚  โ”‚ cookies: {}  โ”‚  โ”‚ cookies: {}  โ”‚   โ”‚
โ”‚  โ”‚ storage: {}  โ”‚  โ”‚ storage: {}  โ”‚  โ”‚ storage: {}  โ”‚   โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜   โ”‚
โ”‚                                                         โ”‚
โ”‚  Each test isolated; browser reused                     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

One API, Three Engines

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  test file (same code)                                  โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚    โ”Œโ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                                  โ”‚
โ”‚    โ–ผ    โ–ผ            โ–ผ                                  โ”‚
โ”‚  Chromium  Firefox  WebKit                              โ”‚
โ”‚  (Blink)   (Gecko)  (WebKit)                            โ”‚
โ”‚                                                         โ”‚
โ”‚  Config chooses the engine; test code does not change.  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Hard Wait vs Auto-Wait

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  HARD WAIT                                              โ”‚
โ”‚  sleep(2000) โ†’ element ready at 500ms โ†’ waste 1500ms    โ”‚
โ”‚  sleep(2000) โ†’ element ready at 3000ms โ†’ FAIL           โ”‚
โ”‚                                                         โ”‚
โ”‚  AUTO-WAIT                                              โ”‚
โ”‚  click() โ†’ element ready at 500ms โ†’ click at 500ms      โ”‚
โ”‚  click() โ†’ element ready at 3000ms โ†’ click at 3000ms    โ”‚
โ”‚                                                         โ”‚
โ”‚  The test waits exactly as long as needed.              โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
Built byMicrosoft, open source
EnginesChromium, Firefox, WebKit
Auto-waitingActionability checks before actions
Auto-retrying assertionstoBeVisible, toHaveText, etc.
IsolationFresh BrowserContext per test
Context costMilliseconds
Hard waitsAnti-pattern
Retail browserSelenium can drive; Playwright uses maintained builds

Key takeaways:

  • Playwright’s cross-browser story is a single API. The same test runs on Chromium, Firefox, and WebKit by changing the config, not the code. The WebKit build is framework-maintained, not retail Safari .
  • Auto-waiting is the flakiness fix. Playwright checks that the element is visible, stable, receives events, and is enabled before acting. A test that clicks a button behind an overlay does not fail; it waits for the overlay to disappear .
  • The context is the isolation unit. Every test gets a fresh BrowserContext with its own cookies and storage. The browser is reused, so isolation costs milliseconds rather than seconds .
  • Hard waits are an anti-pattern. waitForTimeout is a guess that is either too short (flaky) or too long (slow). Web-first assertions wait exactly as long as the condition takes .
  • Hydration is the one case auto-waiting cannot solve. A server-rendered page can show an enabled button before its click handler loads. Playwright clicks it, and nothing happens. The fix is to disable controls until hydration, not to add a wait .

Remember: Playwright is not a better Selenium or a better Cypress in the abstract; it is the framework that combined cross-browser reach with the developer experience that made Cypress popular. The three propertiesโ€”auto-waiting, fresh contexts, one APIโ€”address the three failure modes that made E2E suites unreliable: flaky waits, state leakage, and per-browser configuration. Use the auto-waiting, let the runner create contexts, and run the same test on three engines. The failures that remain are usually hydration or a WebKit-specific bug that the maintained build does not reproduce.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!