Why are my Playwright tests flaky?

Playwright test flakiness almost always comes from race conditions between test code and the browser. The most common causes are clicking an element before it finishes animating, asserting text before a navigation or API response has completed, using fixed sleep() delays that are too short on slow CI machines, and elements that are visible in the DOM but intercepted by an overlay. Playwright's auto-wait handles most of these — flakiness usually means the test is bypassing auto-wait with a manual assertion or raw DOM query.

What is actionability in Playwright?

Actionability is the set of conditions Playwright verifies before performing any action. Before a click(), Playwright checks that the element is attached to the DOM, visible (non-zero bounding box, not hidden), stable (bounding box not changing between animation frames), enabled (not disabled), and not obscured by another element intercepting pointer events at its coordinates. These checks run inside the browser via CDP and retry on a polling interval until all pass or the timeout is reached.

How long does Playwright wait before a test times out?

The default action timeout is 30 seconds — the maximum time Playwright retries actionability checks before throwing a TimeoutError. The default assertion timeout for expect() web-first assertions is 5 seconds. Both are configurable: set them globally in playwright.config.ts via use.actionTimeout and use.navigationTimeout, per-test with test.setTimeout(), or per-action by passing a timeout option. Timeout errors include a detailed message explaining exactly which check failed.

What is the difference between Playwright auto-wait and a sleep?

A sleep pauses for a fixed duration regardless of what the browser is actually doing — it may be too short on slow CI and wastefully long on fast hardware. Playwright auto-wait evaluates real browser state by executing JavaScript inside the browser at the frame level. It retries on a polling interval and proceeds as soon as all actionability conditions pass — not after an arbitrary delay. Auto-wait is both faster on average and more reliable across different machine speeds.

What are web-first assertions in Playwright?

Web-first assertions are Playwright's expect() matchers designed for async browser state. They automatically retry until the condition is true or the assertion timeout is reached, instead of failing immediately. await expect(locator).toHaveText('Welcome') keeps checking until the text appears. Available matchers include toBeVisible(), toBeHidden(), toBeEnabled(), toHaveText(), toHaveValue(), and toHaveURL(). Always prefer web-first assertions over checking locator properties directly — they are retry-aware by design.

Stop Flaky Tests: Playwright Auto-Wait Internals

Infoveave Engineering Team·May 2026·Updated May 2026·13 min read

Most developers know Playwright "waits automatically." Few understand why it works — or why their tests still occasionally flake. This article goes deep on the internals so you can write tests that are truly rock-solid.

The Problem With Timing in Browser Tests

Imagine you're writing a test for a login form. You fill in the email, fill in the password, click submit, and then assert the dashboard heading is visible. Simple enough.

javascript

await page.fill('#email', '[email protected]');
await page.fill('#password', 'secret123');
await page.click('#submit');
await expect(page.locator('h1')).toHaveText('Welcome, Alice');

This test passes locally every time. Then it hits CI and fails intermittently — sometimes the h1 assertion runs before the dashboard has loaded, sometimes the click fires before the button is fully interactive after a slow animation. You add a sleep(1000) and move on.

Sound familiar?

This is the flakiness trap. And it's not your fault — it's a fundamental mismatch between synchronous test code and the asynchronous nature of the browser.

Playwright's auto-wait system was designed to eliminate this mismatch entirely. But to trust it — and to know when it won't save you — you need to understand how it actually works.

What "Auto-Wait" Actually Means

When most people hear "Playwright auto-waits," they assume it just polls for elements until they appear. That's too simple. Playwright runs a series of actionability checks before performing any action, and the checks vary depending on what action you're performing.

Here's the full set of actionability checks Playwright performs:

Check	Description
Attached	The element exists in the DOM (not detached)
Visible	The element has non-zero bounding box and is not `visibility: hidden` or `opacity: 0`
Stable	The element's bounding box has not changed between two consecutive animation frames
Enabled	The element is not disabled (`disabled` attribute or `aria-disabled`)
Editable	The element is not `readonly` (for `fill()` actions)
Receives events	No other element is overlapping and intercepting pointer events at the target coordinates

