Applitools Eyes Cypress Setup for Visual Testing

To add Applitools Eyes to an existing Cypress project, install the Eyes Cypress SDK, run its setup command, provide an Applitools API key, then add named visual checkpoints to your Cypress specs. Cypress continues to drive the browser and user interactions; Eyes captures and compares the visual states. The first run establishes a baseline, and later runs report differences for review.

1. Install and configure the Eyes Cypress SDK

Start in the root of a project where Cypress is already installed. Applitools’ setup examples use these commands:

npm install @applitools/eyes-cypress --save-dev
npx eyes-setup

The setup command configures the SDK for Cypress, including its plugin and commands; it can also add TypeScript definitions. Review the changes it makes in your project before committing them. The cited setup material does not establish a current Cypress or Node.js compatibility matrix or SDK version, so check the current package documentation if your project has strict runtime constraints.

Set the API key outside source control

Set APPLITOOLS_API_KEY in the environment where Cypress will run. For a local shell, for example:

export APPLITOOLS_API_KEY="YOUR_APPLITOOLS_API_KEY"
npx cypress run

Use your CI provider’s secret store to supply the same environment variable in continuous integration. Do not commit a real API key in a spec, configuration file, or checked-in environment file. Applitools examples also show an applitools.config.js configuration approach; if using a config file, keep any real key in an environment variable rather than embedding it.

2. Add visual checkpoints to a Cypress spec

Keep the existing Cypress commands that navigate and interact with the app. Add Eyes calls around the states whose appearance matters. This example assumes the application is available at http://localhost:3000 and has a page at /:

describe('Home page visual checks', () => {
  beforeEach(() => {
    cy.eyesOpen({
      appName: 'Example App',
      testName: 'Home page'
    });
  });

  afterEach(() => {
    cy.eyesClose();
  });

  it('checks the initial page and a completed interaction', () => {
    cy.visit('http://localhost:3000/');
    cy.eyesCheckWindow('Home page loaded');

    cy.get('[data-cy="name"]').type('Avery Example');
    cy.get('[data-cy="submit"]').click();
    cy.get('[data-cy="success-message"]').should('be.visible');
    cy.eyesCheckWindow('Form submitted');
  });
});

Use selectors that match your application. The example’s data-cy attributes are illustrative; Cypress must be able to find the corresponding elements. The key Eyes calls are cy.eyesOpen to begin a test, cy.eyesCheckWindow to capture a named checkpoint, and cy.eyesClose to finish it.

Run the spec

With the API key set and the app running, use your project’s normal Cypress command. For example:

npx cypress run

Alternatively, run Cypress in its interactive mode using the command already configured by your project. Check the Eyes results after the first run to establish the visual baseline. On later runs, review the reported differences and decide whether they represent an intended change or a regression.

3. Choose checkpoints that represent meaningful states

A visual test should capture the page after it reaches the state you intend to protect. Common checkpoint points include:

After initial navigation and the page’s important content is visible.
After a user action, such as submitting a form or opening a menu.
After a loading or empty state resolves, if that resolved state is part of the intended experience.
At responsive viewport sizes or browsers that are part of your supported coverage.

Give checkpoints stable, descriptive names. Separate materially different states into separate checkpoints; that makes it easier to identify which part of a journey changed. Avoid capturing while content is still loading or before an interaction has completed, since timing differences can create noisy comparisons.

4. Handle baselines and dynamic content

The first run has no prior visual baseline to compare with. Later runs can compare the captured state against the saved baseline. A difference is a signal to inspect, not automatically proof of a defect: it may represent an intentional design change, a rendering difference, or unpredictable page content.

Dynamic content such as a gallery of changing popular images can create differences even when the layout is correct. Applitools’ examples describe using a layout region or a Layout match level when the variable content itself should not trigger a mismatch but the page structure still matters. Apply those choices narrowly and deliberately:

Use a layout-oriented comparison when changes within a region’s content are expected but its structure and placement matter.
Keep meaningful content under stricter visual comparison when its appearance is part of the requirement.
Review every ignored or relaxed area. Making it too broad can hide a real visual regression.
Where possible, make test data deterministic so repeated runs represent the same intended state.

Review and approve baseline changes through your team’s normal process. An intentional redesign should update the expected baseline; an unexplained difference should be investigated before it is accepted.

5. Decide whether to add cross-browser coverage

