How to Handle Playwright Timeouts

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:

await expect(page.getByRole('button', {name:'Checkout'}))
.toBeVisible({timeout: 10000});

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:

await expect(page.locator('#mz-product-tab-37217979-0'))
.toBeVisible({timeout: 15000});

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:

await expect(page.locator('.dashboard'))
.toBeVisible({timeout: 8000});

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.

Note: Run your Playwright timeout tests across 50+ real browsers. Try TestMu AI Today!

How to Test Playwright Timeouts With TestMu AI?

Once your tests run locally, you can scale them to the cloud using TestMu AI. Running on TestMu AI 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 TestMu AI 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 TestMu AI.

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

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

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

LT_USERNAME=your-username
LT_ACCESS_KEY=your-access-key

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

import dotenv from 'dotenv';
import path from 'path';
dotenv.config({ path: path.resolve(__dirname, '.env') });

const LT_USERNAME = process.env.LT_USERNAME;
const LT_ACCESS_KEY = process.env.LT_ACCESS_KEY;

if (!LT_USERNAME || !LT_ACCESS_KEY) {
  console.error('Error: LambdaTest credentials not found.');
  process.exit(1);
}

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

export default defineConfig({
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  use: {
    baseURL: 'https://www.lambdatest.com/selenium-playground',
    trace: 'on-first-retry',
  },
  projects: [
    { name: "chrome:latest:macOS Sonoma@lambdatest" },
    { name: "pw-firefox:latest:macOS Sonoma@lambdatest" },
    { name: "pw-webkit:latest:macOS Sonoma@lambdatest" },
  ],
});

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

export const baseCapabilities = {
  browserName: "Chrome",
  browserVersion: "latest",
  "LT:Options": {
    platform: "Windows 11",
    build: "Playwright Sample Build",
    name: "Playwright Sample Test",
    user: process.env.LT_USERNAME,
    accessKey: process.env.LT_ACCESS_KEY,
    video: true,
    console: true,
    resolution: "1920x1080",
    visual: true,
  },
};

Test Execution:

Run the below command to execute the test:

npx playwright test tests/progress-bar.spec.ts

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:

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

export default defineConfig({
  globalTimeout: 6 * 1000, // 6 seconds
});

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():

test('user registration', async ({ page }) => {
  test.setTimeout(30000); // 30 seconds
  // test steps...
});

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:

// Normal clicks use default timeout
await page.click('text=Reviews');

// Give the payment step extra time
await page.click('button:has-text("Pay Now")', { timeout: 45000 });

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:

// Allow 20s for redirect
await expect(page).toHaveURL(/.*account/success/, { timeout: 20000 });

// Allow 15s for success message
await expect(page.locator('h1')).toBeVisible({ timeout: 15000 });

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:

projects: [
  { name: 'local-dev', use: { actionTimeout: 5000, navigationTimeout: 10000 } },
  { name: 'staging',   use: { actionTimeout: 10000, navigationTimeout: 20000 } },
  { name: 'production',use: { actionTimeout: 20000, navigationTimeout: 45000 } }
]

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 TestMu AI 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.

If you are working with Playwright proxy, it’s important to configure timeout settings carefully. Proxies can introduce additional latency, and adjusting timeouts ensures your tests remain stable and don’t fail due to delayed responses.

Citations

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