In Cypress, “snapshot testing” can mean comparing a saved JavaScript value or DOM state, or comparing screenshot pixels. For value snapshots, install and register @cypress/snapshot, save and review a baseline, then commit it with the test. For visual regression, use a visual-testing plugin such as cypress-visual-regression, control the browser conditions, and review every generated diff before updating a baseline. These approaches catch different kinds of change; choose the one that matches what you need to protect.
What snapshot testing means in Cypress
A snapshot is a saved representation of expected output. A later test run captures the output again and compares it with that baseline. A difference signals that something changed; it does not, by itself, tell you whether the change is a bug.
There are two distinct approaches commonly called snapshot testing in Cypress:
- Value or DOM snapshots: compare a serialized object, string, array, or selected DOM element state. The
@cypress/snapshotadd-on provides a.snapshot()command for this purpose. - Visual snapshots: compare rendered screenshot pixels against baseline images. The community
cypress-visual-regressionplugin documents this workflow with.compareSnapshot().
A value snapshot can reveal changes to data or structure without showing what the user sees. A visual snapshot can catch layout, color, and rendering changes, but is sensitive to differences in rendering conditions. They are complementary, not interchangeable.
Free tools Windows power users keep installed
One-click scans. No signup required.
When to use each kind
| Question | Value or DOM snapshot | Visual screenshot snapshot |
|---|---|---|
| What is compared? | A value, object, string, array, or DOM element representation. | Rendered image pixels. |
| What does failure indicate? | A structural or serialized-value difference. | An image difference, potentially reported as mismatched pixels and a difference percentage. |
| Where is the baseline? | Snapshot files associated with the test; the official article describes a saved snapshots.js file. |
Baseline images in the plugin’s base directory, with actual and optional diff images available for review. |
| What needs controlling? | Which fields are serialized, and whether their values are stable and meaningful. | Viewport, browser, fonts, locale, device-pixel assumptions, time, animation, and external content. |
| Best fit | Stable data or selected DOM state. | Visual appearance of a component, page, or integrated flow. |
Use ordinary Cypress assertions for the central user-visible behavior even when you add snapshots. Assertions make the test’s intent explicit; snapshots provide a broader reviewable comparison.
Set up value snapshots with @cypress/snapshot
Install the add-on
Install the package as a development dependency:
npm i -D @cypress/snapshotRegister the command
In the Cypress support file used by your project, register the package once:
require('@cypress/snapshot').register()The exact support-file path depends on your Cypress project configuration. Put the registration in the support code that is loaded by the specs where you intend to call .snapshot().
Take a focused snapshot
For example, snapshot a stable result from a function:
it('adds two numbers', () => {
cy.wrap(add(2, 3)).snapshot()
})The command can also be used on strings, arrays, objects, and DOM elements. You can label a snapshot with an optional name:
cy.wrap(result).snapshot({ name: 'negatives' })A spec can contain multiple snapshots. The add-on stores them under the full test name and an index when a test has more than one snapshot. Keep each snapshot tied to a meaningful state so a failing comparison points reviewers toward a specific expectation.
Snapshot a deliberate projection, not an unstable whole object
Large application objects often contain timestamps, generated identifiers, or fields unrelated to the behavior under test. Snapshotting all of them can create noise and make updates difficult to review. Select only the stable shape that matters:
it('shows the expected account summary', () => {
cy.visit('/account')
cy.get('[data-cy=account-name]').should('contain', 'Ada')
cy.window().then((win) => {
const state = win.store.getState()
const summary = {
name: state.account.name,
plan: state.account.plan,
featureKeys: Object.keys(state.account.features).sort()
}
cy.wrap(summary).snapshot({ name: 'account-summary' })
})
})This is an implementation pattern, not an assumption about your app’s store API: replace win.store and the fields with the application state actually available to your test. If the state is not exposed on window, snapshot a response or other value your test already obtains.
For DOM snapshots, target a component or region that expresses the behavior under test rather than the entire page. Broad DOM snapshots are likely to include unrelated changes and can be harder to interpret than a focused assertion.
Create visual regression snapshots
The cypress-visual-regression community plugin documents a baseline-generation mode and a regression mode. Install it with:
npm install cypress-visual-regressionRegister addCompareSnapshotCommand() in Cypress support code, and configure configureVisualRegression(on) in setupNodeEvents. The plugin’s documented setup and configuration details are available in its project documentation.
Use the comparison command on the element or page you want to protect. For example:
Recommended Free Tools
it('keeps the checkout summary visually stable', () => {
cy.visit('/checkout')
cy.get('[data-cy=checkout-summary]').compareSnapshot('checkout-summary', {
errorThreshold: 0.2
})
})The route and selector must match your application. The plugin documents these forms:
cy.compareSnapshot(name)cy.compareSnapshot(name, errorThreshold)cy.compareSnapshot(name, options)
Its documented default errorThreshold is 0. The plugin describes the threshold as a percentage under which image differences are considered a failure. The example’s 0.2 is illustrative; choose and validate a threshold against your own test and review the plugin’s interpretation rather than assuming it is a universal tolerance.
Visual results can include the actual image, baseline image, and a diff image; the plugin also documents a mismatched-pixel count and difference percentage. Use those artifacts to understand where and how the render changed.
Generate and review baselines deliberately
- Run the plugin in its documented base mode to create or replace baseline images.
- Inspect the resulting images before accepting them. Confirm that the page loaded correctly, the expected content is present, and the baseline does not capture a transient or broken state.
- Commit the reviewed baseline alongside the test code so later comparisons use an intentional expected result.
- Use regression mode for ordinary verification runs. Keep actual, base, and diff artifacts available when a comparison fails.
- Update a baseline only after deciding that the visual change is intended and reviewing the new image.
Make snapshot tests reproducible
Snapshots are only useful when a meaningful change is distinguishable from incidental variation. Cypress’s browser-based component testing renders components in a real browser; Cypress documentation also highlights automatic waiting, spies and stubs, network interception, and clock control. Those capabilities can help make component state predictable, and Cypress lists official component-testing mounting libraries for React, Angular, Vue, and Svelte. See Cypress component testing documentation.
Before generating or comparing baselines, stabilize the inputs and rendering conditions that matter:
- Data and network: seed known data or intercept requests with controlled responses. Avoid depending on mutable production-like content or third-party services.
- Time: control the clock when dates, countdowns, or time-dependent labels appear.
- Viewport and browser: use the same viewport, browser, device-pixel assumptions, and relevant configuration for baseline and regression runs.
- Fonts and locale: ensure fonts are available and use a consistent locale, since text wrapping and formatting affect pixels.
- Animation: disable or wait out nonessential animation so captures represent a stable frame.
- Scope: capture a focused component or region when that is the behavior being tested. Avoid unrelated page content.
For value snapshots, normalization can be more effective than trying to make every value deterministic: remove volatile fields from the selected projection and preserve only meaningful, stable data.
Rank #4
Update a snapshot without hiding a regression
A mismatch is a prompt to investigate, not a reason to immediately regenerate the baseline. Cypress’s official snapshot article advises inspecting snapshots in the Test Runner or in the saved snapshots.js file because they become part of the test. Follow the same review discipline for image baselines.
- Open the failing test output and identify the changed value or image region.
- Check whether the application behavior or rendering inputs changed unexpectedly. For visual tests, compare actual, base, and diff images; for value tests, inspect the serialized snapshot.
- If the change is a defect, fix the application or stabilize the test inputs, then rerun the comparison.
- If the product change is intended, review the new output against the requirement, regenerate the baseline using the add-on or plugin’s documented update/base workflow, and include the baseline change in the same review as the code change.
- Run the test again in normal comparison mode to confirm the committed baseline is the one the test expects.
Do not use silent-failure or update-snapshots options to make a mismatch disappear without review. The visual plugin documents options around silent failure and snapshot updates; their exact behavior should be checked in its documentation before use in a project workflow.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteCommon problems and fixes
.snapshot() is not recognized
The add-on may not be installed or registered in the support file loaded by that spec. Confirm that @cypress/snapshot is a project dependency, that the registration line runs, and that the spec uses the intended support configuration.
Every run changes the value snapshot
The captured object may include timestamps, random IDs, or fields that vary between requests. Control those inputs or snapshot a deliberately selected and normalized projection instead of the entire object.
Visual diffs fail even though the page looks correct
Check for differences in viewport, browser, fonts, locale, device-pixel assumptions, animation timing, and data. Then inspect the diff image to see whether the difference is meaningful. A threshold can reduce sensitivity to small pixel changes, but setting it too permissively can hide real regressions.
The baseline image is blank or incomplete
Verify that the route and selector are correct, the page has finished loading the relevant content, and test data or network responses are available. Wait for a meaningful application condition rather than relying on an arbitrary delay where possible.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Best Value
Baseline updates are hard to review
Reduce the snapshot scope, split separate meaningful states into separate snapshots, and retain image artifacts for visual comparisons. For object snapshots, trim incidental fields. Review snapshot changes alongside the application change that caused them.
A visual test is flaky in CI
Make the capture environment consistent and remove uncontrolled content. Confirm the same browser, viewport, fonts, locale, and device-pixel settings are used in baseline and CI runs. Control time, network data, and animation, and investigate each mismatch before changing the baseline.
Choose component or end-to-end coverage
Use Cypress Component Testing when the visual state belongs to an isolated component and can be mounted with controlled props or data. It runs the component in a real browser and supports Cypress testing capabilities such as waiting, stubbing, interception, and clock control. Use end-to-end tests when the appearance depends on an integrated user flow or multiple application parts working together. A practical suite often uses focused component snapshots for reusable UI and a smaller number of end-to-end visual checks for important composed states.
Or skip the browser setup
If the goal is a website screenshot rather than a Cypress assertion against your application, ScreenshotNeo offers a screenshot API and MCP server. A single GET request can return PNG, JPEG, WebP, or PDF; the API is not a replacement for application-level Cypress assertions or baseline review.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
cURL example for a website screenshot, using 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.webpScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, 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 screenshots. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does Cypress include a built-in `.snapshot()` command?
The value snapshot workflow described here uses the `@cypress/snapshot` add-on, which registers that command.
Can a snapshot test replace Cypress assertions?
No. Keep explicit assertions for the key behavior; snapshots add a broader saved-output comparison.
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 →Can I use value and visual snapshots in the same project?
Yes. They compare different outputs and can cover different risks, provided their baselines are stable and reviewed.
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.
