Playwright 06 ๐ญ Auto-Waiting Mechanics โ Actionability Checks & Web-First Assertions
Playwright’s auto-waiting is not a single timeout. It is a set of checks that run before an action, a set of retries that run around an assertion, and a navigation wait that runs after a page.goto. The checks are the definition of “actionable”: the element exists, it is visible, it is stable, it receives events, it is enabled, and it is not covered by an overlay. The assertion retry is the definition of “eventually”: the condition is re-evaluated until it passes or the timeout expires. The two mechanisms together remove the hard-coded waits that make E2E suites flaky, and understanding the individual checks is what makes a failure diagnosable instead of mysterious.
This chapter covers the actionability checks, the web-first assertion retry model, and the cases where the auto-waiting is not enough. The sections that follow walk through the checks that gate an action, the assertions that retry, and the hydration and animation cases that the checks do not catch.
Key point: Playwright’s actionability checks (attached, visible, stable, receives events, enabled, editable) gate every action, and web-first assertions retry until the condition passes or the timeout expires; a failed action throws after the timeout, and the error names which check did not pass.
a. The actionability checks
Before Playwright performs an action on a locator, it runs a sequence of checks. If any check fails, the action waits and retries until all checks pass or the timeout expires. The checks are the contract between the test and the page, and the failure message names the check that failed.
| Check | Meaning | Applies To |
|---|---|---|
| Attached | Element is in the DOM | All actions |
| Visible | Non-empty box, not visibility:hidden | All actions |
| Stable | Same bounding box for two animation frames | Click, hover, drag |
| Receives events | Not obscured by another element | Click, hover, drag |
| Enabled | No disabled attribute | Click, fill, select |
| Editable | Not readonly | Fill, type, clear |
The visible check is the most nuanced. An element with display: none or visibility: hidden has no box and fails the check. An element with opacity: 0 has a box and passes the checkโit is invisible to the user but present in the layout, and Playwright considers it visible because it can be clicked. This is the difference between “not rendered” and “transparent,” and a test that expects an opacity: 0 element to fail toBeVisible() is wrong.
The stable check is what prevents a click from landing at the wrong coordinates when an animation is still moving the element. Playwright compares the bounding box across two consecutive animation frames; if the box has moved, the element is not stable and the action waits. This is why a click on a button that is sliding into view waits for the slide to finish before clicking.
The receives events check is the one that catches the loading overlay. If a modal is covering the button, the hit-test at the button’s center returns the modal, not the button, and the action waits. The overlay disappearing is the condition the check is waiting for.
The editable check is specific to fill and type. A readonly input is visible, enabled, and stable, but it cannot be filled. The check is what makes fill wait for an input that becomes editable after a click.
b. Web-first assertions and the retry model
A web-first assertion is an expect call on a locator. The assertion is re-evaluated until it passes or the timeout expires. The retry is not a waitFor wrapper; it is built into the matcher.
// Retries until the element is visible
await expect(page.getByText("Saved")).toBeVisible();
// Retries until the text matches
await expect(page.getByRole("heading")).toHaveText("Dashboard");
// Retries until the count matches
await expect(page.getByRole("listitem")).toHaveCount(3);
The non-web-first assertion is an expect on a value, and it does not retry. expect(await page.textContent("h1")).toBe("Dashboard") reads the text once and fails immediately if the value is not yet “Dashboard.” The distinction is the most common source of flakiness in a Playwright suite: a test that uses the value assertion on a page that loads data asynchronously fails intermittently, and the fix is the locator assertion, not a longer timeout.
The web-first matchers include toBeVisible, toBeHidden, toBeEnabled, toBeDisabled, toBeChecked, toBeEditable, toBeFocused, toHaveText, toContainText, toHaveValue, toHaveAttribute, toHaveCount, toHaveURL, toHaveTitle, toBeInViewport. Each one retries. The expect(locator).not.matcher() form negates the assertion and retries the negation, which is the correct way to wait for an element to disappear.
// Retries until the element is hidden
await expect(page.getByText("Loading")).toBeHidden();
The assertion timeout is separate from the action timeout. The default is 5 seconds for both, and the expect: { timeout } config and the --timeout flag change them. A test that needs a longer assertion timeout for a slow endpoint sets it per assertion with { timeout } as the last argument.
await expect(page.getByText("Report ready")).toBeVisible({ timeout: 30_000 });
c. The cases the checks do not catch
The actionability checks are mechanical: they look at the DOM and the layout. They do not know whether the JavaScript behind the button has loaded. A server-rendered page can show an enabled, visible, stable button before the click handler is attached, and Playwright will click it and nothing will happen.
The hydration problem is the canonical case. The fix is on the application side: the button should be disabled until the JavaScript that handles the click is ready, and Playwright’s enabled check will then wait for it. The alternative is to assert on a readiness signalโa class, a data attribute, a network responseโbefore the click, but the disabled-until-hydrated pattern is the one that works without a test-side workaround.
The animation case is the other one. The stable check waits for the bounding box to stop moving, but a CSS transition on a property that does not change the boxโopacity, color, backgroundโdoes not affect the check. A test that clicks during an opacity transition may click a half-faded element, and the check will not catch it. The fix is to wait for the transition to end with a web-first assertion on the final state, not to rely on the stability check.
The visible check does not catch an element that is present but off-screen. A position: absolute; left: -9999px element has a box and passes the visible check, and a click on it scrolls it into view and clicks. This is usually the correct behavior, but a test that expects the element to be invisible to the user is wrong; the visible check is about the box, not the viewport.
Complete Example Session
// ============================================
// PART 1: THE ACTIONABILITY CHECKS
// ============================================
import { test, expect } from "@playwright/test";
test("clicks the button after it is actionable", async ({ page }) => {
await page.goto("/");
// Waits for: attached, visible, stable, receives events, enabled
await page.getByRole("button", { name: "Submit" }).click();
// Web-first assertion: retries until the text appears
await expect(page.getByText("Saved")).toBeVisible();
});
// ============================================
// PART 2: THE RETRY MODEL
// ============================================
test("waits for async data", async ({ page }) => {
await page.goto("/dashboard");
// BAD: reads once, no retry
// expect(await page.textContent("h1")).toBe("Dashboard");
// GOOD: retries until the heading appears
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();
});
// ============================================
// PART 3: THE OVERLAY
// ============================================
test("waits for the overlay to disappear", async ({ page }) => {
await page.goto("/");
await page.getByRole("button", { name: "Open modal" }).click();
// The overlay covers the button; Playwright waits for the
// "receives events" check to pass before clicking.
await page.getByRole("button", { name: "Confirm" }).click();
});
// ============================================
// PART 4: THE HYDRATION CASE
// ============================================
// The button is server-rendered as disabled until hydration:
// <button disabled>Submit</button>
// Playwright's enabled check waits for the attribute to be removed.
The parts covered the actionability checks, the assertion retry, the overlay wait, and the hydration pattern.
Quick Reference
Actionability Checks
| Check | Fails When | Applies To |
|---|---|---|
| Attached | Not in DOM | All |
| Visible | display:none, visibility:hidden | All |
| Stable | Box moving across frames | Click, hover |
| Receives events | Obscured by overlay | Click, hover |
| Enabled | disabled attribute | Click, fill |
| Editable | readonly | Fill, type |
Web-First Matchers
| Matcher | Retries |
|---|---|
toBeVisible() | Yes |
toBeHidden() | Yes |
toBeEnabled() / toBeDisabled() | Yes |
toHaveText() / toContainText() | Yes |
toHaveValue() | Yes |
toHaveCount() | Yes |
toHaveURL() | Yes |
Timeouts
| Setting | Default | Scope |
|---|---|---|
| Action | 30s | Click, fill |
| Expect | 5s | Web-first assertions |
| Navigation | 30s | page.goto |
| Per-assertion | โ | { timeout } argument |
Best Practices
โ Do This:
// Use web-first assertions
await expect(page.getByText("Saved")).toBeVisible(); // โ
// Let the action wait for actionability
await page.getByRole("button", { name: "Submit" }).click(); // โ
// Disable the button until hydrated
<button disabled={!hydrated}>Submit</button> // โ
โ Don’t Do This:
// Read-then-assert
expect(await page.textContent("h1")).toBe("Dashboard"); // โ
// Hard-coded wait
await page.waitForTimeout(2000); // โ
// Rely on stability for opacity transitions
// (the check does not see opacity) // โ
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Flaky assertion on async data | Read-then-assert | Web-first matcher |
| Click does nothing | Hydration not complete | Disable until hydrated |
| Click lands on overlay | Check waits, but overlay is transparent | Fix the overlay or the z-index |
toBeVisible passes on opacity: 0 | Box exists | The check is about the box |
Real-World Examples
1. Click after actionability
await page.getByRole("button", { name: "Submit" }).click();
2. Visible assertion
await expect(page.getByText("Saved")).toBeVisible();
3. Hidden assertion
await expect(page.getByText("Loading")).toBeHidden();
4. Text assertion
await expect(page.getByRole("heading")).toHaveText("Dashboard");
5. Count assertion
await expect(page.getByRole("listitem")).toHaveCount(3);
6. Custom timeout
await expect(page.getByText("Report")).toBeVisible({ timeout: 30_000 });
7. Disabled until hydrated
<button disabled={!hydrated}>Submit</button>
8. Fill waits for editable
await page.getByLabel("Name").fill("Ana");
9. Not matcher
await expect(page.getByText("Error")).not.toBeVisible();
10. URL assertion
await expect(page).toHaveURL(/\/dashboard/);
Visual
Actionability Flow
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ locator.click() โ
โ โ โ
โ โผ โ
โ Attached? โโnoโโโบ wait โ
โ โyes โ
โ โผ โ
โ Visible? โโnoโโโบ wait โ
โ โyes โ
โ โผ โ
โ Stable? โโnoโโโบ wait โ
โ โyes โ
โ โผ โ
โ Receives events? โโnoโโโบ wait โ
โ โyes โ
โ โผ โ
โ Enabled? โโnoโโโบ wait โ
โ โyes โ
โ โผ โ
โ Click โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Web-First vs Value Assertion
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ WEB-FIRST โ
โ expect(locator).toHaveText("X") โ
โ โ retries until the text is "X" or timeout โ
โ โ
โ VALUE โ
โ expect(await locator.textContent()).toBe("X") โ
โ โ reads once, fails immediately if not ready โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Hydration Gap
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Server-rendered HTML โ
โ <button>Submit</button> โ enabled, visible โ
โ โ โ
โ โผ โ
โ Playwright clicks โ no handler yet โ nothing happens โ
โ โ โ
โ โผ โ
โ JavaScript loads, handler attached โ
โ โ
โ Fix: <button disabled> until hydration โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
The Overlay Wait
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ <div class="modal-overlay" /> โ
โ <button>Confirm</button> โ
โ โ โ
โ โผ โ
โ Hit-test at button center โ overlay โ
โ โ โ
โ โผ โ
โ "Receives events" fails โ wait โ
โ โ โ
โ โผ โ
โ Overlay removed โ click โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary
| Item | Value |
|---|---|
| Actionability checks | Attached, visible, stable, receives events, enabled, editable |
| Web-first assertions | Retry until pass or timeout |
| Value assertions | Read once, no retry |
| Action timeout | 30s default |
| Expect timeout | 5s default |
| Hydration gap | Checks cannot see it; disable until ready |
| Opacity | Not caught by the visible check |
Key takeaways:
- The actionability checks are the contract for every action. Playwright waits for the element to be attached, visible, stable, able to receive events, and enabled before it clicks or fills. The failure message names the check that did not pass.
- Web-first assertions retry; value assertions do not.
expect(locator).toHaveText()retries until the condition passes.expect(await locator.textContent()).toBe()reads once and fails immediately if the value is not ready. - The visible check is about the box, not the opacity. An
opacity: 0element passestoBeVisible(), and the stability check does not wait for a color or opacity transition. Use a web-first assertion on the final state. - The hydration gap is the one case the checks cannot catch. A server-rendered button can be enabled before its handler is attached, and Playwright will click it and nothing will happen. Disable the button until hydration.
- The overlay is caught by the receives-events check. A button covered by a modal is not actionable, and Playwright waits for the overlay to disappear before clicking.
Remember: Auto-waiting is the checks plus the retries. The checks gate the action, and the assertions retry the condition. Use web-first assertions for anything that reads from the DOM, let the actions wait for actionability, and fix the hydration gap on the application side. When a test is flaky, the cause is usually a value assertion where a web-first assertion belongs, or a hard-coded wait that is either too short or too long.
Stop using slow, ad-bloated tool sites! ๐คฎ
๐ Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
โ
Finance (Mortgage, Interest, Inflation)
โ
Tech (Base64, JSON, Dev Suite, IP)
โ
Health (BMI, BMR, TDEE)
โ
Productivity (Timer, Workspace, QR)
โก๏ธ Fast & Private
๐ No data leaves your device
๐ 100% Free
๐ Use it now: https://tools.kandz.me
๐ Bookmark itโyouโll need it later!