Assertion Timeouts and Stability

Assertion timeouts and patterns have a direct impact on both the speed and reliability of your Playwright suite. Tuning them carefully helps you avoid flakiness without making tests unnecessarily slow.

Configuring Assertion Timeouts #

You can set default timeouts globally in playwright.config and override them per assertion when necessary. Most tests should work fine with the shared defaults.

// playwright.config.ts (snippet)
import { defineConfig } from '@playwright/test';

export default defineConfig({
  timeout: 30_000,
  expect: {
    timeout: 5_000,
  },
});

// Overriding timeout for a specific assertion
await expect(page.getByRole('status')).toHaveText('Long running task finished', {
  timeout: 15_000,
});

Use assertion patterns that reflect business expectations, such as checking for eventual counts or state changes rather than arbitrary waits.

Common Mistakes #

Mistake 1 — Raising global timeouts to hide slow tests #

This reduces signal.

❌ Wrong: Setting expect.timeout to 60 seconds for all tests.

✅ Correct: Investigate slow tests and adjust only where necessary.

Mistake 2 — Not distinguishing between transient failures and real problems #

This can waste investigation time.

❌ Wrong: Treating every rare timeout as a one-off and just rerunning CI.

✅ Correct: Use retries and traces to spot patterns and fix root causes.