Playwright Auto-Waiting
Playwright Auto-Waiting
Auto-waiting means that Playwright waits for the page to be ready before it acts or checks.
Web pages change all the time: content loads, buttons get enabled, messages appear after a moment.
Because Playwright waits for you, you rarely need to write any waiting code yourself.
Actionability Checks
Before an action, Playwright checks that the element is ready for it.
These are called actionability checks:
| Check | Meaning |
|---|---|
| Visible | The element has a size and is not hidden with visibility:hidden |
| Stable | The element has stopped moving, for example after an animation |
| Receives events | No other element covers it, so the click really lands on it |
| Enabled | The element is not disabled |
| Editable | The element is enabled and not read-only |
Not every action needs every check:
| Action | Visible | Stable | Receives events | Enabled | Editable |
|---|---|---|---|---|---|
| click(), dblclick(), check(), uncheck() | Yes | Yes | Yes | Yes | |
| hover(), dragTo() | Yes | Yes | Yes | ||
| fill(), clear() | Yes | Yes | Yes | ||
| selectOption() | Yes | Yes |
If a check fails, Playwright waits and tries again, until the element is ready or the timeout runs out.
This test clicks the "Save note" button on the practice actions page.
The button stays disabled until you type a note, so the click can never happen:
Example
tests/disabled.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('click a disabled button', async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/actions.html');
await page.getByRole('button', { name: 'Save note' }).click({ timeout: 2000 });
});
Output:
Running 1 test using 1 worker
[1/1] [chromium] › tests/disabled.spec.js:4:1 › click a disabled button
1) [chromium] › tests/disabled.spec.js:4:1 › click a disabled button ─────────────────────────────
TimeoutError: locator.click: Timeout 2000ms exceeded.
Call log:
- waiting for getByRole('button', { name: 'Save note' })
- locator resolved to <button disabled id="save" type="button">Save note</button>
- attempting click action
2 × waiting for element to be visible, enabled and stable
- element is not enabled
- retrying click action
- waiting 20ms
2 × waiting for element to be visible, enabled and stable
- element is not enabled
- retrying click action
- waiting 100ms
3 × waiting for element to be visible, enabled and stable
- element is not enabled
- retrying click action
- waiting 500ms
4 | test('click a disabled button', async ({ page }) => {
5 | await page.goto('https://www.w3schools.com/playwright/practice/actions.html');
> 6 | await page.getByRole('button', { name: 'Save note' }).click({ timeout: 2000 });
| ^
7 | });
8 |
at /home/user/my-project/tests/disabled.spec.js:6:57
1 failed
[chromium] › tests/disabled.spec.js:4:1 › click a disabled button ──────────────────────────────
The call log shows the checks: Playwright found the button, saw that it was not enabled, and retried until the 2 seconds were up.
Waiting for a Result
Web-first assertions wait too: they check again and again until the page shows the expected result.
The practice login page waits 600 milliseconds before it shows the welcome message, like a real server would.
The test needs no extra code for that:
Example
tests/login.spec.js
// @ts-check
import { test, expect } from '@playwright/test';
test('log in', async ({ page }) => {
await page.goto('https://www.w3schools.com/playwright/practice/login.html');
await page.getByLabel('Username').fill('student');
await page.getByLabel('Password').fill('w3schools');
await page.getByRole('button', { name: 'Log in' }).click();
await expect(page.getByTestId('welcome')).toHaveText('Welcome, student!');
});
Output:
Running 1 test using 1 worker
[1/1] [chromium] › tests/login.spec.js:4:1 › log in
1 passed (4.8s)
toHaveText() checked the page again and again, and passed as soon as the message appeared.
Do Not Use waitForTimeout
page.waitForTimeout() pauses the test for a fixed time:
Example: Do not do this
await page.getByRole('button', { name: 'Log in' }).click();
await page.waitForTimeout(1000);
expect(await page.getByTestId('welcome').isVisible()).toBe(true);
This is a bad idea for two reasons:
- If the page is faster than 1 second, the test wastes time on every run
- If the page is slower one day, for example on a busy CI server (a computer that runs your tests automatically), the test fails
A test that sometimes passes and sometimes fails is called a flaky test.
Use a web-first assertion instead.
It waits exactly as long as needed:
Example: Do this
await page.getByRole('button', { name: 'Log in' }).click();
await expect(page.getByTestId('welcome')).toBeVisible();
For the rare cases where you do need to wait yourself, and to change the timeouts, see Waits and Timeouts.