How to Use Applitools Eyes with Cypress Screenshots
Add Applitools Eyes visual checkpoints to Cypress, understand baselines and review, and keep functional assertions alongside screenshot comparisons.
Applitools Eyes adds visual checkpoints to Cypress tests. Cypress drives the application; Eyes captures the rendered UI at selected states and compares each capture with a saved baseline. The first run establishes baselines. Later runs report visual differences for review: accept an intentional UI change to update its baseline, or reject a bug and keep the previous baseline.
Use Cypress assertions for explicit functional conditions, such as whether a heading exists or a submit button is enabled. Use Eyes to catch visual regressions those assertions may miss, such as a broken image or a layout change. The two checks answer different questions and work best together.
1. Install and configure the Eyes Cypress SDK
The setup commands and API pattern below come from Applitools’ tutorial published in 2021. Treat them as a tutorial-documented starting point, not a guarantee of compatibility with current SDK or Cypress versions. Before copying them into a project, check the installed @applitools/eyes-cypress package documentation, supported Cypress versions, and configuration format. Applitools’ current Cypress page describes adding checkpoints to existing Cypress tests and its Ultrafast Grid capability; configuration details can vary by SDK version.
npm install @applitools/eyes-cypress --save-dev
npx eyes-setupThe tutorial says eyes-setup configures the SDK plugin and Cypress commands, and can add TypeScript definitions. Follow the output and configuration changes for the version you install. Do not blindly add an old plugin setup to a project that uses a newer Cypress configuration format.
Eyes also requires an Applitools API key. Create or retrieve the key through your Applitools account, then make it available to the test process as an environment variable. Avoid committing a key to source control. For example, set APPLITOOLS_API_KEY in your CI secret store or local shell environment, following the current SDK’s expected key configuration.
2. Add checkpoints to a Cypress journey
The following illustrates the workflow documented in the 2021 tutorial: open an Eyes test, capture named checkpoints, then close it. Confirm these command names and argument shapes against your installed SDK before using this example. Replace the example origin and selectors with those from your app.
// cypress/e2e/login.cy.js
// Tutorial-era API example: verify it against your installed SDK version.
describe('login visual checks', () => {
it('captures the login page and dashboard', () => {
cy.eyesOpen({
appName: 'Example App',
testName: 'Login journey'
});
cy.visit('http://localhost:3000/login');
// Keep a functional assertion for an explicit behavior.
cy.contains('h1', 'Sign in').should('be.visible');
cy.eyesCheckWindow('Login page');
cy.get('[name="email"]').type('developer@example.com');
cy.get('[name="password"]').type('example-password');
cy.get('button[type="submit"]').click();
cy.contains('h1', 'Dashboard').should('be.visible');
cy.eyesCheckWindow('Dashboard after login');
cy.eyesClose();
});
});This example assumes a locally running app, the tutorial-era Cypress commands, and selectors that exist in the app. Use a non-production test account and test credentials. If the installed SDK uses a different lifecycle or command API, keep the same checkpoint placement but adapt the calls to that SDK.
Choose stable checkpoint states
- Capture after the page has reached the state a user should see, not while it is still loading.
- Name checkpoints for the state or transition, such as
Login pageandDashboard after login. - Capture meaningful states in a journey. A checkpoint after a form submission can reveal a broken success page that a URL or text assertion alone may not catch.
- Keep functional assertions. A visual match does not prove that every underlying interaction or business rule is correct.
- Stabilize variable content where possible. Timestamps, rotating promotions, user-specific data, and animations can create differences that are not product regressions.
3. Run tests and review baselines
- Run the Cypress test with the API key and configuration required by your installed Eyes SDK.
- On the initial run, inspect the captured checkpoints and establish the intended baselines.
- On later runs, review each reported visual difference. Decide whether it represents an intentional design change or an unintended regression.
- Accept an intentional change to update the baseline. Reject a bug-indicating change to retain the prior baseline and investigate the application.
- Keep the review decision tied to the right application state and test. A baseline is useful only when it represents the intended UI.
A screenshot comparison is a signal that something rendered differently; it does not decide whether the difference is good or bad. Human review is part of the workflow.
4. Understand what the screenshot check covers
| Check | Good for | Example |
|---|---|---|
| Cypress assertion | A known, explicit behavior or page condition | The dashboard heading appears after login. |
| Eyes visual checkpoint | Rendered appearance compared with an approved baseline | A logo is missing, spacing shifted, or a page section changed visually. |
Applitools’ Cypress page describes Ultrafast Grid as rendering tests across Chrome, Firefox, Safari, Edge, and mobile viewports in parallel. This is Applitools’ stated cloud-rendering capability; availability and targets depend on the product configuration. It differs from merely running Cypress locally in a browser: the visual service can extend comparison across configured browser and viewport combinations.
5. Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| Eyes commands are undefined | The SDK setup did not register commands, or the tutorial-era setup does not match the installed versions. | Review the setup command output, Cypress support-file loading, and current SDK instructions. Confirm the package supports your Cypress version. |
| Authentication fails | The API key is missing, malformed, or unavailable to the test process. | Check the environment variable in the process that launches Cypress and the key configuration expected by your SDK. Keep secrets out of committed files. |
| A checkpoint is blank or incomplete | The capture ran before the app finished rendering or data had loaded. | Wait for a meaningful app condition with Cypress before taking the checkpoint. Avoid relying on an arbitrary short delay when a visible state can be asserted. |
| Differences appear on every run | The page contains changing data, animation, time-dependent content, or nondeterministic layout. | Use stable test data and consistent app state. Identify which changing region causes the diff and handle it using supported SDK controls if available in your version. |
| The first run has no prior comparison | No baseline exists yet. | Review the initial captures and establish the intended baseline; later executions can report changes against it. |
| A real visual defect passes functional assertions | The assertions only cover their stated conditions, such as text presence, not all rendered content. | Add an Eyes checkpoint at the affected state while retaining assertions for functional requirements. |
| Configuration behaves differently from an old example | The tutorial used SDK and Cypress versions from 2021. | Use the current documentation and configuration format for the versions in the project. Do not assume plugin names, setup behavior, or command signatures stayed unchanged. |
6. Performance, reliability, and cost considerations
Visual checks add capture and comparison work to a test run. Keep the suite focused on useful user-visible states rather than capturing every intermediate action. The exact runtime and service cost depend on your project and account configuration; the sources here do not establish a benchmark or a universal price.
For reliable comparisons, make test data and navigation conditions repeatable, wait for the intended page state, and review changes before updating baselines. A passing visual comparison is evidence about appearance for the configured capture environment; it does not replace functional coverage or guarantee behavior in every browser unless that browser is included in the configured run.
Or skip the browser setup
If you need a website screenshot outside a Cypress-driven test, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request takes a URL and returns an image or PDF. See the ScreenshotNeo API documentation for request options and configuration.
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)
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}`);ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
FAQ
Does an Eyes checkpoint replace a Cypress assertion?
No. Keep assertions for explicit behavior and use visual comparisons to detect changes in rendered appearance.
What happens on the first Eyes run?
The first run establishes the visual baselines. Later runs compare captures with those saved references.
Does every visual difference mean the test found a bug?
No. Review each difference. An intentional UI change can be accepted as a new baseline; an unintended regression should be rejected and investigated.
Can I use the 2021 setup commands unchanged?
Only if they match the package and Cypress versions in your project. Verify the current SDK API and configuration format before relying on that tutorial-era setup.
