How to Compare Website Screenshots with Image Overlays in Cypress
Cypress captures screenshots but does not compare them. Add a visual testing integration to review baseline, current, and highlighted difference images.
Cypress can capture a website screenshot with cy.screenshot(), but it does not compare that image with a baseline. To compare screenshots and inspect image overlays, add a visual testing plugin or hosted visual testing service. The integration captures the current page or element, compares it with an approved baseline, and provides views such as a baseline/current comparison and a highlighted pixel-difference image. Cypress explains the visual testing workflow and lists local and hosted integrations.
What an image overlay shows
An overlay places the baseline and current screenshots together so that shifted edges and changed regions are easier to spot. A difference image highlights pixels that differ. These views help locate a change; they do not decide whether that change is a bug. Review the affected area and approve a new baseline only when the change is intentional.
cy.screenshot() is the capture step. A visual testing integration supplies comparison, baseline management, and a review workflow. The exact overlay controls and approval steps depend on the integration you choose.
Set up a reliable Cypress comparison
- Choose a meaningful checkpoint. Navigate to a page or drive a component into the state you want to protect. Capture after the relevant content has loaded and the UI is in a deliberate state.
- Make the page reproducible. Stub changing API responses with
cy.intercept()and fixture data. Use the same browser and rendering environment for baseline and later runs when possible. Cypress disables JavaScript timers and CSS animations during screenshots by default, which helps reduce visual noise. - Add a visual testing integration. Select a local plugin that compares images in your project or CI, or a hosted service that provides its own comparison and review workflow. Follow that integration’s current installation and configuration instructions; setup APIs and compatibility can change.
- Capture and compare. Use the integration’s Cypress command or task to save a baseline on the initial approved run and compare subsequent captures against it. Open the baseline/current view and the highlighted diff when the comparison reports a change.
- Review before updating. Determine whether the difference is an intended UI change, a regression, or rendering noise. Update the baseline only after confirming the intended appearance.
Cypress’s screenshot command documentation covers capture behavior. The comparison command itself comes from the selected integration, so there is no universal built-in Cypress assertion for image overlays.
Choose what to capture
| Capture scope | Use it for | Trade-off |
|---|---|---|
| Element or component | A focused check of a component, such as a navigation bar, card, or dialog. | Unrelated page changes are less likely to obscure the result, and the diff has a clearer owner. The integration must support element capture or the test must arrange a suitable capture. |
| Full page | Overall page layout, long-form content, or regressions spanning multiple sections. | A larger capture can include more dynamic content and create more differences to review. |
Prefer the smallest capture that proves the behavior you care about. Use a full-page image when the page’s overall composition is itself the requirement.
Control visual noise
- Changing API data: use
cy.intercept()with a fixture so the same content appears on each run. - Animations and timers: Cypress disables JavaScript timers and CSS animations during screenshot capture by default. If the surrounding test still has timing-sensitive behavior, wait for the application to reach a stable checkpoint before capture.
- Ads and third-party widgets: if you cannot control their content, mask only the region that changes. Keep exclusions narrow so the comparison still catches meaningful regressions.
- Fonts, viewport, and browser: keep rendering conditions consistent between baseline and comparison runs. Differences in rendering environment can create diffs unrelated to an application change.
- Responsive layouts: capture the viewport widths that matter to the feature. A passing screenshot at one width does not establish that another layout is correct.
Broad thresholds or large masks can hide real changes. Tune exclusions around known variable regions and inspect the diff when changing the comparison settings.
Select a visual testing integration
Cypress documents both local open-source plugins and hosted visual testing services. Local comparison keeps image processing and baseline storage in infrastructure your team manages; hosted services can provide centralized review and service-specific rendering or collaboration workflows. Neither approach is universally best.
Examples listed in the Cypress guide include Cypress Image Diff, Cypress Image Snapshot, Cypress Visual Regression, and Visual Regression Diff for open-source workflows. Hosted options listed there include Applitools Eyes, Argos, Chromatic, Happo, LambdaTest SmartUI, Percy, Sauce Labs Visual, SmartBear VisualTest, and Wopee.io. Treat these as options to investigate, not an endorsement or ranking: confirm current Cypress compatibility, capture scope, review workflow, data handling, and pricing in the relevant product documentation.
| Decision | Questions to check |
|---|---|
| Execution and storage | Does comparison run locally, in CI, or through a hosted service? Where do screenshots and baselines reside? |
| Baseline review | How are changes approved, shared with reviewers, and associated with a code change? |
| Capture coverage | Does it support page and element captures, component testing, and the browser or viewport coverage you need? |
| Dynamic content | Can variable regions be masked or otherwise controlled without weakening the rest of the comparison? |
| Compatibility and cost | Does the current version support your Cypress version and CI setup? What usage, storage, or collaboration limits affect the cost? |
Plugin catalogs and service capabilities change. Check live documentation before pinning a version or choosing a product; avoid relying on an old compatibility note.
Or skip the browser setup
If you need a screenshot image rather than a Cypress baseline comparison, ScreenshotNeo returns a website capture with one API request. It does not replace a visual testing integration’s baseline and overlay review workflow. 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.webpimport 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 request 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; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.
Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
Troubleshooting Cypress screenshot diffs
| Symptom | Likely cause | What to do |
|---|---|---|
cy.screenshot() saves an image but no comparison appears |
Cypress capture alone does not compare images. | Install and configure a visual testing integration, then use its capture and comparison workflow. |
| The same test reports different pixels on repeated runs | Uncontrolled data, third-party content, or a different rendering environment. | Stub changing requests with fixtures, stabilize the browser and viewport, and mask only content that cannot be controlled. |
| A diff contains a large area of expected change | The baseline predates an intentional design or content update. | Review the baseline/current and diff views; approve a new baseline only after confirming the change is intended. |
| A component test fails because unrelated page regions changed | The capture scope is broader than the behavior under test. | Use an element-level capture if the integration supports it, or narrow the test to a component state. |
| The plugin fails to install or run with the current Cypress version | Version requirements or plugin APIs may have changed. | Check the integration’s current package documentation and Cypress compatibility, then select a supported version combination. |
| CI comparisons differ from local results | The browser, operating system, fonts, viewport, or rendering setup may differ. | Make CI and baseline generation use a consistent environment and investigate environment changes before updating baselines. |
Performance, reliability, and cost
Visual comparisons add image capture, storage, and review work to a test run. Capturing every incidental state increases runtime and creates more baselines to maintain. Focus on high-value page or component states, and use targeted captures when they answer the test question.
Reliability depends on repeatable inputs and rendering conditions. Fixtures reduce API variability; a consistent browser and viewport reduce environmental differences; narrow masks contain unavoidable third-party noise. A screenshot assertion can still fail because of a legitimate visual change, so assign review ownership and treat baseline updates as code changes that need inspection.
Local plugins require the team to manage baseline files, CI artifacts, and review processes. Hosted services may centralize comparison and approval, but their current pricing, storage, data handling, and feature limits must be checked directly. The research sources do not establish a universal cost or performance ranking.
FAQ
Does Cypress have a built-in screenshot overlay command?
No. Cypress captures screenshots, while a visual testing integration provides comparison and overlay or diff views.
Should I compare full-page screenshots or elements?
Use element captures for focused component checks and full-page captures when overall page layout is under test.
Should every pixel difference fail the build?
That depends on the integration and test policy. Review reported differences in context, control known variability, and keep masks narrow so meaningful changes remain visible.