Not all checks apply to every action:

Action	Attached	Visible	Stable	Enabled	Editable	Receives Events
`click()`	Yes	Yes	Yes	Yes	—	Yes
`fill()`	Yes	Yes	Yes	Yes	Yes	Yes
`check()`	Yes	Yes	Yes	Yes	—	Yes
`hover()`	Yes	Yes	Yes	—	—	Yes
`focus()`	Yes	—	—	—	—	—
`selectOption()`	Yes	Yes	Yes	Yes	—	Yes

This is not guesswork or a sleep() loop. Playwright executes JavaScript inside the browser page to evaluate each of these conditions at the frame level, then retries until they all pass or the timeout is reached.

Inside the Engine: How Playwright Evaluates Actionability

Playwright communicates with browsers over the Chrome DevTools Protocol (CDP) for Chromium, and equivalent protocols for Firefox and WebKit. When you call page.click(selector), here's what actually happens internally:

Step 1 — Resolve the Locator to a DOM Element

Playwright evaluates your selector (CSS, role, text, etc.) against the current DOM. If the element doesn't exist yet, it retries on a polling interval (default: every 100ms) until the element appears or the timeout expires.

Resolve selector → element found? → if not, retry after 100ms

Step 2 — Run Actionability Checks in a Tight Loop

Once the element is found, Playwright injects a script into the page that evaluates all applicable actionability conditions in a single synchronous JavaScript call. This happens inside the browser process, not from the Node.js test runner side — which means no round-trip latency between checks.

The injected script looks roughly like this (simplified):

javascript

// This runs inside the browser, not in your test code
function checkActionability(element) {
  if (!element.isConnected) return { passed: false, reason: 'not attached' };

  const box = element.getBoundingClientRect();
  if (box.width === 0 || box.height === 0) return { passed: false, reason: 'not visible' };

  const style = getComputedStyle(element);
  if (style.visibility === 'hidden') return { passed: false, reason: 'visibility hidden' };
  if (parseFloat(style.opacity) === 0) return { passed: false, reason: 'opacity 0' };

  if (element.disabled) return { passed: false, reason: 'disabled' };

  const centerX = box.x + box.width / 2;
  const centerY = box.y + box.height / 2;
  const topElement = document.elementFromPoint(centerX, centerY);
  if (!element.contains(topElement)) return { passed: false, reason: 'element obscured' };

  return { passed: true };
}

Step 3 — The Stability Check Uses Animation Frames

The stability check is the most sophisticated. Playwright records the element's bounding box, then waits one animation frame (via requestAnimationFrame), and checks if the bounding box has changed. If it has, the element is still animating — Playwright waits another frame and checks again.

javascript

// Stability check pseudocode (runs inside browser)
const box1 = element.getBoundingClientRect();
await animationFrame(); // waits ~16ms
const box2 = element.getBoundingClientRect();

if (!rectsEqual(box1, box2)) {
  return { passed: false, reason: 'element is moving' };
}

This is why Playwright handles CSS transitions and animations correctly without you ever thinking about it. It's not waiting an arbitrary amount of time — it's literally watching the element stop moving.

Step 4 — Perform the Action

Once all checks pass, Playwright performs the action using CDP commands that simulate real user input — mouse events, keyboard events, touch events — dispatched through the browser's input handling pipeline. This is different from calling .click() on a DOM element from JavaScript, which bypasses event handling middleware.

The Timeout System

Every action in Playwright has a default timeout of 30 seconds. If actionability checks don't pass within that window, Playwright throws a TimeoutError with a detailed message explaining which check failed and why:

