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.

Installing Eyes Cypress​

Run the following

npm i --save @applitools/eyes-cypress

or 

yarn add @applitools/eyes-cypress

Setting up the project​

On the project, run the following:

npx eyes-setup

Modifying the configuration file​

If npx eyes-setup did not run successfully, modify the configuration file as follows:

Cypress version 10 or later​

Add the following to the cypress.config.js file:

const { defineConfig } = require('cypress')
const eyesPlugin = require('@applitools/eyes-cypress')
module.exports = eyesPlugin(defineConfig({
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
    }
  }
}))

Cypress version earlier than version 10:​

In the pluginsFile file, add the following after the definition of module.exports:

require('@applitools/eyes-cypress')(module)

IntelliSense code completion​

You can add Eyes-Cypress IntelliSense to your tests using one of the following methods:

Triple slash directives​

The simplest way to see IntelliSense when typing an Eyes-Cypress command is to add a triple-slash directive to the head of your JavaScript or TypeScript testing file. This will turn the IntelliSense on a per file basis:

  /// <reference types="@applitools/eyes-cypress" />

Reference type declarations via tsconfig​

Eyes-Cypress ships with official type declarations for TypeScript. This allows you to add eyes commands to your TypeScript tests. If you do not have TypeScript, for example you use JavaScript, you can add IntelliSense declarations to the project using one of the following:

  • Add the path to your tsconfig file:

    {
    "compileroptions": {
      "types": ["@applitools/eyes-cypress", "cypress", "node"]
     }
    }

  • In the cypress/support folder, create a file index.d.ts that contains:

    import "@applitools/eyes-cypress"

    Normally, this is cypress/plugins/index.js. For details, see the Cypress documentation.

Configure custom commands manually​

Eyes-Cypress exposes new commands to your tests. This means that additional methods will be available on the cy object. If npx eyes-setup does not work, you need to configure these custom commands. As with the plugin, there is no automatic way to configure this in Cypress, so you need to manually add the following code to your supportFile:

import '@applitools/eyes-cypress/commands'

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​

Closes the Eyes test and check that all screenshots are valid.

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

cy.eyesClose(throwEx);
  • throwEx - (Boolean) throw an error if visual differences were found, or if the test failed for any other reason. The default is true.

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

getResults​

Returns TestResults for all tests that were run in an Eyes instance. If the test was run with the Ultrafast Grid, TestResults includes results for all environments. If you call getResults before eyes.close the method aborts the test.

cy.eyesGetResults().then(results => {...})
cy.eyesGetResults({throwErr: true}).then(results => {...})
cy.eyesGetResults({throwErr: false}).then(results => {...})

deleteTestResults​

This command deletes previous test results.

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

Logs​

Log files are automatically saved in the temp directory of the machine the tests ran on.

By default, the log directory is <os temp directory>/applitools-logs

You can locate it as follows:

  • Mac/Linux: $TMPDIR/applitools-logs/
  • Windows: %Temp%/applitools-logs/

When running the tests remotely, you can specify the path to the logs using the environment variable APPLITOOLS_LOG_DIR=<full path to log_dir>