How to Handle Playwright Timeouts

Handling Playwright timeouts is crucial to ensure tests run reliably and do not fail due to slow-loading pages or elements. It helps identify real issues instead of false negatives caused by temporary delays. Proper timeout management improves test stability, making automation more predictable. Additionally, it allows customization for different scenarios, balancing speed with accuracy in testing workflows.

What Is a Timeout in Playwright?

In Playwright, a timeout is the maximum amount of time the framework (Playwright) will wait for a particular action or event to complete before it considers the operation failed and throws an error.

For example, when testing a login form, after submitting the user credentials, Playwright waits for the authentication response or a specific element, like a dashboard or welcome message, to appear.

If the server takes too long to respond and the expected element doesn’t show up within the set timeout, Playwright throws a timeout error.

Why Use Playwright Timeouts?

Timeouts are what separate flaky tests from reliable ones. They help your automation handle real-world delays whether that’s a slow network, a delayed DOM update, or an API that takes a few seconds too long to respond.

Prevent Hanging Test Runs

Without timeouts, a test might keep waiting if something goes wrong. Maybe an API fails, the test runner just waits. It also takes time, consumes memory, and never ends.

Playwright overcome this with built-in default timeouts for tests, actions, and assertions. These ensure that tests automatically fail after the default time elapses, even if you didn’t set a specific timeout.

Example:

If the button doesn’t show up within 10 seconds, the test fails immediately. If you don’t specify a timeout, Playwright uses its default value, so there are no infinite waits or wasted resources.

Handle Slow Loading Components

Not all slowness is a bug. Some components like animated dropdowns or sections powered by external APIs take longer to appear. A test that assumes instant visibility often fails for the wrong reasons.

Timeouts give elements room to load, failing only when they truly don’t show up.

Example:

Here, the test allows up to 15 seconds for the element to become visible. This protects your test from false failures caused by normal delays, while still failing fast if something genuinely breaks.

Faster Feedback on Failures

No one should wait five minutes to discover that a login flow is broken. Proper timeouts give you faster feedback when something goes wrong.

Example:

The test waits up to 8 seconds for the dashboard to load. If it doesn’t appear, that’s likely a real issue: slow authentication, blocked API calls, or database lag.

Instead of long waits, you get quick, actionable feedback.

Types of Playwright Timeout

Timeouts in Playwright control how long things are allowed to wait. Some wait for pages to load. Others wait for elements to show up or actions to complete.

Here are the main types of timeouts in Playwright:

Global Timeout

It is the top-level timeout. It sets the maximum time for the entire test run. If this is hit, all tests are stopped immediately, no matter what their individual timeouts are.

Example:

Test Timeout

It sets the maximum time a single test (including hooks and fixtures) can run.

• Per-action or per-navigation timeouts can override it.
• But the overall test timeout always wins. If it’s hit, the test fails.

Global test timeout in config:

Per-test timeout:

Hooks Timeout

It controls how long beforeAll, afterAll, beforeEach, and afterEach hooks can run.

• Defaults to the test timeout.
• Can be overridden using testInfo.setTimeout() inside the hook.

Example:

Fixture Timeout

It controls how long a fixture’s setup can take. If setup inside use() exceeds the timeout, the test fails.

Example with custom fixtures:

Here, both fixtures have a 30-second setup timeout.

Action Timeout

It sets the maximum time for user actions like click(), fill(), or check().

• Default: no timeout.
• Overrides test timeout for that action only.

Global config:

Per-action timeout:

Here, the click waits up to 10 seconds. Other actions follow the global/test timeout.

Expect Timeout

It controls how long Playwright retries expect() assertions before failing.

• Default: 5 seconds
• Retries automatically until timeout is hit.

Global config:

Per-assertion override:

Navigation Timeout

It controls how long Playwright waits for page navigation events (e.g. page.goto(), page.waitForNavigation()).

• Affects page load delays due to network or server response times.
• Throws a timeout error if exceeded.

Global config:

Per-navigation override:

Here, Playwright waits up to 15 seconds for the page to load.

How to Test Playwright Timeouts?

In automation testing with Playwright, validating timeout scenarios is essential for building resilient test scripts that mirror real user behavior.

Progress bars often trigger timeout issues in tests. They appear during uploads, submissions, or background processing, and tests must wait until they complete.

This demonstration covers three strategies:

• Timeout failure demonstration.
• Progressive timeout strategy.
• Retry mechanism for flaky tests.

All examples use the Jquery Download Progress-Bar Demo of LambdaTest Selenium Playground.

Prerequisites

Make sure you have the following installed before starting:

• Node.js: v20.17.0 or above.
• npm: v10.8.2 or above.
• Playwright: v1.52.0 or above.
• Clone this Playwright Timeout Handling GitHub repository to access all code samples and configurations.

Project Structure

Organize your project like this for clarity and maintainability:

Timeout Failure

This test shows what happens when you set an unrealistic timeout. The progress bar never finishes in the given 1000ms, so the test fails as expected.

Progressive Timeout Strategy

This test uses staged timeouts to handle delayed UI updates without false positives.

Retry Mechanism for Flaky Progress Bars

Some UIs are inconsistent, so retries can help stabilize test runs.

Test Execution:

Run the test on using the below command:

This command produces terminal output and an HTML report for detailed results.

How to Test Playwright Timeouts With LambdaTest?

Once your tests run locally, you can scale them to the cloud using LambdaTest. Running on LambdaTest Playwright automation cloud lets you validate Playwright timeout across multiple browsers, operating systems, and real-world network conditions.

