To update a Cypress visual snapshot baseline, first identify the image-comparison integration that owns it, reproduce the test, review the diff, and approve the new image through that integration’s workflow. Cypress itself captures screenshots but does not compare images or provide one universal baseline-update command.
That distinction prevents a common mistake: treating a debugging screenshot from cy.screenshot() as an approved visual-regression baseline. The correct command and file location depend on your plugin or hosted service.
What a Cypress snapshot baseline is—and what it is not
A baseline is the previously approved image against which a new render is compared. A visual test captures the current page or component, compares it with that image, and presents a diff for review. Cypress’s built-in cy.screenshot() only captures an image; it does not perform the comparison itself.
By default, Cypress writes screenshots to the project’s screenshots folder. Names follow the spec and test unless you pass a name, and duplicate names receive a numeric suffix unless overwrite behavior is enabled. Cypress also captures screenshots automatically when tests fail during cypress run. Those failure artifacts help diagnose a test, but they are not visual-regression baselines.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Find the integration that owns your baseline
- Search the spec and support files. Look for the visual command used by your project, such as a plugin-specific snapshot command, a task, or a service SDK. Do not assume that
cy.screenshot()is the command that updates the baseline. - Inspect project configuration and package scripts. The package name, Cypress task registration, and CI script usually reveal whether images are stored locally or uploaded to a hosted service.
- Read that integration’s current update instructions. Cypress has no universal flag for this operation. One plugin may update files after an environment variable is set; a hosted service may require approving a build in its web interface.
Cypress’s visual-testing guidance lists active open-source options including Cypress Image Diff, Cypress Image Snapshot, Cypress Visual Regression, and Visual Regression Diff. Pixeleye is described as a self-hostable review platform. Commercial integrations named by Cypress include Applitools, Argos, Chromatic, Happo, LambdaTest SmartUI, Percy (BrowserStack), Sauce Labs Visual, SmartBear VisualTest, and Wopee.io. Features and availability can change, so verify the provider’s documentation before relying on a particular command.
Safe baseline-update procedure
1. Confirm that the product change is intentional
Start from the pull request or design change that explains why the page should look different. A baseline should never be updated merely because a diff is inconvenient.
2. Reproduce the comparison
Run the same Cypress spec and capture the failing result. Examine the expected image, actual image, and diff image. Check for shifted layout, missing content, font changes, color changes, and one-pixel edges rather than judging only the overall appearance.
3. Make rendering deterministic before approving anything
- Assert that the intended page state is visible before the snapshot.
- Use a fixed viewport and, where practical, pin the browser and operating-system environment used for comparisons.
- Control clocks for dates, timers, and countdowns with
cy.clock(). - Use fixtures and
cy.intercept()to return stable network data. - Disable, finish, or otherwise account for animations. Cypress notes that
waitForAnimationsandanimationDistanceThresholdaffect action commands; they do not guarantee that a screenshot will avoid an unrelated animation already in progress. - Mask a small region containing uncontrollable ads or third-party widgets instead of increasing a tolerance for the entire image.
4. Approve through the owning tool
For a local plugin, update the image files produced by that plugin after reviewing the diff. Those files are often committed with the code change so reviewers can see exactly what was accepted. For a hosted service, use its build or pull-request review workflow and approve only the intended change. Keep the approval associated with the same code review whenever possible.
Free tools Windows power users keep installed
One-click scans. No signup required.
5. Run the suite again
A successful update should leave the new image as the expected baseline and produce a clean comparison on a second run. If the result changes between runs, investigate timing, data, fonts, viewport, browser, or environment drift instead of repeatedly accepting images.
Example: make the state stable before a snapshot
The following pattern is integration-neutral. Replace visualSnapshot with the command supplied by your comparison tool.
describe('billing dashboard', () => {
beforeEach(() => {
cy.clock(new Date('2026-09-29T12:00:00Z'));
cy.intercept('GET', '/api/invoices', {
fixture: 'invoices.json'
}).as('invoices');
});
it('matches the approved dashboard image', () => {
cy.visit('/billing');
cy.wait('@invoices');
cy.get('[data-cy=dashboard-ready]').should('be.visible');
cy.get('[data-cy=loading-spinner]').should('not.exist');
visualSnapshot('billing-dashboard');
});
});This code stabilizes the clock and API response, waits for a meaningful readiness assertion, and avoids capturing the loading state. The exact snapshot command and update mechanism remain integration-specific.
Local image plugins versus hosted visual services
| Consideration | Local plugin | Hosted service |
|---|---|---|
| Baseline storage | Usually image files in the repository or CI artifacts | Managed in the provider’s platform |
| Approval | Review a local or CI diff, then update files | Approve a build or review in a hosted interface |
| Rendering responsibility | Your team stabilizes browser, fonts, viewport, and operating system | The service may provide consistent rendering infrastructure |
| Review features | Depends on your repository and CI setup | May include pull-request review, browser coverage, or viewport coverage; verify current provider capabilities |
| Cost and retention | Infrastructure and repository storage are your responsibility | Pricing, image storage, retention, and limits depend on the provider |
Choose local storage when repository-owned files and direct control matter most. A hosted workflow can reduce rendering-setup work, but it moves baseline management and cost into a third-party system.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Why a new baseline may be wrong
Loading or animation captured
Symptom: the diff changes on every run or contains half-rendered content. Fix: wait for a state assertion, remove loading indicators, and make animation state deterministic. Do not assume Cypress action-command animation settings control the screenshot itself.
Changing data
Symptom: dates, prices, avatars, or list order differ without a code change. Fix: freeze time with cy.clock(), intercept APIs, and use fixtures. For data that cannot be controlled, mask only the affected region.
Environment drift
Symptom: local approval passes but CI fails, or browser upgrades create broad diffs. Fix: use the same viewport and browser where possible, pin versions, and compare in a consistent operating environment.
Wrong artifact or duplicate name
Symptom: you updated an image but the test still compares another file. Fix: inspect the generated path and name. Cypress can add numeric suffixes to duplicate screenshot names unless overwrite is configured; confirm the integration’s own baseline path as well.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Confusing a failure screenshot with a baseline
Symptom: an automatically captured failure image is copied into the expected-image directory. Fix: locate the visual plugin’s expected-image store and use its documented approval flow. Failure screenshots are diagnostic evidence, not approval.
Screenshot capture settings are not baseline approval
Cypress screenshot settings can control capture behavior such as selected-element blackout, screenshot-on-failure, animation or timer handling, and duplicate overwrite. These settings affect what is captured; they do not compare images or approve a visual-regression baseline. Keep capture configuration and comparison-tool configuration conceptually separate when troubleshooting.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need a clean reference image for a page rather than a Cypress-managed visual baseline, ScreenshotNeo provides a website screenshot API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. It is not a replacement for your comparison plugin: you still review and approve the image in your own workflow.
One GET request is enough:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
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(`HTTP ${res.status}`);
require('node:fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));See the ScreenshotNeo documentation for options such as full-page capture, CSS selectors, device and viewport settings, custom CSS and JavaScript, waiting rules, request blocking, cookies, headers, caching, signed links, asynchronous jobs, bulk capture, PDFs, and the usage API. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf to Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account to try it.
FAQ
Does Cypress have an update-snapshots flag?
No universal Cypress flag exists. The integration that performs image comparison defines its own update command or approval process.
Should visual baselines be committed to Git?
For a local plugin, repository-managed images make changes reviewable, but the decision depends on image size, retention policy, and your team’s CI design. Hosted services generally retain baselines in their platform.
Is a full-page snapshot always preferable?
No. Element-level snapshots can reduce unrelated failures when the question is component appearance. Use a full-page image when page-level layout and relationships are what you need to verify.
Recommended Free Tools
Frequently Asked Questions
Can I approve every changed image automatically?
That removes the review step that distinguishes an intentional UI change from a regression. Approve only after examining the expected, actual, and diff images.
Why do screenshots pass locally but fail in CI?
Different browsers, fonts, viewports, operating systems, clocks, network responses, or animation timing can alter pixels. Align those inputs before changing a baseline.
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.