TimeoutError: locator.click: Timeout 30000ms exceeded.
=========================== logs ===========================
waiting for getByRole('button', { name: 'Submit' })
  locator resolved to <button disabled id="submit">Submit</button>
  element is not enabled - waiting...

Notice how the error tells you exactly what went wrong — the element was found but was still disabled. This is far more useful than a generic "element not found" error.

You can override the default timeout per-action, per-test, or globally:

javascript

// Per-action override
await page.getByRole('button', { name: 'Submit' }).click({ timeout: 5000 });

// Per-test override
test.setTimeout(60_000);

typescript

// playwright.config.ts — global overrides
export default defineConfig({
  timeout: 30_000,
  use: {
    actionTimeout: 10_000,
    navigationTimeout: 15_000,
  }
});

How `expect()` Assertions Auto-Wait Differently

Actions aren't the only thing that auto-waits. Playwright's expect() assertions also retry, but through a different mechanism called web-first assertions.

javascript

// This retries for up to 5 seconds by default
await expect(page.locator('h1')).toHaveText('Welcome, Alice');

Web-first assertions poll the DOM repeatedly, re-evaluating the locator and the condition on each attempt, until the assertion passes or the assertion timeout is reached (default: 5 seconds, configurable separately from action timeout).

Available web-first assertions include:

javascript

await expect(locator).toBeVisible();
await expect(locator).toBeHidden();
await expect(locator).toBeEnabled();
await expect(locator).toBeDisabled();
await expect(locator).toHaveText('Hello');
await expect(locator).toContainText('Hell');
await expect(locator).toHaveValue('[email protected]');
await expect(locator).toHaveAttribute('href', '/dashboard');
await expect(locator).toHaveCount(3);
await expect(page).toHaveURL('/dashboard');
await expect(page).toHaveTitle('Dashboard');

Critical distinction: locator.textContent() does NOT auto-wait for a condition — it returns whatever value is there right now. Always prefer expect(locator).toHaveText() over manual assertion patterns:

javascript

// Avoid — no retry, will flake
const text = await page.locator('h1').textContent();
expect(text).toBe('Welcome, Alice');

// Prefer — retries until the text matches or timeout
await expect(page.locator('h1')).toHaveText('Welcome, Alice');

What Auto-Wait Does NOT Cover — And Where Flakiness Still Sneaks In

Understanding the limits of auto-wait is just as important as understanding what it does.

1. Waiting for a Network Response

Auto-wait checks DOM state — it knows nothing about in-flight network requests. If your button is enabled but triggers a slow API call before updating the UI, Playwright won't wait for that API call automatically.

javascript

// May click before API response populates the dropdown
await page.getByRole('button', { name: 'Load Options' }).click();
await page.getByRole('combobox').selectOption('Option A');

// Wait for the network response explicitly
const responsePromise = page.waitForResponse('**/api/options');
await page.getByRole('button', { name: 'Load Options' }).click();
await responsePromise;
await page.getByRole('combobox').selectOption('Option A');

After a form submit that triggers a full page navigation, wait for the new page to load:

javascript

await Promise.all([
  page.waitForURL('/dashboard'),
  page.getByRole('button', { name: 'Login' }).click(),
]);

3. Dynamic Content Loaded After Scroll

If elements are virtualized (only rendered when scrolled into view), Playwright's locator won't find them until they're in the DOM:

javascript

await page.locator('.virtual-list-item').last().scrollIntoViewIfNeeded();

4. Conditions Based on Multiple Elements

If you need to wait until a count of elements reaches a certain number, use web-first assertions:

javascript

await expect(page.locator('table tbody tr')).toHaveCount(5);

5. Third-Party Scripts and Iframes

Auto-wait operates within the main frame. For cross-origin iframes, explicitly get the frame handle:

javascript

const frame = page.frameLocator('iframe[name="payment"]');
await frame.getByLabel('Card number').fill('4242 4242 4242 4242');

Debugging Auto-Wait: Seeing What Playwright Sees

