Menu
×
   ❮   
HTML CSS JAVASCRIPT SQL PYTHON JAVA PHP C C++ C# AWS W3.CSS HOW TO BOOTSTRAP REACT MYSQL JQUERY EXCEL XML DJANGO NUMPY PANDAS NODEJS DSA TYPESCRIPT ANGULAR ANGULARJS GIT POSTGRESQL MONGODB ASP AI R GO KOTLIN SWIFT SASS VUE GEN AI SCIPY CYBERSECURITY DATA SCIENCE INTRO TO PROGRAMMING HTML & CSS BASH RUST TOOLS MATH

Playwright Auto-Waiting


Share

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:

CheckMeaning
VisibleThe element has a size and is not hidden with visibility:hidden
StableThe element has stopped moving, for example after an animation
Receives eventsNo other element covers it, so the click really lands on it
EnabledThe element is not disabled
EditableThe element is enabled and not read-only

Not every action needs every check:

ActionVisibleStableReceives eventsEnabledEditable
click(), dblclick(), check(), uncheck()YesYesYesYes
hover(), dragTo()YesYesYes
fill(), clear()YesYesYes
selectOption()YesYes

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.



Free account

Track your progress

XP earned 0 Day streak 0 Spaces 0 League —

New

Learn in Adventure Mode W3Schools Adventure App

Coding fundamentals as bite-sized lessons and challenges.

×

Contact Sales

If you want to use W3Schools services as an educational institution, team or enterprise, send us an e-mail:
sales@w3schools.com

Report Error

If you want to report an error, or if you want to make a suggestion, send us an e-mail:
help@w3schools.com

W3Schools is optimized for learning and training. Examples might be simplified to improve reading and learning. Tutorials, references, and examples are constantly reviewed to avoid errors, but we cannot warrant full correctness of all content. While using W3Schools, you agree to have read and accepted our terms of use, cookies and privacy policy.

Copyright 1999-2026 by Refsnes Data. All Rights Reserved. W3Schools is Powered by W3.CSS.