How to Fix Playwright Test Timeout Issues: Complete Guide

In testing terms, a timeout means the automated process waited too long for something to happen and then stopped. In the context of Playwright, specifically the Playwright Test runner, it often looks like a test just hanging or ending with a message like “timeout 30000ms exceeded”.

Test timeout issues happen frequently because web pages load at different speeds, selectors fail to match, networks lag, or CI machines run slower.

We’ll cover all the common causes, fixes, and best practices for dealing with Playwright timeout problems.

What Causes Playwright Timeouts?

When your test execution takes too long, you’ll see a test timeout or timeout error in Playwright. Here are the most common reasons:

• Slow pages or large resources. The page under test takes a long time to load, so the test stops with a test timeout.
• Wrong or unstable selectors. The locator doesn’t match anything, and Playwright waits until it hits the “assertion timeout” or test timeout.
• Network delays or slow backend. If APIs are slow or responses are delayed, the test will await navigation or element loading, and then a navigation timeout or action timeout may hit.
• Slow CI or resource constraints. In a CI environment, the maximum time for a test might be reached faster because the machine is slower or busier.
• Unadjusted timeouts in the configuration file. If you only use default timeout settings, tests with longer flows may get cut off.

Understanding All Playwright Timeout Types

It helps to know which kind of timeout is involved, since each is set differently and matters in different ways. Here are some key timeout types in Playwright :

• Test timeout. The maximum time for each individual test and its fixtures to run. By default, it’s 30,000ms (30s).
• Action timeout. The maximum time a specific action, like a click or fill, may take. By default, it’s set to 0 (no limit), meaning the action will try until the test timeout is reached. You can configure a specific limit (for example, 15s) to fail actions faster than the whole test duration.
• Navigation timeout. The maximum time allows for a navigation (page.goto or similar) to complete. Like action timeouts, it defaults to 0, meaning it shares the limit of the test timeout unless explicitly configured.
• Expect timeout (assertion timeout). The time an assertion (via expect()) will wait for a condition to become true. The default is often 5,000ms (5s).
• API/request timeout. When your test is waiting for a network request or API response, and it takes too long, you may hit this timeout.
• Session timeout. When your application’s user session expires or authentication drops mid-test, your test may fail because the user is logged out or cookies are lost.

In short, they differ in scope. The test timeout covers the entire test execution, while action/navigation/expect timeouts cover specific operations. Properly calibrating them avoids wasted time during tasks like scraping or other projects.

How to Adjust Timeouts in Playwright

Adjusting Timeout for a Single Test

When a specific test has unusually long steps, like a large data upload or a special flow, you can increase its test timeout locally. For example:

test('example test', async ({ page }) => {
  test.slow();
  // test steps…
});

Use it only when necessary. If you overuse long timeouts everywhere, your overall suite slows down, and you hide underlying performance issues.

Increasing Global Timeouts

You can also change default timeout settings for your whole project in the playwright.config.ts or .js (the configuration file) so that every test uses longer limits.

export default defineConfig({
  timeout: 60_000,         
  globalTimeout: 3_600_000, 
});

However, setting a very high global timeout means that when a test really hangs, you wait longer before you find out. Long global timeouts may hide problems rather than solve them.

Adjusting Timeout in expect()

If you get many “assertion timeout” failures, for example, expect(locator).toBeVisible() timed out, then you can lengthen the timeout for that expect:

await expect(page.locator('button')).toBeVisible({ timeout: 10_000 });  // 10 s

Or in the config:

export default defineConfig({
  expect: { timeout: 10_000 }
});

It helps stabilize tests when elements take longer to appear, but don’t hide inefficient selectors or slow UI.

How to Handle API, Request, and Session Timeouts

Handling API Timeouts

A “request timeout” occurs when the test waits for a response via API or network, and the server is slow, returns 408 errors, or hangs. In those cases:

• Mock slow endpoints if possible so your tests don’t rely on a slow backend.
• Increase the request timeout value in your config or code when you know the backend is slow.
• Monitor server performance and fix the slow service rather than just increasing limits.

Handling Session Timeouts

If your app logs out users after some idle time or drops auth tokens, then during test execution, a session timeout might be the cause of a failed test. Here are some fixes:

• Design your test to re-login or refresh the token when the session expires.
• Break large flows into smaller tests so the session remains valid.
• Shorten steps that require a long wait, so you avoid session expiry mid-flow.

When sessions expire, you’ll see test failures where previously the test passed. Adjusting timeouts won’t fix faulty session logic.

Avoiding Hard-Coded Waits

Static waits like await page.waitForTimeout(5000) may look simple, but they make your test slow and flaky. Instead, you can use condition-based waits, like await locator.waitFor() or await expect(...), so your flow proceeds as soon as the UI is ready, not after a fixed delay.

Fixed waits are only acceptable in special situations: awaiting an external rate-limit reset or a long animation with a known fixed duration. But even then, you should be using minimal duration. Over-reliance on hard waits will likely worsen your test execution time and may hide real problems.

Conclusion

Timeouts in Playwright mean things take too long. To resolve the issue, you need to understand the various timeout types mentioned in the article. You should also use targeted timeout adjustments, like single test, expect, or global, only when necessary.

Don’t simply raise the timeouts everywhere. Instead, optimize selectors, speed up backends, and avoid hard waits. Good timeout settings lead to faster, more reliable test execution.

FAQ