Cross-browser visual testing is an optional configuration choice. Select browsers and viewport sizes based on the browsers your application supports, the layouts that matter, and your team’s capacity to review differences. A practical starting plan is to cover the primary browser and viewport first, then add combinations tied to actual support requirements or known layout risks.

Applitools’ Cypress material describes configuring browser options and viewport sizes, but the reviewed sources do not establish a current compatibility matrix or a universal list of configuration values. Check the current Cypress and Eyes documentation for supported browser choices and exact configuration syntax before adding them to a project.

When expanding coverage, keep the comparison interpretable: capture the same named application state, use consistent test data, and review differences in the context of the selected browser and viewport. More combinations create more results to triage, so add coverage where it answers a real compatibility question.

6. Troubleshooting

Symptom	Likely cause	What to do
Eyes reports that the API key is missing or invalid	`APPLITOOLS_API_KEY` is not set in the process running Cypress, or the supplied value is wrong.	Set the variable in the local shell or CI job that launches Cypress. Confirm the secret is available to that process without printing it into logs.
`cy.eyesOpen`, `cy.eyesCheckWindow`, or `cy.eyesClose` is unknown	The SDK setup may not have completed, or the spec is running before the Eyes Cypress integration is loaded.	Run `npx eyes-setup` from the project root, inspect the generated integration changes, and follow the current SDK instructions for your project’s Cypress configuration.
The first run shows a difference or has no baseline	No earlier run has established the expected visual state.	Inspect the initial result. If it is the intended appearance, establish or approve that baseline using the workflow provided by your Eyes account and team.
Repeated runs report differences in images, timestamps, or changing content	The page includes nondeterministic data or is captured at different points in its loading sequence.	Stabilize test data and wait for the intended state before capturing. If the content should vary while layout should remain stable, consider a narrowly scoped layout-oriented comparison.
Visual differences appear only in one browser or viewport	The application may render differently at that size or in that browser, or the runs may not be capturing equivalent states.	Compare the same state and viewport settings, then inspect the browser-specific result. Keep only combinations relevant to the application’s support needs.
The app cannot be reached during the test	The local development server may not be running or the URL in the spec may not match its address.	Start the application using the project’s normal command and update `cy.visit` to the address and route it serves.
TypeScript does not recognize Eyes commands	The project may not have imported the SDK’s Cypress command or type definitions as expected.	Review what `npx eyes-setup` added and follow the current SDK guidance for TypeScript setup.

7. Performance, reliability, and cost considerations

Visual checks add capture and comparison work to a test run. The reviewed sources provide no independent performance benchmark or named timing figure, so measure the effect in your own suite. Start with checkpoints at important states, avoid redundant captures, and add browser and viewport combinations when they cover a requirement. Keep the test journey and test data stable so failures are useful to investigate.

Reliability depends on reaching the same intended page state on each run. Ensure the app is available, wait for meaningful content or interactions to finish, and control variable data where practical. Treat baseline updates as reviewed changes, particularly when relaxing comparison for dynamic regions.

Applitools pricing and plan details are not established by the sources used for this guide. Check the current Applitools offering for costs and limits before planning suite size or team usage. For a separate way to capture website screenshots without configuring a browser runner, see the option below.

Or skip the browser setup

If your immediate need is a website screenshot rather than a Cypress visual regression test, ScreenshotNeo provides a screenshot API and MCP server. Its API returns a PNG, JPEG, WebP, or PDF from one GET request. Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response includes page-verdict and billing headers. AI agents can use its MCP tools, including take_screenshot, get_page_info, and capture_pdf.

See the ScreenshotNeo API documentation for setup and options. Example calls:

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import 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)

Node.js

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 is a website screenshot API and MCP server by Yorker Media. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is available on every plan. Sign up for 1,000 free screenshots a month with no card.

FAQ

Does Eyes replace Cypress?

No. Cypress still runs the browser journey and interactions. Eyes adds visual checkpoints and comparisons to that journey.

Should every Cypress test include a visual checkpoint?

No. Add checkpoints where appearance is part of the behavior you need to protect, such as a key page state or completed interaction.

Does the Applitools MCP server provide Cypress setup?

The reviewed MCP documentation describes setup and checkpoint tools for Playwright Fixtures, while its inspection tools can work with results from any Eyes SDK. That is separate from setting up the Cypress SDK.

Can ScreenshotNeo replace Eyes visual regression testing?

ScreenshotNeo captures website screenshots through an API or MCP server. The facts in this guide do not describe it as a visual baseline comparison system, so use Eyes when you need the Cypress checkpoint and comparison workflow described above.