Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
If Playwright appears to ignore a toBeVisible() timeout, first check that the assertion is awaited, that you changed the assertion timeout rather than only the test timeout, and that the locator matches the intended visible element. In Playwright Test, toBeVisible() is an asynchronous web-first assertion: it retries until the condition is satisfied or the assertion timeout expires. Without the failing test, imports, Playwright version, error log, and page state, there is no way to identify which cause applies.
Start with the assertion and the timeout in the error
Use await expect(locator).toBeVisible() with the expect imported from Playwright Test. The awaited promise lets the test runner observe the assertion’s result and wait through its retries. Playwright describes web-first assertions as re-testing until the expected state is met; its examples show the call log waiting for a locator until an assertion succeeds or times out. See Playwright’s assertions guide.
import { test, expect } from '@playwright/test';
test('shows the saved status', async ({ page }) => {
await page.goto('/settings');
await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByTestId('status')).toBeVisible();
});If this assertion lives in a helper, return or await it so the caller does not finish before it settles:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
async function expectStatusVisible(page) {
await expect(page.getByTestId('status')).toBeVisible();
}
// In the test:
await expectStatusVisible(page);Then read the exact failure and call log. A message such as expect.toBeVisible with timeout 5000ms tells you the matcher used a 5,000 ms assertion budget. Compare that value with the configuration you intended to change. A timeout is not evidence by itself that Playwright ignored a setting; it may indicate the setting was applied to a different timeout scope.
#1 Best Overall
Choose the timeout scope that actually expired
Playwright’s current timeout documentation lists a default expect timeout of 5,000 ms for each assertion and a separate default test timeout of 30,000 ms for each test. These are documented defaults, not guaranteed values for every project: configuration, per-call options, and the installed version can change behavior. See Playwright’s timeout guide and TestConfig reference.
| Budget | What it limits | How to change it |
|---|---|---|
| Assertion / expect timeout | How long an async matcher such as toBeVisible() retries for its expected state. Default documented by Playwright: 5,000 ms. |
Set expect.timeout in configuration or pass { timeout: ... } to this matcher. |
| Test timeout | The total time budget for an individual test. Default documented by Playwright: 30,000 ms. | Use test-timeout configuration or test.setTimeout() when the whole test needs a larger budget. |
Increasing the test timeout alone does not increase the assertion timeout. If the call log shows that the expect matcher expired, adjust that matcher’s budget rather than only the overall test budget.
Raise the timeout for one assertion
Use a per-call override when one particular interface transition is legitimately slower. The following example gives this matcher a 10,000 ms budget:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →await expect(
page.getByRole('button', { name: 'Save' })
).toBeVisible({ timeout: 10_000 });The value is an example configuration, not a claim about how long a page should take. Keep the timeout proportional to the behavior being tested; a longer wait can make a genuine delay less likely to fail the test, but it also delays reporting when the condition never occurs.
Set the project-wide expect timeout
If a consistent assertion budget is appropriate across the project, configure it in playwright.config.ts:
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: { timeout: 10_000 },
});Check that the test command loads this configuration file and that no local matcher option overrides the value. Configuration is project-wide; the per-call option is narrower and makes the special case visible next to the assertion.
Verify the locator points to the right visible node
Playwright documents toBeVisible() as ensuring that the locator points to an attached and visible DOM node. That verifies a state for the locator’s match; it does not prove that your selector identifies the intended control, status, or page. Review the selector, page or frame, accessible name, and call log. The LocatorAssertions reference documents the matcher and its options.
- Confirm the test is on the expected page and frame when it reaches the assertion.
- Check that the selector or role/name combination matches the intended element, rather than a similarly named node elsewhere.
- Check whether the locator matches one element or several, and whether the intended requirement is that a particular element be visible or that any item in a collection be visible.
- Inspect whether the target is attached and visible at the assertion point, rather than assuming that an earlier render or action guarantees it remains so.
If the requirement really is that the first matching item in a collection be visible, Playwright documents using .first():
await expect(page.getByRole('listitem').first()).toBeVisible();Use this only when the first match is the intended target. If the requirement is that a specific item appears, make the locator identify that item rather than masking a broad or ambiguous selector with .first().
Debug the page state instead of adding a fixed sleep
Run the test with Playwright Inspector to pause and examine the state near the failing assertion:
npx playwright test --debugStep through the test, inspect the locator and page, and compare what the browser shows with what the selector is expected to match. Playwright’s debugging guide explains the Inspector workflow.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →A fixed delay such as await page.waitForTimeout(2000) is usually a poor fix: a delay can be too short on a slower run and unnecessarily long on a fast one. The Frame API says waitForTimeout() should only be used for debugging and recommends waiting on meaningful signals, such as a selector becoming visible or a network event. See the Frame API reference.
When the page is asynchronous, express the actual condition the test needs. For example, wait for a meaningful status or result locator through a web-first assertion, or use an appropriate network signal when the behavior depends on a specific request. Do not increase timeouts until you know whether the page is simply delayed or the locator can never match the required state.
Use this troubleshooting sequence
- Confirm the runner and import. Use Playwright Test’s
expect, commonly imported from@playwright/test, and writeawait expect(locator).toBeVisible(). If a helper contains the assertion, ensure it returns or awaits the promise. - Read the failure and call log. Note the timeout printed for
toBeVisibleand the locator Playwright says it was waiting for. - Identify the expired budget. If the matcher timed out, configure
expect.timeoutor the matcher’stimeoutoption. If the whole test timed out, review the test timeout separately. - Validate the target. Check the page or frame, selector, accessible name, number of matches, and the actual DOM state at the assertion.
- Inspect the failing moment. Run
npx playwright test --debugand step through the page with Inspector. - Wait for a real condition. Replace arbitrary sleeps with the relevant UI or network signal when the state is genuinely asynchronous.
Version, reliability, and runtime considerations
The LocatorAssertions API notes that toBeVisible() was added in Playwright v1.20 and its timeout option in v1.18. Check the installed Playwright version and verify the matching API reference if a project uses an older release. The official documentation establishes expected behavior and controls, but cannot identify the cause in a particular test without its assertion, import/helper path, configuration, version, error log, and page state.
For reliability, make the assertion describe the user-visible condition that matters and use the narrowest appropriate timeout scope. A longer timeout can accommodate a legitimately slow transition but cannot repair a wrong locator, an element that never attaches, or a missing await. When diagnosing a failure, preserve the call log and reproduce the page state rather than treating every timeout as a performance problem.
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 minuteOr skip the browser setup
If the debugging task is to capture the page for inspection or documentation rather than to assert its state inside a Playwright test, ScreenshotNeo is a screenshot API and MCP server for developers. A one-request call can return an image or PDF; the API offers controls such as waiting for a selector and choosing a viewport. It does not replace a Playwright assertion when the test needs to verify visibility.
cURL example (see the ScreenshotNeo API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie and consent banners are accepted like a visitor, and more than 60 known consent platforms, newsletter popups, and chat widgets can be removed before capture; each step can be turned off.
- Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and billing status.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdffor Claude, Cursor, and other MCP clients. - The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.
Sign up for 1,000 free screenshots a month—no card required.
What to include when asking for help
To make a failing toBeVisible() timeout diagnosable, include the assertion and locator, relevant imports and helper code, the applicable part of playwright.config.ts, installed Playwright version, exact error and call log, and what the page or DOM shows at that point. Remove secrets and private data from logs before sharing them.
Recommended Free Tools
Frequently Asked Questions
Does toBeVisible() wait for an element to appear?
Yes. In Playwright Test, the async web-first assertion retries until the locator is visible or the assertion timeout expires.
Why does changing test.setTimeout() not fix this assertion?
The test timeout and expect timeout are separate budgets. A matcher can reach its own timeout before the overall test budget ends.
Can I use toBeVisible() to prove a locator is correct?
No. It checks visibility and attachment for the locator’s match; inspect the selector and page state to confirm it identifies the intended element.
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.
