How to Prevent Cypress Screenshots from Capturing Too Soon
Stop flaky Cypress screenshots by synchronizing on application state, network requests, and stable UI signals before calling cy.screenshot().

Put a retryable query and assertion, or a named network wait, immediately before cy.screenshot(). Cypress captures the state currently rendered in the browser; it does not keep retrying until your desired visual state appears. The Cypress documentation summarizes the practice as: “Take a snapshot only after you confirm the page is done changing.” See the Cypress visual testing guide and screenshot API.
Why Cypress screenshots are captured too soon
A screenshot can be early when the test has finished a browser action but the application has not finished rendering the resulting state. Common examples include:
- An API request is still populating a list.
- A loading skeleton has not been replaced by real content.
- A click started a transition or modal update.
- Images, fonts, ads, or third-party widgets are still changing layout.
- A test uses a fixed delay that is shorter than the slowest run.
- A failure screenshot is taken asynchronously after the application has moved on.
Cypress query and assertion commands retry until they pass or time out. cy.screenshot() is a capture command, not a readiness assertion. Synchronize on the state your test actually needs instead of waiting an arbitrary number of milliseconds. See Cypress retry-ability.
The reliable pattern: assert the final state, then capture
Use a named request when data arrival is the readiness signal, then assert visible content before taking the snapshot.

describe('items page', () => {
it('captures the loaded list', () => {
cy.intercept('GET', '/api/items', { fixture: 'items.json' }).as('getItems')
cy.visit('/items')
cy.wait('@getItems')
cy.get('[data-testid="items-loading"]').should('not.exist')
cy.contains('.todo-list li', 'write tests').should('be.visible')
cy.screenshot('items-loaded')
})
})
The request wait handles data synchronization; the assertion confirms the rendered DOM state. Keep both when a request can finish before the UI has painted its final state.
Wait for user-driven changes without arbitrary delays
After an action, assert the result of that action. Cypress retries the query until the application reaches the expected state.
it('captures a newly added todo', () => {
cy.visit('/todos')
cy.get('.new-todo').type('write tests{enter}')
cy.contains('.todo-list li', 'write tests')
.should('be.visible')
.and('contain.text', 'write tests')
cy.screenshot('todo-added')
})
This is more reliable than cy.wait(1000), because the assertion adapts to the actual response and render time. Use a fixed delay only when there is no observable application signal, and keep it as short and narrowly scoped as possible.
Synchronize with the exact application signal
Wait for a network request
cy.intercept('POST', '/api/checkout').as('checkout')
cy.get('[data-testid="pay"]').click()
cy.wait('@checkout').its('response.statusCode').should('eq', 200)
cy.get('[data-testid="receipt"]').should('be.visible')
cy.screenshot('receipt')
Use an intercept pattern that matches the request your page actually sends. If several requests can match, assert the response body or status and then check the resulting DOM.
Wait for a loading marker to disappear
cy.visit('/dashboard')
cy.get('[data-testid="dashboard-spinner"]').should('not.be.visible')
cy.get('[data-testid="dashboard-content"]').should('be.visible')
cy.screenshot('dashboard-ready')
Wait for a meaningful element
cy.get('[data-testid="profile-name"]')
.should('be.visible')
.and('have.text', 'Ada Lovelace')
cy.screenshot('profile')
Prefer stable data-testid attributes or semantic selectors over classes that are changed by styling refactors.
Wait for a URL or route transition
cy.get('[data-testid="open-settings"]').click()
cy.url().should('include', '/settings')
cy.get('h1').should('have.text', 'Settings')
cy.screenshot('settings')
Wait for an element-level state
cy.get('[data-testid="save"]').click()
cy.get('[data-testid="save"]').should('be.disabled')
cy.get('[data-testid="saved-message"]').should('be.visible')
cy.screenshot('saved')
Animations, timers, and transitions
cy.screenshot() uses disableTimersAndAnimations: true by default. Cypress freezes JavaScript timers and CSS animations during capture, which helps stabilize the capture itself. It does not prove that the page has reached the intended application state.
cy.screenshot('stable-card', {
disableTimersAndAnimations: true,
padding: 16
})
You can configure defaults globally:
// cypress/support/e2e.js
Cypress.Screenshot.defaults({
disableTimersAndAnimations: true,
capture: 'viewport',
blackout: ['[data-testid="clock"]']
})
waitForAnimations and animationDistanceThreshold belong to action commands such as .click(). They help Cypress decide whether an element is settled enough to interact with; they are not page-wide screenshot waits. If a transition is part of the behavior under test, wait for an application-level completion signal. If animation is not under test, disable it in the test environment or with a test-only stylesheet.
Make visual captures repeatable
- Fix the viewport: set the same width and height for local and CI runs.
- Pin the browser and operating system: browser versions, display scaling, fonts, and rendering engines affect pixels.
- Stub live APIs: use deterministic fixtures when production data can change.
- Control time: use a fixed clock when timestamps appear in the UI.
- Mask unavoidable motion: blackout only ads, clocks, animated media, or third-party regions that cannot be controlled.
- Prefer focused captures: capture a meaningful element when a full page would include unrelated volatility.
beforeEach(() => {
cy.viewport(1440, 900)
cy.clock(new Date('2026-01-15T12:00:00Z').getTime())
})
it('uses deterministic data', () => {
cy.intercept('GET', '/api/notifications', {
fixture: 'notifications.json'
}).as('notifications')
cy.visit('/inbox')
cy.wait('@notifications')
cy.get('[data-testid="inbox"]')
.should('be.visible')
.screenshot('inbox-panel')
})
Cypress captures images but does not perform baseline comparison itself. Add a visual-regression integration that fits your CI and review process if you need approval workflows, diffs, or collaboration. The Cypress guide discusses integrations and visual-testing workflows.
Choosing the right screenshot scope
| Goal | Capture | Why |
|---|---|---|
| Verify one component | cy.get(selector).screenshot() |
Reduces unrelated layout noise. |
| Verify the visible page | cy.screenshot({ capture: 'viewport' }) |
Matches what a user sees in the viewport. |
| Verify a long document | cy.screenshot({ capture: 'fullPage' }) |
Includes content below the fold; requires stable lazy loading. |
| Protect private or volatile regions | blackout selectors |
Keeps dynamic pixels out of comparison. |
cy.get('[data-testid="invoice"]')
.should('be.visible')
.screenshot('invoice', {
blackout: ['[data-testid="live-clock"]']
})
Diagnose which screenshot is early
Manual screenshot looks one state behind
Inspect the command immediately before cy.screenshot(). Replace a generic existence check with a state assertion such as visible text, a disappeared spinner, an enabled button, or a completed request.
The screenshot shows a later state than the failure
Cypress screenshot capture is asynchronous and the documentation describes it as taking around 100 ms. An automatic failure screenshot can therefore show the application after the moment that caused the failure. Use the test video or CI replay to reconstruct ordering. Automatic failure screenshots are controlled by screenshotOnRunFailure and are not enabled in cypress open by default.
// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: true,
retries: {
runMode: 2,
openMode: 0
}
})
When retries are enabled, Cypress retains screenshots from failed and retried attempts with an attempt suffix. Retries are disabled by default unless configured.
A fixed wait passes locally but fails in CI
CI usually has different CPU, network, browser, and font conditions. Replace the delay with a request alias and a DOM assertion. If no signal exists, expose a test-only readiness marker from the application.
Full-page capture contains blank lazy-loaded areas
Trigger or observe lazy loading before capture. Scroll the relevant region, wait for its images to complete, and assert the content that must appear.
cy.visit('/catalog')
cy.get('[data-testid="catalog"]').scrollTo('bottom')
cy.get('[data-testid="last-product-image"]')
.should('be.visible')
cy.contains('[data-testid="product"]', 'Desk Lamp')
.should('be.visible')
cy.screenshot('catalog-full', { capture: 'fullPage' })
A third-party widget keeps changing pixels
Stub the widget, block it in the test environment, or mask only its selector. Avoid relaxing a comparison threshold for the whole page when only a small region is unstable.
Performance, reliability, and cost considerations
- Assertions are usually cheaper than repeated screenshots: wait once for the final state, then capture one meaningful artifact.
- Keep fixtures small and deterministic: large live responses increase rendering variance.
- Element screenshots reduce review noise: they also make failures easier to diagnose.
- Full-page screenshots can be slower: they include more layout, images, and lazy-loaded content.
- Keep CI environments consistent: matching browser, fonts, viewport, and device scale improves reliability.
- Do not infer readiness from Cypress command timing: capture duration is approximate and application rendering is independent.
Or skip the browser setup
If you need a clean screenshot of a URL outside the Cypress run, ScreenshotNeo provides a GET API that returns PNG, JPEG, WebP, or PDF. The browser still needs to be synchronized for an in-test assertion, but a hosted capture can remove setup for documentation, reports, or repeatable page artifacts.

