Configure Playwright test, assertion, and action timeouts

Set the timeout for the operation that is actually failing, and account for the overall test budget and hook limits.

Guance Editorial Team 2026-10-27 3 min read Updated 2026-10-27

Illustration of software development and testing

Playwright Test has separate budgets for a test, retrying assertions, actions, and navigation. Configure them with timeout, expect.timeout, use.actionTimeout, and use.navigationTimeout. You can override a particular test with test.setTimeout() or an assertion with its timeout option.

Understand the defaults

Layer	Configuration	Default	Scope
Test	`timeout`	30 seconds	Test execution, including fixture setup and `beforeEach` work
Assertion	`expect.timeout`	5 seconds	Retrying assertions such as `toBeVisible()`
Action	`use.actionTimeout`	`0`	No separate action limit; the test budget still applies
Navigation	`use.navigationTimeout`	`0`	No separate navigation limit; the test budget still applies

These are Playwright Test defaults. Standalone Playwright Library usage has its own timeout settings. Teardown and hooks also have documented timeout rules; the test timeout is not simply one stopwatch covering every part of suite execution.

Set project-wide limits

import { defineConfig } from '@playwright/test';

export default defineConfig({
  timeout: 60_000,
  expect: { timeout: 10_000 },
  use: {
    actionTimeout: 15_000,
    navigationTimeout: 30_000,
  },
});

A longer action or assertion timeout cannot extend the test's remaining time.

Override a specific test or group

Inside a Playwright Test file with test and expect imported:

test('upload a large file', async ({ page }) => {
  test.setTimeout(180_000);
  // Navigate and perform the application's upload steps.
  await expect(page.locator('#done')).toBeVisible({ timeout: 60_000 });
});

test.describe('reports', () => {
  test.describe.configure({ timeout: 300_000 });
  // Define report tests here.
});

Diagnose before extending the budget

A 30-second timeout can mean the environment is genuinely slow: cold starts, large fixtures, or resource contention may justify more time. It can also mean the test is waiting for an element that will never appear because the locator is wrong or the application is already in an error state.

Inspect the failing step in Trace Viewer before changing the limit. Given a captured trace, open it with npx playwright show-trace path/to/trace.zip. Increasing a timeout should accommodate expected work, not postpone the same inevitable failure.

Frequently asked questions

Should CI have longer timeouts?

When measurements justify it, configure a different budget, for example timeout: process.env.CI ? 120_000 : 60_000. If you enable retries, retain traces and investigate retrying tests. Retries do not explain or fix the underlying race.

Why did an action fail before its configured timeout?

The overall test budget may have expired first. An actionTimeout of 0 means no independent action limit, not freedom from the test deadline. A large action budget is ineffective if the containing test has less time remaining.

What controls beforeAll?

beforeAll and afterAll have separate hook timeouts, whose default value follows the test timeout. Use test.setTimeout() inside the hook to adjust that hook. Playwright Test does not provide a hooksTimeout configuration field.

References

Playwright Test timeouts