Why should I avoid page.waitForTimeout() in Playwright?

page.waitForTimeout() introduces arbitrary hard-coded sleep delays that slow down test execution and create flaky tests when network or CI delays exceed the arbitrary sleep window. Use web-first assertions instead.

This answer is one piece of Chapter 11: Assertions.

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

page.waitForTimeout() pauses test execution for a fixed number of milliseconds. While often reached for as a quick fix when an element isn't ready, hardcoded sleeps waste significant CI time and still fail when network delays exceed the arbitrary sleep duration.

In contrast, Playwright's web-first assertions poll automatically until the expectation is satisfied, proceeding immediately without dead time. Measuring the two approaches on the same DOM update shows the dramatic difference: an arbitrary 3,000ms sleep takes 3,010ms, while the auto-waiting assertion on the same element completes in just 15ms.

Over a suite of hundreds of tests, eliminating manual sleeps turns minutes of idle waiting into instant execution. Reserve timeouts exclusively for local step-debugging; never commit page.waitForTimeout() to your test repository.

avoid-sleep.spec.js(https://practice.learnplayforge.com)

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

test('measure fixed sleep vs web-first assertion duration', async ({ page }) => {
  await page.goto('/catalog.html?mock=static&seed=42&autologin=1');
  const grinder = page.locator('article[data-sku="MRD-1003"]');
  await grinder.getByRole('button', { name: 'Add to cart' }).click();

  // The wrong way: arbitrary fixed sleep
  const t0 = Date.now();
  await page.waitForTimeout(3000);
  const fixedDuration = Date.now() - t0;

  // The web-first way: auto-waiting assertion on the same element
  const t1 = Date.now();
  await expect(page.getByTestId('cart-total')).toHaveText('₹11,900');
  const webFirstDuration = Date.now() - t1;

  console.log(`fixed sleep duration: ${fixedDuration}ms`);
  console.log(`web-first wait duration: ${webFirstDuration}ms`);
});

Output

fixed sleep duration: 3010ms
web-first wait duration: 15ms
1 passed (5.5s)

Test yourself

Why is await page.waitForTimeout(5000) considered an anti-pattern in automated tests?

Practised in the full course: the drill Read but never compared.

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

Why should I avoid page.waitForTimeout() in Playwright?

Related questions