Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteUse a Locator with a retrying assertion when your Playwright test needs to verify that an element eventually reaches a state. For example, await expect(page.getByRole('status')).toBeVisible() waits for visibility and fails if the condition is not met within the configured assertion timeout. For setup that needs a specific locator state rather than an assertion, use locator.waitFor(). For an action such as clicking a button, Playwright already waits for the element to be actionable.
Choose the wait that matches the condition
First decide what must be true before the test continues: that an element is in the DOM, that it is visible, that it disappears, or that it has particular text or a particular count. Then express that condition with a Locator API. Locators are re-resolved when used, which makes them more resilient to page re-renders than holding onto a particular DOM node. Playwright describes locators as central to its auto-waiting and retry behavior (Playwright locators).
| Need | Use | What it does |
|---|---|---|
| Verify the page eventually shows the expected result | await expect(locator).toBeVisible() |
Retries the assertion until it passes or its assertion timeout expires. |
| Wait for a locator to reach a particular state as setup | await locator.waitFor({ state: 'visible' }) |
Waits for the requested locator state and throws a timeout error if it is not reached. |
| Interact with a control | await locator.click() |
Automatically waits for the locator and relevant actionability checks before clicking. |
| Check visibility right now, without waiting | await locator.isVisible() |
Returns an immediate boolean; it does not retry until the element appears. |
Best default: assert the result in Playwright Test
If the element’s appearance is part of what the test is verifying, use a web-first assertion. It retries the condition instead of checking once and immediately passing or failing.
import { test, expect } from '@playwright/test';
test('shows the confirmation', async ({ page }) => {
const confirmation = page.getByRole('status');
await expect(confirmation).toBeVisible();
});Choose an assertion that describes the actual outcome. Use toBeVisible() to verify visible presence, toHaveText() to verify content, or toHaveCount() to verify how many matching elements are present. See the official Playwright Test assertions reference for available web-first assertions and configuration.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
When the assertion is preferable to a separate wait
An assertion both waits for the condition and reports a test failure if the expectation is not met. If the test’s purpose is to establish that a confirmation appeared, asserting its visibility says more than waiting and then continuing without checking the outcome.
Wait explicitly for a Locator state
Use locator.waitFor() when a step needs to pause until a locator reaches a specific state, without making that step itself a web-first assertion.
const results = page.getByTestId('search-results');
await results.waitFor({ state: 'visible' });
// Continue with work that requires visible results.The supported states are attached, detached, visible, and hidden. The default is visible, but spelling out the intended state makes the precondition clear. The wait resolves immediately if the locator already meets the requested state. See the Locator API reference for the installed-version details.
What each state means
attached: the element is present in the DOM; it does not have to be visible.visible: the element has a non-empty bounding box and is notvisibility: hidden.hidden: the element is detached, has an empty bounding box, or isvisibility: hidden.detached: the element is no longer present in the DOM.
Playwright’s visibility definition counts an element with opacity: 0 as visible. Visibility is therefore not identical to “a person can see and interact with this element.” A click has additional actionability checks, including whether the element receives pointer events rather than being covered by another element (Playwright actionability).
For an action, let Playwright auto-wait
A separate visibility wait is often unnecessary when the next step is an action. For example:
await page.getByRole('button', { name: 'Continue' }).click();For a click, Playwright waits for the locator to resolve to one element and for the relevant actionability checks to pass. These include visibility, stability, receiving events, and enabled state. Add an explicit wait only when the test has a distinct condition to establish before the action—for example, a results panel must be visible before some other setup step begins. The actionability documentation describes the checks for different actions.
Rank #3
Build a locator for the intended element
Prefer locators that describe the page in terms users recognize, especially for interactive controls. For example, use page.getByRole('button', { name: 'Save' }) for a button with the accessible name “Save.” Other built-in locator methods include getByText(), getByLabel(), getByPlaceholder(), getByAltText(), getByTitle(), and getByTestId() (locator guidance).
- Make the target unambiguous. If an operation requires one element but the locator matches several, narrow it or state the intended match explicitly. A timeout may be a locator ambiguity problem rather than a slow page.
- Scope into frames when needed. If the target is inside an iframe, locate it through a frame locator before finding the element inside it.
- Use a test ID when it is the right contract. A test ID can be useful when user-facing text or accessible semantics are not a stable way to identify the target.
Why not use isVisible or a fixed sleep?
isVisible() checks immediately
await locator.isVisible() returns a boolean for the current state; it does not wait for the element to become visible. Use await expect(locator).toBeVisible() to verify eventual visibility or await locator.waitFor({ state: 'visible' }) to wait explicitly. The distinction is documented in the Locator API.
A sleep waits for time, not the condition
A fixed delay can waste time when the page is ready quickly and still be too short when it is slow. It also does not prove that the required element appeared. Prefer a retrying assertion or a locator-state wait tied to the condition the test needs.
page.waitForSelector() is not the recommended new pattern
The Page API still provides page.waitForSelector(), but marks it as discouraged in favor of locator-based waits and web-first assertions (Page API). Use a Locator-based pattern in new tests so the condition and target are expressed together.
Set and diagnose timeouts
A locator wait that fails to reach its requested state throws a TimeoutError. The Locator API reference describes its default timeout as zero, with the effective default configurable through page or browser-context timeout settings. Web-first assertions use the configured expect timeout; the assertion reference documents a five-second default. These are different settings, and project configuration and installed Playwright version matter. Check the relevant API references and your configuration rather than assuming a timeout value applies everywhere (Locator wait; assertions).
When a wait times out, check the condition before extending the timeout:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
- Confirm the locator points to the intended element and does not match multiple targets.
- Check whether the element is inside a frame and, if so, scope through the appropriate frame locator.
- Decide whether the test needs DOM attachment, visibility, disappearance, text, or another specific outcome.
- Inspect whether the page actually reached that state. Increase the timeout only when the intended condition is correct and the expected page behavior can reasonably take longer.
Common failures and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| The visibility assertion times out | The locator is wrong, the page never shows the target, the target is hidden, or it is inside a frame. | Check the locator and actual page state; use the correct frame context and confirm that visibility—not just attachment—is required. |
isVisible() is false, then the element appears later |
isVisible() reports the current state and does not retry. |
Replace the immediate check with await expect(locator).toBeVisible() or an explicit visible-state wait. |
| A click fails even though a visibility wait passed | Visibility alone does not establish every click actionability condition; for example, another element may intercept pointer events or the target may not be stable or enabled. | Let click() perform its auto-waiting and inspect the actionability failure. Do not treat a visible-state wait as proof that a click must succeed. |
| The operation complains about more than one matching element | The locator is ambiguous for an operation requiring one target. | Refine the locator so it identifies the intended element. |
| The wait completes for a hidden-looking element | Playwright treats opacity: 0 as visible under its documented visibility definition. |
Use a condition that reflects the actual behavior being tested; visibility alone does not mean fully opaque or unobstructed. |
| The test waits but proceeds without proving the result | A setup wait was used where the test should assert the expected outcome. | Use a web-first assertion such as toBeVisible(), toHaveText(), or toHaveCount(). |
Or skip the browser setup
If your goal is to capture a website screenshot rather than interact with page elements in a Playwright test, ScreenshotNeo provides a one-request screenshot API. A response returns a PNG, JPEG, WebP, or PDF, and its API documentation is at screenshotneo.com/docs.
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://stripe.com
-o shot.webpScreenshotNeo removes supported cookie and consent banners, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides screenshot tools for AI agents, including Claude, Cursor, and other MCP clients. The Free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Does locator.waitFor() wait for the element if it is already visible?
Yes. It resolves immediately when the locator already meets the requested state.
Does Playwright consider an element with opacity: 0 visible?
Yes, under Playwright’s documented visibility definition. Visibility does not guarantee that the element is unobstructed or actionable.
Should I use waitForSelector() in a new Playwright test?
Prefer a Locator-based wait or web-first assertion; the Page API marks waitForSelector() as discouraged.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
