Free tools Windows power users keep installed
One-click scans. No signup required.
First identify which timeout expired: Playwright’s test, assertion, action, or navigation timeout is different from Applitools Eyes’ visual MatchTimeout. Read the exact error and the operation at the top of the failing stack trace before changing a limit. If the page is simply not ready for a visual checkpoint, wait for an application condition—such as a loading spinner disappearing—before calling eyes.check().
Identify which timeout failed
A timeout near eyes.check() does not by itself prove that Eyes’ MatchTimeout expired. The failure may belong to Playwright or to an application operation immediately before the checkpoint. Use the message, call log, and stack trace to locate the operation that was waiting.
| Failure surface | What it usually means | First place to inspect |
|---|---|---|
Timeout of 30000ms exceeded attributed to a Playwright test |
The test body, fixture setup, or beforeEach exceeded the test budget. |
Playwright’s test timeout configuration or a scoped test timeout. |
| An assertion call log waiting for a locator or text | The auto-retrying assertion did not pass within its own timeout. | expect.timeout or the timeout option on that assertion. |
| A click, fill, or other locator action times out | The action could not complete within its action budget, often because the target was not in the required state. | The action’s timeout and the locator’s state. |
page.goto() or navigation times out |
Navigation did not complete within its navigation budget. | The navigation timeout and page/network behavior. |
An error during eyes.check() or visual comparison |
Checkpoint work, an application still loading, or Eyes visual matching may be involved. | Wait for UI readiness, then inspect the Eyes error and installed SDK version. |
| A failure in fixture setup, teardown, or a hook | The relevant fixture or hook scope may have its own timeout behavior. | The test report, fixture setup/teardown, and hook timing. |
Playwright’s timeout guide documents a 30,000 ms default test timeout and a separate 5,000 ms default for auto-retrying assertions. The test timeout includes the test function, fixture setup, and beforeEach; the assertion timeout is independent. Action and navigation timeouts are separately configurable. These are documented defaults, not proof that a particular operation is the source of your failure.
Wait for the page state the checkpoint needs
If the screenshot is captured while the application is loading, increasing a global timeout can hide the symptom without making the checkpoint reliable. Wait for a condition that means the UI is ready for the visual comparison. For example, if the page displays a spinner until its content is available:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
await page.waitForSelector('.spinner', { state: 'detached' });
await eyes.check('Dashboard');Use the condition that matches your application: a spinner becoming hidden or detached, a key element appearing, or another meaningful readiness signal. Avoid waiting for an arbitrary amount of time when the application can tell the test that it is ready.
Applitools documents a Playwright waitBeforeCapture callback for capture synchronization, including a locator wait for a spinner to become hidden. Check the Applitools guidance on animations and loading artifacts for the API pattern that fits your integration. Its framework-native approach is preferable to guessing how long the page will take.
Change the timeout that owns the failure
Playwright test timeout
If the test body, setup, fixture work, or beforeEach genuinely needs more time, adjust the test timeout at the appropriate scope rather than changing unrelated limits. A per-test override can keep the exception local:
import { test } from '@playwright/test';
test('visual review of a slow report', async ({ page }) => {
// Test steps
}, { timeout: 60_000 });For a project-wide change, Playwright’s documented configuration uses the timeout setting in the test configuration. Scope the increase narrowly where possible: one unusually slow test may not justify giving every test a larger budget.
Assertion timeout
If an auto-retrying assertion is the operation that expires, adjust its timeout—not the Eyes MatchTimeout. Playwright supports a project-level expect.timeout and a timeout option for an individual assertion. Keep the assertion focused on the state being verified.
Action and navigation timeouts
If the stack trace points to a locator action or page.goto(), inspect that operation’s timeout and the reason it cannot finish. A click timeout may indicate that the target is not actionable; a navigation timeout may indicate delayed server or network behavior. Raising the test timeout alone does not necessarily change the operation’s own limit.
Eyes MatchTimeout
MatchTimeout applies to Eyes’ wait for an image to stabilize toward a baseline match. Applitools Support’s Match Timeout article documents a two-second default and describes retries and a per-step override. That article dates to 2021, and the units depend on the SDK, so verify the setting and syntax for the Eyes package installed in your project before applying an example. MatchTimeout is not a replacement for Playwright’s test timeout.
Check integration and version differences
Applitools’ current integration documentation describes fixture-based Playwright integration, including importing an enhanced test from @applitools/eyes-playwright/fixture and using the eyes fixture. Its Playwright integration guide and updated SDK article published March 11, 2026 discuss this approach and a gradual migration path. Projects using a previous or standard SDK may have different setup and APIs; confirm the package version and integration style before copying fixture or MatchTimeout code.
Troubleshoot the cause before widening limits
- Save the full error and stack trace. Note the exact timeout message and the last operation in the call log, rather than inferring the owner from the test name.
- Check readiness at the failing checkpoint. Add a condition-based wait for the element or state the screenshot needs, then run the test again.
- Inspect trace and logs. Determine whether time was spent in test setup, an assertion, a locator action, navigation, or Eyes comparison.
- Consider environmental delays. Applitools lists unstable networks, delayed application servers, third-party components, and CPU or memory bottlenecks as possible contributors to synchronization difficulty. Look for repeatable evidence before raising a timeout globally.
- Use fixed sleeps only when necessary. Applitools describes a fixed sleep as its least-recommended synchronization choice: it wastes time on fast runs and can still be too short on slow ones. If no deterministic readiness condition is available, make any delay bounded and intentional.
- Verify SDK-specific settings. Check the API and units against the installed Eyes SDK and the Playwright version in the project; do not assume an older support example applies unchanged.
Or skip the browser setup
If your goal is a screenshot rather than a Playwright test or baseline comparison, ScreenshotNeo provides a one-request website screenshot API. It accepts a URL and returns an image or PDF; for a screenshot, a cURL request looks like this:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for authentication and request options. ScreenshotNeo accepts cookie or consent banners before capture and removes 60+ known consent platforms, newsletter popups, and chat widgets; these steps can each be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and whether the request was billed. Its MCP server provides screenshot tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month—no card required.
Frequently Asked Questions
Is Eyes MatchTimeout the same as a Playwright timeout?
No. MatchTimeout is for Eyes’ visual stabilization and comparison; Playwright has separate test, assertion, action, and navigation timeouts.
Why does `eyes.check()` time out when the page looks loaded?
The error alone does not identify the owner. Inspect the full message, stack trace, and call log to distinguish checkpoint work, application readiness, Playwright limits, and Eyes matching.
Should I add a fixed sleep before every visual check?
No. Prefer waiting for a meaningful application condition; fixed sleeps can waste time or remain too short when page speed changes.
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.
