How to Run Cypress End-to-End Tests with Applitools

To run Cypress end-to-end tests with Applitools Eyes, install the Eyes Cypress SDK, configure your Applitools API key as a secret, add named visual checkpoints around the application states you want to protect, and run the spec with Cypress. Cypress still performs the interactions; Eyes captures those states, compares them with baselines, and provides results for review in Test Manager.

Applitools lists Cypress as an Eyes SDK option. The commands below follow Applitools vendor tutorial examples; package instructions and APIs can change, so confirm the current Cypress SDK quickstart before adopting them in a new project. Applitools Cypress integration · Applitools Cypress tutorial

1. Confirm the Cypress test works by itself

Start with a working Cypress end-to-end setup. Verify that the application starts, the test can visit it, and the existing functional assertions pass. This gives you a useful baseline for diagnosing setup problems after adding Eyes.

The examples use a Cypress spec and an application route at /account. Adapt the route and selectors to your app. They show the command pattern in the cited tutorial; they have not been run here, and exact syntax may differ by installed SDK version.

2. Install and configure the Eyes Cypress SDK

The Applitools tutorial documents this example installation and guided setup:

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

Older tutorials may show a different package spelling or setup flow. Check the current official SDK instructions for the package and version supported by your Cypress version before installing. Run the setup command from the project root and review any files it creates or updates.

Set the Applitools API key as an environment variable called APPLITOOLS_API_KEY. Keep the key out of the repository and provide it through your local secret mechanism or CI secret store. The cited cross-browser tutorial documents this variable; consult current Applitools documentation for the exact authentication setup supported by your SDK version.

# macOS or Linux shell, for the current terminal session
export APPLITOOLS_API_KEY="your_api_key"

# Then run Cypress as usual
npx cypress run

For CI, configure the variable in the CI provider’s secret settings rather than placing the key in a committed configuration file or command recorded in a shared log.

3. Add named visual checkpoints to the Cypress flow

Open an Eyes test, perform the user actions with regular Cypress commands, capture named states, and close the Eyes test. Checkpoint names should describe the state being protected, such as “Account overview” or “Account menu open.”

describe('Account', () => {
  it('shows the overview and open menu', () => {
    cy.eyesOpen({
      appName: 'Web App',
      testName: 'Account overview'
    });

    cy.visit('/account');
    cy.eyesCheckWindow('Account overview');

    cy.get('[data-testid="menu"]').click();
    cy.eyesCheckWindow('Account menu open');

    cy.eyesClose();
  });
});

This example follows the documented command shape. Confirm the lifecycle and checkpoint APIs against the SDK version you install, and follow its guidance for ensuring the Eyes test closes when a Cypress test fails. Keep ordinary Cypress assertions for behavior: an Eyes checkpoint adds visual comparison, but does not replace checks that buttons work, navigation succeeds, or data is correct.

Choose checkpoints at stable, meaningful points in the user journey. For example, wait for a page heading or a loading indicator to disappear before capturing a state. Avoid checkpoints during animations, while asynchronous content is still changing, or when the test contains unpredictable content that has not been stabilized.

4. Run one spec and review its result

Run the target Cypress spec first, using the spec path format supported by your Cypress version:

npx cypress run --spec "cypress/e2e/account.cy.js"

Applitools’ tutorial uses Cypress’s run command and a --spec argument. After the run, follow the Eyes result link or open Test Manager to inspect the checkpoint results. The documented workflow compares captured checkpoints against stored baselines and supports reviewing differences there.

Review each difference as a human decision. A changed image can indicate a regression, a legitimate product change, or a test state that was captured at the wrong time. Update a baseline only after deciding the visual change is expected and approved. Baseline and first-run behavior can depend on the current account and SDK configuration; the cited sources do not settle every current policy.

5. Add cross-browser visual coverage when needed

An Applitools tutorial describes Ultrafast Grid as a way to validate visual states across selected browser and viewport configurations. It describes supplying configuration through cy.eyesOpen() arguments, environment variables, or an applitools.config.js file. The tutorial is older, so verify current browser targets, account limits, and configuration syntax in current documentation before depending on a particular target.

