expect()

Playwright's expect builds on a familiar assertion API but adds async matchers integrated with the test runner's reporting and retry logic.

Async Matchers

Web matchers return promises. The test runner attributes failures to the exact line with locator logs showing matched elements.

Pass { timeout: 5000 } as second argument to override default for a single assertion.

await expect(page.getByRole('alert')).toBeVisible({ timeout: 5000 });
await expect(page.getByText('Loading')).toBeHidden();
await expect.poll(async () => {
  return await page.getByTestId('counter').innerText();
}).toBe('10');

expect.poll retries arbitrary async code until the matcher passes.

Matcher Syntax

await expect(subject).matcher()
await expect(subject).not.matcher()
await expect(subject).matcher({ timeout: ms })

Subject can be Locator, Page, APIResponse, or plain values.
.not inverts any matcher.
Timeout option applies to retry window for that assertion.
expect.configure creates pre-configured expect with defaults.

expect() Options

Control retry and behavior.

Feature	Usage
Per-assertion timeout	`toBeVisible({ timeout: 8000 })`
Negation	`not.toContainText('error')`
Polling	`expect.poll(fn).toBe(value)`
Soft	`expect.soft(locator).toBeVisible()`
Configure defaults	`expect.configure({ timeout: 7000 })`
Generic matchers	`toEqual`, `toMatch`, `toBeGreaterThan`

expect.poll for Custom Conditions

await expect.poll(async () => {
  const res = await page.request.get('/api/status');
  return res.status();
}).toBe(200);

Use when no built-in matcher fits — still gets retries.

Synchronous expect for Plain Values

Use Playwright's expect() for locators and API responses. For plain JavaScript values inside page.evaluate, standard expect from the same import works synchronously.

Common Mistakes

Mixing sync expect on values that change asynchronously without poll.
Using Jest-only matchers not available in Playwright.
Setting timeout to 60s everywhere masking real performance issues.
Soft assertions without reviewing all collected failures.

Key Takeaways

Web matchers are async — always await them.
Use timeout option and expect.poll for special retry needs.
.not and soft assertions extend flexibility.
Keep generic expect for computed values inside steps.

Pro Tip

When migrating from Jest unit tests, rename imports carefully — Playwright's expect is not drop-in for all Jest DOM matchers without @playwright/test.