Slow Motion Mode

Run actions in slow motion to watch what's happening:

typescript

// playwright.config.ts
use: {
  launchOptions: {
    slowMo: 500, // 500ms between each action
  }
}

Trace Viewer

Enable tracing to capture a full recording of the test run — DOM snapshots, network requests, and action log:

bash

npx playwright test --trace on
npx playwright show-trace test-results/trace.zip

The Trace Viewer shows exactly which actionability check was blocking and how long it took to pass.

Inspector Mode

Pause execution at any point and inspect the page interactively:

javascript

await page.pause(); // Opens Playwright Inspector

Verbose Logging

Set the DEBUG environment variable to see every internal step:

bash

DEBUG=pw:api npx playwright test

Best Practices: Writing Tests That Never Flake

Always use web-first assertions — never assert on raw values extracted with textContent(), getAttribute(), or inputValue() unless you have no choice.

Prefer role-based locators — getByRole, getByLabel, getByPlaceholder are more resilient and align with actionability semantics better than CSS selectors.

Never use page.waitForTimeout() — if you find yourself reaching for a fixed delay, that's a signal you need a proper waitForResponse, waitForURL, or expect() assertion instead.

Wait for state, not time — express what you're waiting for, not how long to wait:

javascript

// Avoid — always either too slow or too fast
await page.waitForTimeout(2000);

// Prefer — completes as soon as the condition is met
await expect(page.locator('.spinner')).toBeHidden();
await expect(page.locator('.results')).toBeVisible();

Use waitForLoadState for navigation-heavy tests:

javascript

await page.goto('/dashboard');
await page.waitForLoadState('networkidle'); // waits until no requests for 500ms

Putting It All Together: A Fully Reliable Test

Here's a real-world login test that applies everything above:

javascript

import { test, expect } from '@playwright/test';

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

  await page.getByLabel('Email address').fill('[email protected]');
  await page.getByLabel('Password').fill('secret123');

  await Promise.all([
    page.waitForURL('/dashboard'),
    page.getByRole('button', { name: 'Sign in' }).click(),
  ]);

  await expect(page.getByRole('heading', { level: 1 })).toHaveText('Welcome, Alice');
  await expect(page.getByTestId('user-menu')).toContainText('Alice');
});

No sleeps. No arbitrary timeouts. No fragile CSS selectors. Every wait is tied to observable browser state — and Playwright's engine handles all the timing internally.

Conclusion

Playwright's auto-wait system is not magic. It's a carefully engineered set of actionability checks — visibility, stability, enabled state, event receptiveness — evaluated inside the browser at the frame level, combined with a retry loop that gives the DOM time to settle. Understanding this gives you two things:

Confidence — you know why your test waited, not just that it did
Awareness — you know where auto-wait can't help, so you can add the right explicit waits in the right places

The result is tests that are fast when the app is fast, patient when it needs to be, and never blindly waiting on a timer.

References: Playwright Actionability Docs · Web-First Assertions

How We Use This at Infoveave

Infoveave's frontend test suite covers a multi-tenant analytics platform — dashboards, data pipeline configurations, form builders, and AI query flows. Every one of those interactions involves async data loading, conditional rendering, and state that changes in response to backend events. Playwright's auto-wait behaviour is what makes this test suite maintainable. The specific patterns in this article — using web-first assertions instead of waitForTimeout, explicitly waiting for network responses when backend timing is the variable, and reading trace files when a test flakes in CI — are patterns we've adopted after debugging real failures on real pipeline runs. If you're testing a data-heavy frontend, the complexity in this article is not academic.

About the Authors

This article was written by the Infoveave Engineering Team — building Unified Data Platform, agentic BI, and enterprise analytics infrastructure. Infoveave (by Noesys Software) helps organisations unify data, automate business processes, and act faster with AI-powered insights.

Visit infoveave.com Follow us on LinkedIn