Mastering Playwright Timeout Settings

Mastering timeout settings in Playwright is crucial to ensure that your tests are both reliable and stable. In Playwright, timeouts control how long the framework waits for certain actions to complete (e.g., page loading, element interactions) before throwing an error. Properly configuring timeouts helps to avoid flaky tests and ensures that your test suite runs smoothly, even under varying network conditions or page load speeds. Let’s deep dive into important timeouts in playwright automation tool.

1. Global Timeout Configuration

You can set a global timeout for your entire test suite by configuring the Playwright test runner. This setting defines the maximum time for the entire test to complete.

To set a global timeout, you can configure it in the playwright.config.ts file:

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

export default defineConfig({
  timeout: 30000, // Global timeout for tests, in milliseconds (30 seconds)
});

This applies the timeout to all tests. If a test takes longer than this time, it will be automatically aborted.

2. Test-Specific Timeout

Sometimes, you may want to set a timeout for a specific test or group of tests. This allows you to configure timeouts individually, based on the complexity or expected duration of a test.

You can specify a timeout for individual tests using the test() function's options:

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

test('slow test example', { timeout: 60000 }, async ({ page }) => {
  await page.goto('https://example.com');
  // Your test steps here
});

Here, the test will timeout after 60 seconds instead of the global timeout.

3. Timeouts for Specific Actions

Playwright allows you to configure timeouts for specific actions, such as waiting for an element, navigation, or network requests. These can be crucial to ensure that actions are completed within a reasonable time before moving forward.

(a) Waiting for Elements

When waiting for an element to appear, you can set the timeout option for the waitForSelector() method.

await page.waitForSelector('#myElement', { timeout: 5000 }); // 5 seconds timeout

This will cause Playwright to wait up to 5 seconds for the element to appear, after which it will throw a TimeoutError.

(b) Navigation Timeout

You can also configure how long Playwright will wait for a page to navigate before timing out. This is particularly useful when you want to ensure that a page load completes in a given timeframe.

await page.goto('https://example.com', { timeout: 10000 }); // 10 seconds timeout

(c) Wait for Navigation

If you're waiting for a specific type of navigation (such as a page load or redirect), you can set a timeout for that too:

await page.waitForNavigation({ timeout: 15000 }); // 15 seconds timeout for navigation

4. Action Timeouts for Clicking and Typing

You can also set timeouts for specific actions like clicking buttons, typing text into fields, etc. Here's an example for clicking a button with a custom timeout:

await page.click('#submitButton', { timeout: 8000 }); // 8 seconds timeout for clicking

For typing:

await page.fill('#inputField', 'Hello World!', { timeout: 7000 }); // 7 seconds timeout for typing

5. Adjusting Timeout Based on Environment

Sometimes, test environments (e.g., CI/CD pipelines) might have slower response times due to resource constraints or network latencies. You may want to adjust timeouts based on whether the test is running locally or in a CI/CD pipeline.

You can use environment variables to achieve this:

const timeout = process.env.CI ? 60000 : 30000; // 60s for CI, 30s for local

export default defineConfig({
  timeout: timeout,
});

6. Handling Timeout Errors

Playwright throws a TimeoutError if a specific timeout is exceeded. To handle this gracefully, you can use try/catch blocks.

try {
  await page.waitForSelector('#myElement', { timeout: 3000 });
} catch (error) {
  console.error('Element not found within the specified timeout', error);
}

7. Disabling Timeouts (For Debugging)

If you're debugging and want to disable timeouts temporarily to let tests run indefinitely, you can do so by setting the timeout to 0:

export default defineConfig({
  timeout: 0, // Disable timeout for all tests
});

8. Using expect Assertions with Timeout

Playwright has built-in support for expect() assertions, which also come with a timeout option. This is useful if you want to ensure an element's state within a specific time frame.

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

await expect(page.locator('#myElement')).toBeVisible({ timeout: 4000 }); // 4 seconds timeout

Mastering timeout settings in Playwright is key to ensuring stable and reliable tests. By adjusting timeouts for different actions, you can handle flaky or slow elements more effectively. Always ensure that your timeouts are set according to the expected load times, network conditions, and environment, and use the flexibility of Playwright's timeout settings to fine-tune your test suite for the best results.