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>