How do I change the assertion timeout in Playwright?

Pass { timeout: ms } to a single assertion, or set expect: { timeout: ms } in playwright.config.js to change the default for every assertion. The default is 5 seconds.

This answer is one piece of Chapter 11: Assertions.

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

Web-first assertions such as toBeVisible() retry until they pass or their timeout runs out. That timeout is 5 seconds unless you change it, and it is separate from the 30-second test timeout.

There are two places to change it:

One assertion: await expect(locator).toBeVisible({ timeout: 10_000 }). Use this when one element is known to be slow.
Every assertion: expect: { timeout: 10_000 } at the top level of the config. Use this when the whole app is slow, for example in a shared test environment.

Prefer the first. Raising the global default makes every genuine failure take longer to report.

In the example, ?delay=6000 makes the dashboard's backorders figure appear after roughly 6.8 seconds. With the default 5 seconds, the assertion gives up first; when we ran it without the option, it failed at about 5.3 seconds. With { timeout: 10_000 } it waits long enough and passes. The fix is a longer wait on that one check, not a fixed sleep.

slow-kpi.spec.js(https://practice.learnplayforge.com)

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

test('a KPI that arrives after 5 seconds needs a longer assertion timeout', async ({ page }) => {
  // ?delay=6000 makes the backorders KPI arrive at roughly 6.8 seconds
  await page.goto('/index.html?mock=static&seed=42&delay=6000');

  await expect(page.getByTestId('kpi-backorders-value')).toBeVisible({ timeout: 10_000 });
});

Output

1 passed (8.5s)

Test yourself

Nothing in your config mentions timeouts. How long does await expect(locator).toBeVisible() keep retrying?

Practised in the full course: the drill Waiting: The Default Timeout.

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

How do I change the assertion timeout in Playwright?

Related questions