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:
- Applitools API key
- Eyes server URL - Required only if the Eyes server is not deployed on the Eyes public server.
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()
}
})
})