The only difference is that your configuration must include LambdaTest Username and Access Key and Playwright automation capabilities so tests can run in the cloud. To get started, check out this guide on Playwright testing with LambdaTest.

To get your LambdaTest credentials, go to Account Settings, then click on Password & Security. You can generate capabilities from the LambdaTest Automation Capabilities Generator.

To run tests on the LambdaTest platform, you can follow the steps below:

Step 1: Create a .env file in your project root:

Step 2: Update the playwright.config.ts file by importing dotenv and load env vars:

Now modify the playwright.config.ts file for running tests on LambdaTest:

Step 3: Add the lambdatest-setup.ts file and define capabilities for different conditions:

Test Execution:

Run the below command to execute the test:

Changing Timeout Settings in Playwright

Timeouts let you control how long Playwright waits before failing. You can adjust them globally, per test, per action, or even per environment, depending on your needs.

Change Global Timeout

If you want a timeout that applies to all tests, set globalTimeout in your playwright.config.ts file:

Any test that runs longer than 6 seconds will fail automatically.

Change Timeout for a Single Test

If one of your tests takes longer (like login, checkout, or file upload), increase the limit using the test.setTimeout():

This way, you only extend the timeout for this test, not the whole suite.

Change Timeout for an Action

If one specific step takes longer (like a payment or API-heavy workflow), override the timeout just for that action:

You don’t slow down other actions, just the one that needs more time.

Change Timeout for an Assertion

If you’re waiting for a page change or element to appear, set a custom timeout on the assertion:

Each check gets the time it really needs, nothing more.

Change Timeouts Per Environment

You can also give different environments their own timeout rules inside your config:

This way, your tests behave realistically whether you’re running locally, in staging, or in production.

Best Practices for Managing Playwright Timeouts

Timeouts can make tests fail if elements or responses take longer than expected. Following these practices will keep your playwright test stable, fast, and less prone to errors.

• Use Auto-Waiting Features: Playwright automatically waits for elements to be ready before performing any action on them, reducing the need for hard-coded delays. Relying on this auto-awaiting will make your tests more stable and faster.
• Use Web-First Assertions: Using Playwright assertions like toBeVisible() or toHaveText() will wait and retry until the expected state or condition is met, provided the timeout hasn’t run out. They reflect what a real user actually sees and help prevent false failure. So, prioritize using them in your test instead of hard waits.
• Set Appropriate Timeouts: When you’re testing on a slow Internet connection, adjust your timeouts to avoid unnecessary false failures. You can set global timeout or local ones on specific actions, giving Playwright enough time to handle slower responses.
• Use locator.waitFor When Necessary: When working with dynamically loaded content, explicitly wait for a specific state, such as visible or attached. Doing this will prevent flaky test failures when the element renders late or isn’t in the expected state. Avoid using fixed delays like waitForTimeOut().
• Use Optimized Locators and Prefer User-Facing Attributes: Prioritize using unique attributes like data-test-id or other user-facing identifiers instead of XPath or generic CSS selectors. These optimized Playwright locators or unique attributes will help Playwright to find elements faster, thereby reducing the risk of timeout errors and flaky tests.

Common Timeout Errors and Troubleshooting

Your test may occasionally take longer than anticipated when using Playwright, which could result in timeout problems. Fixes for these issues vary depending on their kind. These are the typical ones, along with their go-to solutions.

• Page Load Timeout: This type of error happens when the page you’re navigating to takes more than the default time to load, usually because of a slow network.

To resolve, check your URL first; it might be wrong. Then, you can increase your timeout for that specific navigation, for example, use page.goto(‘https://www.example.com’, {timeout: 60000}) or set global ones with page.setDefaultNavigationTimeout(60000).

For single-page apps, use page.waitForLoadState(‘domcontentloaded’) instead of the default ‘load’ to avoid waiting for images or other heavy media files.

• Locator Timeout: This occurs if Playwright can’t find or interact with an element within the given time. This could be a result of delayed rendering, or the element is hidden during an animation.

To fix, ensure the element is visible before interaction with the locator.waitFor({ state: “visible” }) or expect(locator).toBeVisible().

You can also reduce locator timeout issues by using unique attributes like data-test-id or specific CSS selectors so Playwright can find elements faster, for example: await page.locator(‘[data-test-id=”submit-button”]’).click();

• Assertion Timeout: Assertion timeouts happen when assertions like expect(page.locator(‘#status’)).toHaveText(‘Success’) do not resolve within the allocated or default timeout. This error is commonly caused by dynamic content when they do not appear as expected or when there’s a delay in rendering.

To troubleshoot in this situation, you can add an explicit wait, such as a locator.waitFor() before the assertion. You can also increase the assertion timeout using {timeout: <time>} when the content is consistently slow.

• Network Request Timeout: API calls can take too long if the server is slow or if there’s a connection issue. To handle this, set longer timeouts with page.setDefaultTimeout() after checking how long the request normally takes.

You can also use a page.waitForResponse() for important API calls or even mock slow responses with page.route() so tests don’t depend on actual server speed.

Conclusion

Handling timeouts properly can make a big difference in how stable your Playwright tests are. One of my test cases for this blog kept failing just because an image loaded a bit late. After adjusting the timeout in steps, first for loading, then for visibility, it finally passed. That small fix saved me a lot of time and headaches.

When you’re working with different speeds, animations, or network conditions, things don’t always behave the same way. That’s where platforms like LambdaTest come in handy. It lets you run your Playwright tests across real browsers and networks, so you can spot these issues early and fix them with confidence.

Citations

• Playwright Timeouts: https://playwright.dev/docs/test-timeouts