Think of this as visual rendering and validation of captured test state. Cypress remains the driver for application interactions; adding Eyes does not mean Cypress itself executes every target browser in the grid. Start with the browser and viewport combinations that matter to your users, then expand coverage if the additional review and runtime fit your workflow.

Options and configuration choices

Choice	What it controls	Practical guidance
Checkpoint placement	Which rendered application states are compared	Capture after meaningful actions and after the page is stable.
Checkpoint name	How a state is identified in the result workflow	Use repeatable names that explain the state, rather than timestamps or random values.
App and test names	How runs are grouped and identified	Use stable project and test names so results are easy to locate.
Configuration location	Where grid or SDK settings are supplied	The cited tutorial describes test arguments, environment variables, and `applitools.config.js`; verify current option names.
Browser and viewport targets	Which visual renderings are compared	Confirm supported targets and plan limits in current Applitools docs.
Secret handling	How the API key reaches the test process	Use an environment variable locally and a secret store in CI; do not commit the key.

Keep configuration shared when many specs need the same targets, and use per-test settings only when a test has a clear reason to differ. The exact schema is version-specific and should be copied from the current SDK documentation rather than inferred from an older tutorial.

Performance, reliability, and cost considerations

Each visual checkpoint adds capture and comparison work to the test flow. Avoid taking redundant checkpoints of unchanged screens. A small set of checkpoints tied to user-visible states is usually easier to diagnose than a large number of snapshots with unclear purpose.

Reliability depends on capturing the intended state consistently. Wait for app-specific readiness, control variable data where possible, and avoid moving animations or transient notifications at checkpoint time. If a result differs, check both the UI change and the timing or test data before accepting a new baseline.

Applitools pricing and account limits are not established by the research used for this guide. Check current Applitools plan details for the expected checkpoint volume, grid targets, and team workflow before choosing a plan. No performance or accuracy benchmarks are claimed here.

Common errors and fixes

Symptom	Likely cause	What to check
`eyesOpen` or `eyesCheckWindow` is undefined	The SDK setup did not complete, its Cypress commands were not loaded, or the installed package/version differs from the tutorial.	Review the setup command output, Cypress support-file configuration, and current SDK setup guide. Confirm the spec runs with the intended project configuration.
Authentication or API-key error	`APPLITOOLS_API_KEY` is absent from the process environment, misspelled, or unavailable in CI.	Check the variable name in the current terminal or CI secret configuration. Avoid printing the key into logs.
The target spec is not found	The `--spec` path does not match the project’s Cypress spec location or naming pattern.	Check the configured Cypress spec pattern and use the path relative to the project root.
Checkpoint captures a loading or incomplete screen	The screenshot was taken before asynchronous content finished rendering.	Wait for a stable app-specific selector or completion condition before calling the checkpoint.
Unexpected visual differences recur	Dynamic content, animation, fonts, timing, viewport, or test data changes between runs.	Stabilize test inputs and readiness conditions, then inspect the diff. Update a baseline only for an approved intended change.
Local run works but CI cannot connect or authenticate	CI may lack the key or required environment/configuration, or its network policy may block the service.	Check secret injection, job environment, and network access under your organization’s CI rules. Consult current vendor docs for connection diagnostics.

Or skip the browser setup

If your goal is to capture a page image outside a Cypress visual regression workflow, ScreenshotNeo provides a one-request screenshot API. This does not replace Eyes checkpoints, baseline comparison, or Cypress user interactions; it is a direct option for producing a screenshot or PDF.

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

ScreenshotNeo API documentation · ScreenshotNeo

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

FAQ

Does adding Eyes replace Cypress assertions?

No. Cypress continues to exercise the application. Keep functional assertions for behavior and use Eyes checkpoints to compare rendered visual states.

Does a visual difference always mean the test failed?

A difference needs review. It may be an unintended regression or an intentional UI change; decide whether to approve a baseline update based on the expected product state.

Can I run only one Cypress spec?

Yes. Use Cypress’s --spec option with the path and pattern configured for your project.

Does the cited tutorial establish current cross-browser targets?

No. It describes the Ultrafast Grid configuration concept, but verify current targets, limits, and syntax in the current SDK documentation.