Playwright web-first assertions: stop flaky UI waits

Use locator assertions, not fixed sleeps, for UI state

Playwright's web-first assertions retry automatically. When you write expect(page.locator('.status')).toHaveText('Saved'), Playwright does not check the DOM once and fail immediately. It re-queries the locator, waits for actionability, and evaluates the text repeatedly until the condition passes or the assertion timeout expires. This removes most page.waitForTimeout() calls and makes tests less sensitive to network or rendering delays.

How the retry mechanism works

A web-first assertion is any expectation called on a Playwright locator through Playwright's expect, such as toBeVisible(), toBeEnabled(), toHaveText(), or toHaveCount(). The loop works like this:

1. Playwright resolves the locator to an element in the current DOM.
2. It runs actionability checks: the element must be visible, stable, enabled, and able to receive events.
3. It evaluates the actual assertion, such as comparing visible text.
4. If any step fails, Playwright waits briefly and repeats from step 1 until the timeout expires.

Actionability means the browser can realistically interact with the element. A hidden button or an element covered by a loading overlay fails this check, so the assertion keeps waiting instead of passing on a stale or invisible target.

Worked configuration

Create or open a test file in your Playwright project, for example tests/save-status.spec.ts. Run commands from the project root where Playwright is installed. No special operating-system permissions are required beyond reading and writing project files.

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

test('displays saved status after submit', async ({ page }) => {
  await page.goto('https://example.com/form');

  await page.locator('button#submit').click();

  await expect(page.locator('.status')).toHaveText('Saved');
});

Replace button#submit, .status, and 'Saved' with selectors and text from your application. The placeholder { page } is Playwright's test fixture; do not construct page yourself in the test body.

To change the timeout for every test in a file, add this at the top:

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

expect.setTimeout(10000);

Playwright's default assertion timeout is five seconds in many releases; check your installed version before relying on that number. Ten seconds is often more realistic for slow networks without masking real failures.

Expected check: run npx playwright test tests/save-status.spec.ts. If the element shows Saved within the timeout, the test passes. If the text never appears, Playwright fails with a timeout message that includes the last observed state and elapsed retry time.

Risk: setting the timeout too high makes genuinely broken features fail slowly, which wastes CI time. Tune the value per suite instead of using one long timeout everywhere.

What does not auto-retry

Only locator-based expectations retried by Playwright's expect benefit from this behavior. Standard Node assertions do not:

// Does NOT retry. Fails immediately if the value is wrong.
expect(1 + 1).toEqual(2);

Likewise, importing expect from Node's assert module or from another test runner while using Playwright locators disables the retry policy. Always import expect from @playwright/test when you want auto-retrying UI assertions.

Limits and common mistakes

• Auto-retry can hide performance problems. A test that passes only after eight seconds of retries may indicate a slow API or render path. The test is green, but the user experience is not.
• Asserting a detached element can fail. If the application removes and recreates the DOM node after you click, the locator may resolve to a stale element. Playwright re-queries, but if the element never becomes actionable, the assertion times out.
• Using the wrong expect. Mixing Playwright's test fixture with a non-Playwright assertion library removes retries and causes intermittent failures.
• Long default timeouts slow failing tests. A 30-second default means every negative test waits 30 seconds before reporting failure.

Verify before relying on the behavior

Playwright APIs and defaults can change between major releases. Check your installed version first:

npx playwright --version

Then confirm retries in a controlled way:

1. Run the test with debug output: npx playwright test tests/save-status.spec.ts --debug.
2. Open the trace viewer after the run and inspect the assertion step. You should see the locator re-evaluated as the DOM changes.
3. Temporarily change the expected text to a wrong value, such as 'Not Saved', and run the test. The failure message should show the timeout elapsed and the last observed text, confirming the retry loop ran rather than failing immediately.
4. Change the text back and remove any temporary debug changes before committing.

No rollback is required because this change modifies test code only; it does not alter production data or infrastructure.

Version assumptions

This guide describes Playwright's web-first assertion behavior in current stable releases. Method names and default timeouts can differ between major versions, so consult the documentation for your installed release before adopting suite-wide timeout changes.