Recommended Free Tools
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To use @simonsmith/cypress-image-snapshot, install it, register its Node plugin in cypress.config.ts, register its custom command in your Cypress support file, then call cy.matchImageSnapshot() after the page is in the state you want to verify. The plugin compares the captured image with a saved baseline, writes a diff when the images differ, and fails the test by default. The exact Cypress compatibility and update flags depend on the installed package release, so verify its metadata before upgrading.
What the plugin does
@simonsmith/cypress-image-snapshot adds visual snapshot comparisons to Cypress tests. After a test drives the application to a chosen state, the command captures a screenshot and compares it with a saved baseline. When a mismatch is found, the plugin can generate a diff image; by default, the mismatch also fails the test.
This is useful for catching unintended visual changes that ordinary assertions may not detect, such as a shifted element, missing image, altered spacing, or changed colors. It does not decide whether a visual change is a defect: a developer still needs to inspect the diff and decide whether the baseline should change.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsCheck compatibility before installing or upgrading
Compatibility information is not fully aligned across the package sources. The README says the plugin was tested with Cypress 13.x and 14.x, while the Cypress plugin directory lists version 11.0.0 as requiring Cypress 15.10.0 or newer. Those statements may describe different releases. Check the metadata for the exact package version you intend to use and the Cypress version in your project rather than assuming either statement applies universally. See the package README and the npm package metadata.
Cypress should already be installed as a peer dependency. If it is not, add Cypress to the project using the installation method appropriate for your application before configuring the snapshot package.
Install and register the plugin
The integration has two parts: a Node event plugin in the Cypress configuration, and a custom command in the support file that your tests load.
1. Add the package
npm install --save-dev @simonsmith/cypress-image-snapshot
# or
yarn add --dev @simonsmith/cypress-image-snapshot2. Register the Node event plugin
In cypress.config.ts, import the plugin function and call it from setupNodeEvents:
PC 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 & 11Outdated 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 matchimport { defineConfig } from 'cypress'
import { addMatchImageSnapshotPlugin } from '@simonsmith/cypress-image-snapshot/plugin'
export default defineConfig({
e2e: {
setupNodeEvents(on) {
addMatchImageSnapshotPlugin(on)
},
},
})3. Register the Cypress command
In the support file used by the relevant test type, import and call the command registration function. For an end-to-end project, that is commonly cypress/support/e2e.ts; make sure it matches the support-file configuration in your project.
import { addMatchImageSnapshotCommand } from '@simonsmith/cypress-image-snapshot/command'
addMatchImageSnapshotCommand()You can provide shared defaults when registering the command. For example, this applies a failure threshold to snapshots unless an individual call overrides it:
addMatchImageSnapshotCommand({ failureThreshold: 0.2 })TypeScript users can add @simonsmith/cypress-image-snapshot/types to the project’s tsconfig.json types so TypeScript recognizes the added Cypress command. The package includes its own declarations; follow the package README for the relevant project configuration.
Capture a page or element in a test
Call the command after navigation and after any actions needed to reach the state under test. With no argument, the README says the test title supplies the snapshot name.
it('shows the login form', () => {
cy.visit('/login')
cy.matchImageSnapshot()
})You can pass an explicit name or nested path, or call the command on a selected element to capture that element rather than the whole page:
cy.matchImageSnapshot('login')
cy.matchImageSnapshot('some/dir/image')
cy.get('#login').matchImageSnapshot()The command can also receive per-snapshot options. The plugin combines comparison settings from jest-image-snapshot with Cypress screenshot settings. The documented examples include:
failureThresholdto set the permitted difference threshold.comparisonMethod: 'ssim'to choose the structural similarity comparison method.capture: 'viewport'to specify the screenshot capture mode.blackoutto apply the relevant Cypress screenshot blackout option.
Use only options supported by the installed package and Cypress version. Set shared defaults at command registration when they should apply consistently; pass an options object to a particular snapshot when that case needs different comparison or capture behavior.
Understand baselines, diffs, and snapshot paths
The documented flow takes a Cypress screenshot and checks for a corresponding saved image under <rootDir>/cypress/snapshots. When a comparison produces a diff, the generated image goes under <rootDir>/cypress/snapshots/__diff_output__. Explicit names and nested paths let you organize snapshots, but the path rules need to align with the spec layout.
For Cypress 10 and newer, the README notes that common ancestor paths were removed from generated screenshots. Its e2eSpecDir option, which defaults to cypress/e2e/, can preserve the intended relationship between spec paths and snapshot directories. If your specs live somewhere else, set this option to match the directory structure used by specPattern; otherwise, snapshots may be stored or resolved under an unexpected path.
Update snapshots and control CI failures
By default, a visual mismatch fails the test. The README documents three controls for baseline updates and failure behavior. The command-line syntax differs for Cypress 15.10 and newer versus older Cypress versions:
| Purpose | Cypress 15.10+ | Older Cypress versions |
|---|---|---|
| Update snapshot baselines | --expose updateSnapshots=true |
--env updateSnapshots=true |
| Allow diffs without failing tests | --expose failOnSnapshotDiff=false |
--env failOnSnapshotDiff=false |
| Require snapshots to exist | --expose requireSnapshots=true |
--env requireSnapshots=true |
Use the syntax appropriate to the Cypress version actually installed. The requireSnapshots setting can be useful in CI when a missing baseline should be treated as an error rather than silently accepted.
Review a baseline change deliberately
Updating snapshots replaces the reference image used for future comparisons. Treat an update as a review operation: inspect the changed baseline and any diff, confirm that the visual change is intentional, and commit the accepted baseline with the associated test or UI change. Turning off failures can be useful in a controlled workflow, but it also means a mismatch need not stop the run; teams should decide how those diffs will be reviewed.
Free tools Windows power users keep installed
One-click scans. No signup required.
Make visual comparisons reproducible
Screenshot comparisons are sensitive to rendering differences. Cypress’s visual testing guidance recommends generating and comparing screenshots in the same environment with a fixed viewport. Keep the browser and rendering environment, viewport dimensions, test data, and application state consistent between baseline creation and comparison. Otherwise, the test may report environmental noise rather than a meaningful product change. See Cypress’s visual testing guide.
Use stable test setup before capturing: wait for the relevant content, avoid transient states such as an animation mid-frame, and use deterministic data where possible. The plugin supports screenshot configuration through its command options, while Cypress’s screenshot API also supports capturing an application or selected element. For the plugin-specific options available to your release, consult the README.
Troubleshooting common problems
The command is undefined
- Likely cause: The custom command was not registered, or Cypress is not loading the support file where it is registered.
- Fix: Confirm the import and
addMatchImageSnapshotCommand()call are in the support file configured for that test type, then rerun the test.
Plugin setup errors when Cypress starts
- Likely cause: The Node plugin was not added to
setupNodeEvents, or installed package and Cypress versions are incompatible. - Fix: Check the import path and call to
addMatchImageSnapshotPlugin(on)incypress.config.ts. Compare the exact package release’s compatibility metadata with your installed Cypress version.
Snapshots appear in an unexpected directory or are not found
- Likely cause: The spec directory and the plugin’s
e2eSpecDirdo not describe the same layout, especially in Cypress 10+ projects. - Fix: Compare
e2eSpecDirwith the directory used byspecPattern, then check the resulting snapshot path undercypress/snapshots.
A test fails even though the page looks unchanged
- Likely cause: The baseline and current run were captured in different environments or at different viewport sizes, or the page contains transient visual content.
- Fix: Standardize the rendering environment and viewport, stabilize the page before capture, then inspect the generated diff in
__diff_output__before deciding whether any baseline should be updated.
A mismatch is not failing the test
- Likely cause:
failOnSnapshotDiff=falsewas supplied through Cypress configuration or command-line options. - Fix: Remove that override if visual differences should fail the run. On Cypress 15.10+, use
--exposefor the documented controls; on older versions use--env.
A missing snapshot does not fail CI
- Likely cause: The run is not configured to require an existing baseline.
- Fix: Enable
requireSnapshots=trueusing the command-line form documented for your Cypress version.
When a hosted visual-testing service may fit better
The local plugin approach keeps image comparison and files in your project or CI infrastructure, but your team owns baseline organization, review of diffs, and consistency of rendering environments. Cypress describes hosted visual-testing services as another approach that can manage capture, storage, comparison, and review, and may provide consistent cloud rendering across browsers and viewport widths. The Cypress guide discusses Percy and Sauce Labs Visual in this context; it does not establish current prices. Choose based on who should store the images, which browsers and viewports you need, how rendering consistency is achieved, and how reviewers will approve changes.
Or skip the browser setup
If you need a screenshot from a URL rather than an assertion inside a Cypress test, ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call GET endpoint returns an image or PDF; it is not a replacement for Cypress’s test runner or baseline comparison workflow.
For API parameters, formats, and options, see the ScreenshotNeo documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each of those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for 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.
Sign up for ScreenshotNeo and get 1,000 free screenshots a month with no card.
Frequently Asked Questions
Can I use this plugin to compare a single component instead of a full page?
Yes. Call matchImageSnapshot() on the Cypress element returned by a selector, for example cy.get('#login').matchImageSnapshot().
Does updating a baseline automatically approve a visual change?
No. Updating writes the reference image used by later comparisons; review the image and diff yourself before accepting and committing the change.
Can ScreenshotNeo replace Cypress visual regression tests?
No. ScreenshotNeo captures a URL as an image or PDF; the Cypress plugin compares test captures with saved baselines and can fail tests on differences.
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.
