Playwright Waits and Timeouts
Playwright Waits and Timeouts
An explicit wait tells Playwright to wait for something it cannot see on the page, like a network response or a new URL.
A timeout is how long Playwright waits before it gives up.
Most of the time, the auto-waiting of actions and web-first assertions is all you need.
Explicit Waits
Auto-waiting only covers elements.
To wait for something else, use one of these methods:
| Method | Waits for |
|---|---|
| page.waitForResponse(url) | A network response, for example from an API |
| page.waitForURL(url) | The page to reach a URL |
| page.waitForLoadState(state) | The page to reach a load state: 'load', 'domcontentloaded' or 'networkidle' |
The load states are explained in the Navigation chapter.
This file has two tests: one waits for an API response, and one waits for a new URL after a click:
Example
tests/explicit.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('wait for a response', async ({ page }) => {
const responsePromise = page.waitForResponse('**/api/products.php');
await page.goto('https://www.w3schools.com/playwright/practice/shop.html');
const response = await responsePromise;
expect(response.status()).toBe(200);
const data = await response.json();
expect(data.products).toHaveLength(5);
});
test('wait for a URL', async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/index.html');
await page.getByRole('link', { name: 'Todo list' }).click();
await page.waitForURL('**/todo.html');
await page.waitForLoadState('load');
await expect(page.getByRole('heading', { name: 'Todo List' })).toBeVisible();
});
Output:
Running 2 tests using 2 workers
[1/2] [chromium] › tests/explicit.spec.js:4:1 › wait for a response
[2/2] [chromium] › tests/explicit.spec.js:13:1 › wait for a URL
2 passed (2.5s)
Example Explained
waitForResponse()is called beforegoto(), withoutawait. It starts listening first, so it cannot miss the responseawait responsePromisethen waits until the response has arrived**in a URL pattern matches any characters, so'**/todo.html'matches the todo page on any serverwaitForURL()waits for the new page, andwaitForLoadState('load')waits until it has loaded
Note: goto() already waits for the load event, so you rarely need waitForLoadState() after it.
After a click, await expect(page).toHaveURL(/todo\.html/) retries until the URL changes, so it works just as well as waitForURL().
Timeouts
Playwright has default timeouts, so a test never waits forever:
| Timeout | Default | Change it with |
|---|---|---|
| Test timeout (the whole test, with its beforeEach hooks) | 30 seconds | timeout in the config, or test.setTimeout() |
| Assertion timeout (each web-first assertion) | 5 seconds | expect: { timeout } in the config, or the timeout option |
| Action timeout (each action) | No limit, only the test timeout | use: { actionTimeout } in the config, or the timeout option |
| Navigation timeout (goto, waitForURL...) | No limit, only the test timeout | use: { navigationTimeout } in the config, or the timeout option |
Set them for the whole project in playwright.config.js:
Example
playwright.config.js
// @ts-check
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
testDir: './tests',
fullyParallel: true,
reporter: 'html',
timeout: 60_000,
expect: {
timeout: 10_000,
},
use: {
actionTimeout: 10_000,
navigationTimeout: 30_000,
trace: 'on-first-retry',
},
projects: [
{ name: 'chromium', use: { ...devices['Desktop Chrome'] } },
],
});
All timeouts are in milliseconds.
60_000 is the same as 60000: 60 seconds.
To change the timeout for one test, call test.setTimeout() inside it.
This test looks for a "Sign in" button, but the button says "Log in":
Example
tests/timeout.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('a slow test', async ({ page }) => {
test.setTimeout(3000);
await page.goto('https://www.w3schools.com/playwright/practice/login.html');
await page.getByRole('button', { name: 'Sign in' }).click();
});
Output:
Running 1 test using 1 worker
[1/1] [chromium] › tests/timeout.spec.js:4:1 › a slow test
1) [chromium] › tests/timeout.spec.js:4:1 › a slow test ──────────────────────────────────────────
Test timeout of 3000ms exceeded.
Error: locator.click: Test timeout of 3000ms exceeded.
Call log:
- waiting for getByRole('button', { name: 'Sign in' })
5 | test.setTimeout(3000);
6 | await page.goto('https://www.w3schools.com/playwright/practice/login.html');
> 7 | await page.getByRole('button', { name: 'Sign in' }).click();
| ^
8 | });
9 |
at /home/user/my-project/tests/timeout.spec.js:7:55
1 failed
[chromium] › tests/timeout.spec.js:4:1 › a slow test ───────────────────────────────────────────
The click had no timeout of its own, so it waited until the whole test ran out of time after 3 seconds.
Tip: Use test.slow() inside a test you know is slow.
It makes the test timeout three times longer.