Cypress Tutorial

Run your first test!

Looking to just try it out? Get started by running your first test on GitHub!

  • Create a new repository sandbox from our template
  • Update your Applitools API key in GitHub Secrets
  • Run your first test with GitHub Actions

Create a New Repository Download the Example

Getting Started with Applitools Eyes & Cypress

Adding Applitools Eyes to a Cypress test

  1. Install Applitools Eyes for Cypress

In order to use Applitools Eyes, we need to first install the Eyes SDK for Cypress as an npm package.

npm i -D @applitools/eyes-cypress
  1. Configure the Applitools Eyes plugin and commands

Once installed, we can run a quick setup command that will configure the Applitools Eyes plugin as well as custom Cypress commands.

npx eyes-setup
  1. Add a new visual test with Applitools Eyes

To run a new check with Applitools Eyes, you can add the following to a test:

  appName: 'Hello World!',
  testName: 'My first JavaScript test!',

At it's simplest, this will tell Eyes that you want to start a test, capture the active window, and finally close the test.

You can also create multiple checks that make sense in a typical user flow. If you have a login page where you want to be sure your authentication is working exactly as expected, you may write a test like:

  appName: 'My App',
  testName: 'User Login',
cy.eyesCheckWindow('Login Page');

You can use the same Cypress commands you already do and integrate Applitools to provide broad visual coverage for your apps.

  1. Set your Applitools API key

Before running your test, you need to make your API key available to the environment. You can do this by either prepending your test command or exporting it in your terminal session.

To prepend, run you a command like npm test as:

APPLITOOLS_API_KEY="[Your Key]" npm test

To export your API key on a Mac, run:

export APPLITOOLS_API_KEY="[Your Key]"

To export your API key on Windows, run:


Learn how to find your API key

  1. Run your Cypress tests!

Now you're ready to run your tests!

You can use your existing test command or open up Cypress with:

npx cypress open

And that's it! Your tests should now be available to review in the Applitools dashboard.

Applitools Eyes SDK for Cypress

How it works

The Applitools Eyes Cypress SDK is a simple plugin to Cypress. Once installed, it adds few commands to the main cy object. Specifically, it adds three main methods, cy.eyesOpen to start the test, cy.eyesCheckWindow to take screenshots (for each test step) and cy.eyesClose to close the test.

Note: Supports Chrome, Firefox and Mobile simulators

The interesting thing is that even though you run your Cypress tests using Chrome browser, you can still add visual validations using both Chrome and Firefox! This is because we upload the DOM and assets to our Visual Grid that was rendered in Chrome and open it in Firefox or Chrome as per the settings. The same thing happens in mobile simulators as well.

The picture below shows how it works

  1. You run the Cypress test as usual

  2. Everytime you call cy.eyesCheckWindow, the SDK grabs the DOM and other assets asynchronously. And stores it locally until all the tests are done.

  3. Once all the Cypress tests are done, the SDK uploads all the assets to the Visual Grid server

  4. The Visual Grid server then opens up the assets in real browsers (Firefox or Chrome), or in mobile simulators, and with appropriate Viewport depending on what was set in the tests. Note that all these happen concurrently in the cloud.

  5. As and when the rendering happens, the Applitools Eyes server gets notification about it and the eyes server then compares the pictures using AI and advanced algorithms and shows the results.

Check out a working demo

See it in action with our example over on GitHub!

More information

The @applitools/eyes-cypress npm package page contain more information about advanced configuration, best practices and troubleshooting. Visit eyes-cypress SDK repo to find out more about what's possible with Applitools' Cypress SDK.

Getting Started with Applitools

Want to learn more about the Applitools platform and how it works? First get started with one of the following:

Last Updated: 9/2/2021, 12:57:58 AM