6.4Web-First Assertions

Playwright's expect() assertions are "web-first" — they retry until the condition is met or the timeout expires. This is fundamentally different from instant assertions that check once and fail.

// Web-first: retries until text appears (up to 5s by default)
await expect(page.getByRole('alert')).toHaveText('Saved successfully');

// Instant assertion: checks once, fails immediately if not ready
// DON'T DO THIS:
const text = await page.getByRole('alert').textContent();
expect(text).toBe('Saved successfully'); // fragile!

Common Web-First Assertions

// Element state
await expect(page.getByRole('button')).toBeVisible();
await expect(page.getByRole('button')).toBeEnabled();
await expect(page.getByTestId('input')).toHaveValue('hello');
await expect(page.getByRole('alert')).toHaveText('Success');

// Page state
await expect(page).toHaveTitle(/Dashboard/);
await expect(page).toHaveURL(/\/dashboard/);

// Element count
await expect(page.getByRole('listitem')).toHaveCount(5);

// CSS and attributes
await expect(page.getByTestId('status')).toHaveClass(/active/);
await expect(page.getByRole('link')).toHaveAttribute('href', '/about');

Assertion Timeout

// Default timeout: 5 seconds. Override per assertion:
await expect(page.getByText('Report ready')).toBeVisible({ timeout: 30_000 });

// Or set globally in config:
// expect: { timeout: 10_000 }