What are web-first assertions in Playwright?

Web-first assertions are async assertion matchers provided by expect(locator) that wait and retry automatically until the expected condition is met or a timeout expires. They eliminate test flakiness caused by asynchronous rendering.

This answer is one piece of Chapter 11: Assertions.

Web-First Assertions Cookbook
Retry & Polling Patterns
Visual Regression Testing
Making a Failure Explain Itself

Modern web applications render asynchronously: elements appear, change attributes, and update text after API responses or CSS transitions finish. Traditional test runners evaluate assertions instantly on whatever is in the DOM right now, requiring manual sleep statements to avoid timing race conditions.

Playwright's web-first assertions, such as await expect(locator).toBeVisible() or await expect(locator).toHaveText('Success'), resolve this by continuously polling the target element until the expectation passes or the assertion timeout (default 5 seconds) is reached.

Because web-first assertions retry automatically, test suites remain fast and free of arbitrary sleep delays. If the condition is never met, Playwright provides a comprehensive failure log detailing every value observed across retries until timeout.

web-first-assertions.spec.js(https://practice.learnplayforge.com)

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

test('web-first assertions wait and retry until condition holds', async ({ page }) => {
  await page.goto('/catalog.html?mock=static&seed=42&autologin=1');
  const cartLink = page.getByTestId('cart-link');
  await expect(cartLink).toBeVisible();
  await expect(cartLink).toHaveText(/Cart/);
});

Output

1 passed (2.0s)

Test yourself

How do web-first assertions like await expect(locator).toBeVisible() handle elements that appear after an API response finishes?

Practised in the full course: the drill The assertion that isn't one.

See the chapter

AI can write the test now. The job is knowing whether it checks anything. That's what the course teaches, one chapter at a time.

163 lessons · 226 drills · start free

What are web-first assertions in Playwright?

Related questions