Skip to main content

Cypress overview

Applitools Eyes SDK for Cypress​

The Cypress SDK allows you to leverage the Applitools Ultrafast Grid to automatically run tests across all major browsers.

For information about installing and configuring this SDK, see Testing web apps in JavaScript using Cypress on the Applitools Tutorial site.

For general information about working with Cypress, see Cypress Testing Framework on the Applitools website.

Getting started​

To use this SDK, you need to set the following:

Entering the Applitools API key​

To authenticate via the Applitools server and run tests, you need to set the environment variable APPLITOOLS_API_KEY to the API key provided from Applitools Eyes. For details how to retrieve your API key, see the Applitools documentation.

Entering the API Key on Linux or a Mac​

export APPLITOOLS_API_KEY=<API_key>
npx cypress open

Entering the API Key on Windows​

set APPLITOOLS_API_KEY=<API_key>
npx cypress open

Eyes server URL​

If the Eyes server is not deployed in https://eyes.applitools.com, you need to set the Server URL in the environment variable APPLITOOLS_SERVER_URL before running tests.

The server URL of your Applitools Eyes dashboard is in the format https://<MY_COMPANY>.applitools.com

Entering the server URL on Linux or a Mac​

export APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>

Entering the server URL on Windows​

set APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>

Using the SDK​

After you have configured the server URL and API key, you can take screenshots and make them available in Test Eyes using Eyes-Cypress commands.

Example​

describe('Hello world', () => {
  it('works', () => {
    cy.visit('https://applitools.com/helloworld');
    cy.eyesOpen({
      appName: 'Hello World!',
      testName: 'My first JavaScript test!',
      browser: { width: 800, height: 600 },
    });
    cy.eyesCheckWindow('Main Page');
    cy.get('button').click();
    cy.eyesCheckWindow('Click!');
    cy.eyesClose();
  });
});

Best practice for using the SDK​

A test in Applitools Eyes always starts with a cy.eyesOpen call and ends with cy.eyesClose. The steps in the test are calls to cy.eyesCheckWindow between cy.eyesOpen and cy.eyesClose calls.

A test is structured as following:

cy.eyesOpen
  [step 1]
  [step 2]
  ...
cy.eyesClose

To create a test structure in Eyes that corresponds to the test structure in Cypress, open and close each test in every it call. You can do this with the beforeEach and afterEach Cypress functions.

Example​

describe('Hello world', () => {
  beforeEach(() => {
    cy.eyesOpen({
      appName: 'Hello World!',
      browser: { width: 800, height: 600 },
    });
  });

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

  it('My first JavaScript test!', () => {
    cy.visit('https://applitools.com/helloworld');
    cy.eyesCheckWindow('Main Page');
    cy.get('button').click();
    cy.eyesCheckWindow('Click!');
  });
});

Eyes will take screenshots and perform the visual comparisons in the background. Performance of the tests will not be affected during the test run, but there will be a small phase at the end of the test run that waits for the Applitools Eyes tests to end.

📝 Note: In Cypress interactive mode (cypress open) there is a bug that exceptions in root level after statements do not appear in the interface. They still appear in the browser's console, and are considered failures in cypress run. See this issue for more information and tracking.

Common commands​

In addition to the built-in commands provided by Cypress, such as cy.visit and cy.get, Eyes-Cypress defines new custom commands, which enable the visual testing with Applitools Eyes. Common commands are:

Open​

This command creates an Eyes test. This will start a session with the Applitools server.

cy.eyesOpen({
  appName: '',
  testName: ''
});

You can pass a config object to eyesOpen with any configuration properties.

CheckWindow​

This command generates a screenshot of the current page and adds it to the Eyes Test.

cy.eyesCheckWindow('Login screen')

or

cy.eyesCheckWindow({ tag: 'Login screen', target: 'your target' })

For details of cy.eyesCheckWindow() arguments, see eyesCheckWindows arguments.

Close​

This command closes the Eyes test and checks that all screenshots are valid.

It is important to call this command at the end of each test, symmetrically to eyesOpen (or in afterEach(), see Best practice for using the SDK.

Close receives no arguments.

cy.eyesClose();

GetAllTestResults​

This command returns an object with the Eyes test results from a given test or test file. This command should be called after close.

Example​

after(() => {
  cy.eyesGetAllTestResults().then(summary => {
    console.log(summary)
  })
})

deleteTestResults​

This command deletes previous test results.

after(() => {
  cy.eyesGetAllTestResults().then(summary => {
    for(const result of summary.getAllResults()) {
      await result.getTestResults().delete()
    }
  })
})

Additional information​