To add Percy visual regression checks to Cypress, install the Percy CLI and Cypress SDK, import the SDK in Cypress’s support file, add cy.percySnapshot() after the page reaches a stable state, set your project token as PERCY_TOKEN, and run Cypress through percy exec. Cypress captures screenshots; Percy adds cloud-based visual comparison and review.
What Cypress and Percy each do
Cypress can capture screenshots locally with cy.screenshot() and automatically captures screenshots for test failures during cypress run by default. Percy’s Cypress integration adds snapshots, comparison against visual baselines, and a dashboard workflow for reviewing changes. Percy’s described service also renders snapshots across browsers and responsive widths, while a Cypress run uses the browser selected for that run. Cypress documents its screenshot command; see also Percy’s Cypress walkthrough.
As an Amazon Associate I earn from qualifying purchases.
| Need | Cypress screenshot | Percy snapshot workflow |
|---|---|---|
| Capture an image | cy.screenshot() saves a screenshot as part of the Cypress run. |
cy.percySnapshot() sends a snapshot into Percy’s visual workflow. |
| Visual baseline review | Screenshot capture alone does not provide Percy’s comparison and review workflow. | Percy provides cloud comparison and a dashboard for reviewing visual changes. |
| Setup and operations | Uses Cypress and its screenshot configuration. | Adds Percy packages, a project token, a CLI command, and an external dashboard. |
Set up Percy in an existing Cypress project
1. Install the packages
If Cypress is not already installed, add it as a development dependency using the package manager used by the project, then open Cypress to configure end-to-end or component testing. Cypress lists installation options for npm, Yarn, pnpm, and Bun in its installation guide.
Free tools Windows power users keep installed
One-click scans. No signup required.
For an npm project, install Percy’s CLI and Cypress integration:
#1 Best Overall
- 14" diagonal, 1366x768 resolution, HD BrightView LED, Glossy NON-TOUCH Display
npm install --save-dev @percy/cli @percy/cypressUse the equivalent command for your repository’s package manager. Percy’s walkthrough is a setup guide rather than versioned API documentation, so verify the import and command against the versions recorded in your lockfile and current package documentation.
2. Register the Cypress support module
Import the integration in the Cypress support file so its custom command is available to tests:
import '@percy/cypress';Place the import in the support file configured for your project. The exact path and whether the project uses JavaScript or TypeScript depend on the Cypress configuration; follow the existing support-file convention rather than creating a second support entry.
Recommended Free Tools
3. Provide the Percy project token
Create or select a Percy project and set its project token in the environment as PERCY_TOKEN. Store it in your local environment or CI secret store. Do not commit a real token to the test source or repository.
4. Add a snapshot at a meaningful checkpoint
Call cy.percySnapshot() after Cypress assertions establish that the intended content is ready. For example:
Rank #2
- 256 GB SSD of storage.
- Multitasking is easy with 16GB of RAM
- Equipped with a blazing fast Core i5 2.00 GHz processor.
describe('product page visual state', () => {
it('captures the product after it loads', () => {
cy.visit('/products/example');
cy.get('[data-testid="product-title"]')
.should('be.visible')
.and('contain', 'Example product');
cy.percySnapshot('Product page - loaded');
});
});Use descriptive names that identify the state being captured, such as a page after a filter is applied or a component after a menu opens. A snapshot belongs after the relevant interaction and readiness checks, not in the middle of a transition or before asynchronous content appears.
5. Run Cypress through Percy
Run the suite with Percy’s CLI wrapping the Cypress command:
npx percy exec -- cypress runIn CI, start the application and wait until it is responding before invoking this command. Cypress warns that starting a server in the background and immediately launching tests can create a race condition; use the CI system’s readiness check or a wait utility so Cypress does not visit an unavailable app. See Cypress CI guidance.
6. Review visual changes
Open the Percy dashboard to review the snapshot comparison. A difference is a reason to inspect the change, not automatically a defect: confirm whether the UI change was intended before accepting an updated baseline.
Make Percy comparisons stable and useful
Wait for a real readiness condition
Prefer an assertion that confirms a selector is visible or content is present over an arbitrary sleep. A fixed delay can be too short on a slow run and unnecessarily long on a fast one. Cypress’s visual testing guide covers strategies for reliable visual checks.
Rank #3
- WINDOWS 11 | STABLE PERFORMANCE: Powered by Intel Celeron N4020 processor and Windows 11 system, this laptop delivers stable performance for everyday computing tasks. It supports web browsing, online learning, document editing, email communication, and basic office work with optimized power efficiency, providing a practical and reliable experience for essential daily use for daily use.
- 15.6” FHD IPS DISPLAY: Features a 15.6-inch Full HD IPS display with narrow bezels, offering wider viewing angles and clearer image details compared to standard panels. The improved screen-to-body ratio enhances visual experience for study, reading, document work, and video playback, making it suitable for both productivity and entertainment use.
- 4GB DDR4 + 128GB eMMC STORAGE: Equipped with 4GB DDR4 memory and 128GB eMMC storage for everyday basics such as browsing, documents, email, and online learning platforms. The built-in TF card slot supports storage expansion up to 1TB, giving you more flexibility for files, photos, videos, and daily documents. TF card not included.
- CONNECTIVITY & PORTS: Includes 1× TF card slot, 2× USB 3.2 Gen1 ports, and 2× full-featured Type-C ports (USB 3.2 Gen1). The Type-C ports support data transfer, charging, and video output, enabling flexible connection with external devices such as monitors, storage, and peripherals for daily work and study use.
- LIGHTWEIGHT DESIGN | ONLINE COMMUNICATION: Designed with a slim, portable profile, this laptop is easy to carry for school, commuting, and travel. A built-in 1MP front camera supports online classes, video meetings, remote communication, and everyday conferencing. The 3300mAh battery works with the low-power system design to support practical daily use, while thermal optimization helps maintain quieter operation during extended tasks.
Control data and rendering conditions
- Stub variable API responses with
cy.intercept()and fixtures where that suits the test, so changing backend data does not create unrelated image differences. - Keep browser and viewport settings consistent between runs when comparing the same visual state.
- Mask only genuinely variable regions, and keep masks narrow enough that important regressions remain visible.
- Avoid snapshotting while images, fonts, or other page content are still loading.
Account for animation
Cypress screenshot configuration includes controls for timers and CSS animations, but interaction-specific animation settings do not guarantee that every unrelated animation elsewhere on the page has stopped. Prefer a stable checkpoint and test the project’s actual page behavior before relying on animation settings alone. See Cypress screenshot options.
Choose the right capture scope
Use an element-level snapshot when the component itself is the subject and surrounding page changes would create noise. Use a full-page snapshot when page-wide layout is what you need to review. Keep the suite to high-value checkpoints rather than capturing every incidental test state.
Manage generated screenshots
Cypress’s default local screenshot folder is cypress/screenshots. Generated test assets are commonly excluded from source control; check the repository’s ignore rules and CI artifact policy so screenshots are retained only where they are useful. Cypress’s configuration reference describes screenshot settings.
Troubleshooting common setup failures
cy.percySnapshot is not a function: confirm@percy/cypressis installed and imported by the support file loaded by this Cypress configuration. Check the support-file path, module format, and locked SDK version.- Percy reports a missing token: check that
PERCY_TOKENis present in the environment of the Percy CLI process. In CI, verify the secret is configured for the relevant job and available to the branch or pull request context. - The page is blank or incomplete in a snapshot: assert on the content that must be present before the snapshot, and ensure the application server and required test data are ready.
- Visual diffs appear on every run: stabilize variable API responses, viewport and browser conditions; wait for fonts and images; avoid mid-animation captures; and review whether a dynamic region needs a tightly scoped mask.
- CI intermittently cannot load the app: do not rely on backgrounding the server and immediately running Cypress. Add an explicit readiness check before
npx percy exec -- cypress run. - A changed baseline is unexpected: inspect the actual UI and test state before approving it. Do not accept a baseline solely to make a failing comparison disappear.
Or skip the browser setup
If you need a clean website screenshot rather than Cypress-driven visual regression tests, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return an image or PDF; here is the cURL form, with the options and response details in 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.webpIt removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are not billed. An MCP server lets AI agents use screenshot tools, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month with no card.
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 minuteFrequently Asked Questions
Can I use Cypress screenshots without Percy?
Yes. Cypress provides cy.screenshot() and captures screenshots for test failures during cypress run by default. Percy is needed for its separate cloud comparison and review workflow.
Should I add a Percy snapshot to every Cypress test?
No. Add snapshots at a small number of stable, high-value UI states where visual review will answer a useful question.
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.
