To add visual testing to an existing Cypress project, install Applitools’ Cypress SDK, run its setup command, provide an Applitools API key, and add Eyes checkpoints to a Cypress spec. Cypress still handles navigation and interaction; Eyes captures selected page states and compares them with approved baselines.
What Applitools Eyes adds to Cypress
Cypress tests verify behavior such as opening pages, filling forms, and clicking buttons. Applitools Eyes adds visual checkpoints to those journeys so you can review how a page looks, not only whether its interactions work. A first run establishes a baseline; later runs compare new captures with it. The Applitools overview explains this workflow: Modern Cross Browser Testing with Cypress and Applitools.
Install and configure the Eyes Cypress SDK
These steps assume Cypress is already installed in the project. Applitools’ published setup example uses the following commands:
-
From the project root, install the SDK as a development dependency:
Free tools Windows power users keep installed
One-click scans. No signup required.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.npm install @applitools/eyes-cypress --save-dev -
Run the SDK setup tool:
npx eyes-setup -
Set an Applitools API key before running visual tests. The vendor examples use the
APPLITOOLS_API_KEYenvironment variable. Keep the real key in your local environment or CI secret store rather than committing it to source control.
Applitools says eyes-setup configures the SDK as a Cypress plugin and adds Cypress commands; it can also import TypeScript definitions. See the vendor’s Cypress visual-testing setup guide and API-key and configuration example. These examples do not establish a current Cypress/Node compatibility matrix or SDK version, so check the package documentation and release notes for your project’s versions before adopting the integration.
Add visual checkpoints to a Cypress test
Keep the existing Cypress journey, and place Eyes calls at states worth reviewing. The core sequence is cy.eyesOpen, one or more cy.eyesCheckWindow checkpoints, then cy.eyesClose. For example, adapt this pattern to an existing spec and application:
describe('account page visual checks', () => {
it('captures the loaded page and completed form state', () => {
cy.visit('/account');
cy.eyesOpen({
appName: 'My application',
testName: 'Account page'
});
cy.eyesCheckWindow('Account page loaded');
cy.get('[name="email"]').type('[email protected]');
cy.get('button[type="submit"]').click();
cy.eyesCheckWindow('Account form completed');
cy.eyesClose();
});
});The selector, route, and test data are examples; use selectors and data that make sense for your app. Put a checkpoint after a meaningful visual state is ready, such as a completed page load or form interaction, rather than after every low-level action. The vendor’s cross-browser guide describes the checkpoint workflow: Applitools Eyes with Cypress.
Review baselines and handle dynamic content
Approve the initial appearance deliberately
The first run has no existing baseline to compare against. Review the captured state and establish the intended appearance; subsequent runs can then surface differences for review. A visual difference is a prompt to assess the change, not by itself proof that the application is broken.
Choose how variable regions should be compared
Unpredictable content, such as a gallery that displays different popular images, can create differences unrelated to a layout regression. Applitools’ examples describe using a layout region or a Layout match level when the content itself should not drive a failure but the structure still matters. The tradeoff is important: relaxing comparison for variable content can reduce irrelevant diffs, while ignoring too large a region may conceal a meaningful visual change. Keep the affected region as narrow as practical and review the result against what the test is meant to protect.
Rank #4
Choose browser and viewport coverage
Cross-browser visual checks are an optional coverage choice, not a requirement for every test. Select browsers and viewport sizes based on the environments your application supports and the visual states users rely on. More combinations create more results to review, so plan how the team will triage and approve baseline differences. The Applitools guide describes browser and viewport configuration, but does not supply an independent performance benchmark: cross-browser Cypress guidance.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common setup problems
-
The setup command or package install fails: Confirm you are in the Cypress project root and that Cypress is already installed. Check your project’s Node and Cypress versions against the current SDK package documentation; the cited setup articles do not specify a current compatibility matrix.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Best Value
-
Eyes cannot authenticate: Confirm
APPLITOOLS_API_KEYis available in the shell or CI job that launches Cypress, and that the value is valid. Do not put a live key in a committed configuration file. -
No visual comparison appears: Check that the spec actually reaches
cy.eyesOpen, includes acy.eyesCheckWindowcall after the target state is ready, and finishes the test withcy.eyesClose. -
Every run reports differences in changing content: Stabilize test data where possible, or apply an appropriately narrow layout-oriented comparison strategy to the region whose content is intentionally variable. Avoid masking areas that contain UI the test should validate.
-
There are too many results to review: Reduce browser and viewport combinations to the supported coverage matrix and prioritize the states with the greatest user impact. Expand coverage when the team can review the additional results.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Or skip the browser setup
If you need a clean screenshot rather than a Cypress visual regression test, ScreenshotNeo offers a one-request screenshot API. It does not replace Cypress interaction tests or Eyes baseline comparisons.
Quick Recap
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 removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for free.
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.