See the ScreenshotNeo API documentation for the available options. This minimal call captures Stripe as WebP:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webp
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com'
})
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`)
if (!res.ok) throw new Error(`Screenshot failed: ${res.status}`)
const fs = await import('node:fs/promises')
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()))
ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and each response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 screenshots. Create a free ScreenshotNeo account.
Troubleshooting checklist
- Identify the exact state the image must represent.
- Find the request, DOM marker, URL, or event that proves that state.
- Wait for that signal with
cy.wait(), a retryable query, or an assertion. - Assert visible text or attributes, not only element existence.
- Disable or control animations that are not under test.
- Fix viewport, browser, fonts, clock, and API fixtures.
- Capture the smallest useful scope and mask only unavoidable dynamic regions.
- Review videos or retries when a failure screenshot appears out of order.
FAQ
Does cy.screenshot() wait for network idle?
No. It captures the current rendered state. Wait for the specific request or rendered condition your test depends on.
Is cy.wait(1000) ever acceptable?
It can be a last resort for an external condition with no observable signal, but a named request or retryable assertion is more reliable.
Should I turn off disableTimersAndAnimations?
Usually no. Keep the default when animation is not the behavior under test. If animation itself matters, synchronize on its completion and choose capture settings deliberately.
Why do screenshots differ only in CI?
Browser version, operating system, fonts, display scale, viewport, live data, and third-party content can all change pixels. Standardize those inputs and use fixtures or targeted masks.
Can Cypress compare screenshots by itself?
Cypress creates screenshots; visual regression comparison and baseline review require an integration or external service.


