Cypress Tutorial🔥

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

cypress-marketecture.png
  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.

Quick Start

In this Quick start you'll learn how to add the Cypress SDK to you existing Cypress project.

1. Add Eyes.Cypress plugin to your Cypress project by running the following:

npm install @applitools/eyes.cypress --save-dev

2. Configure Eyes plugin and commands by running the following:

npx eyes-setup

The above command will add the necessary imports to your cypress pluginsFile and supportFile. For more information about configuration, read the full documentation here.

3. Get the Applitools API key.

API-key

4. Set the APPLITOOLS_API_KEY environment variable on your computer to this API key value.

  • For Mac and Linux terminals:

    export APPLITOOLS_API_KEY=Your_API_Key_Here

  • For Windows command prompt:

    set APPLITOOLS_API_KEY=Your_API_Key_Here

  • For Windows PowerShell:

    Set-Variable -Name "APPLITOOLS_API_KEY" -Value "Your_API_Key_Here"

5. Add cy.eyesOpen to start the test inside your it method

//Start the test
cy.eyesOpen({
  appName: 'Hello World!',
  testName: 'My first JavaScript test!',
  browser: { width: 800, height: 600 },
});

⚡️⚡️ Note: Other common eyesOpen configurations ⚡️⚡️

  1. Setting multiple Browsers in one shot as an array
cy.eyesOpen({
  ...
  browser: [
    {width: 800, height: 600, name: 'firefox'},
    {width: 1024, height: 768, name: 'chrome'}
    //Add more variations
  ]
}
  1. Take screenshot using the mobile device emulation
cy.eyesOpen({
  ...
  browser: {
    deviceName: 'iPhone X',
    screenOrientation: 'landscape'
  }
}
  1. Using applitools.config.js file

It's possible to have a file called applitools.config.js at the same folder location as cypress.json. In this file specify the desired configuration, in a valid JSON format.

For example:

module.exports = {
  appName: 'My app',
  showLogs: true,
  batchName: 'My batch'
  ...
  // all other configuration variables apply
}
  1. Other configurations

See all other advanced configurations here.

6. Add one or more eyesCheckWindow checkpoints for various test steps

cy.eyesCheckWindow('Main Page');

⚡️⚡️ Note: Other common `eyesCheckWindow` configurations

You can use eyesCheckWindow in various ways. Below are the main ones.

  1. For the entire page
cy.eyesCheckWindow('Some window name');
  1. For a given CSS selector
cy.eyesCheckWindow({
  sizeMode: 'selector', //mode
  selector: '.my-element' //CSS Selector
});
  1. For a specific region
cy.eyesCheckWindow({
  sizeMode: 'region',
  region: {top: 100, left: 0, width: 1000, height: 200}
});
  1. To Ignore a region
cy.eyesCheckWindow({
  ignore: [
    {top: 100, left: 0, width: 1000, height: 100},
    {selector: '.some-div-to-ignore'}
  ]
});
  1. To create a floating region
cy.eyesCheckWindow({
  floating: [
    {top: 100, left: 0, width: 1000, height: 100, maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20},
    {selector: '.some-div-to-float', maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20}
  ]
});

7. End the test

Add the following near tne end of your test.

cy.eyesClose();

Note: All the eyesCheckWindow calls between eyesOpen and eyesClose are considered as test steps.

8. Putting it all together

Your code for each test should look something like below.

describe('Hello world', () => {
  it('works', () => {
    cy.visit('https://applitools.com/helloworld');

    //Start the test
    cy.eyesOpen({
      appName: 'Hello World!',
      testName: 'My first JavaScript test!',
      browser: { width: 800, height: 600 },
    });

    // Add checkpoint #1 (This is test step #1)
    cy.eyesCheckWindow('Main Page');

    cy.get('button').click();

    // Add checkpoint #2 (This is test step #2)
    cy.eyesCheckWindow('Click!');

    //End Test
    cy.eyesClose();
  });
});

9. Running your tests

Run your Cypress tests as usual.

Interactive

./node_modules/cypress/bin/cypress open

CLI

./node_modules/cypress/bin/cypress run --spec "path to your test spec"

A Note on SDK Performance

The SDK grabs assets in the b background asynchronously so each time you call eyesCheckWindow, it adds a bit of time. And at the end of all of your tests, it takes about a second per eyesCheckWindow call in order to upload all the assets to the Visual Grid.

Step-by-Step Guide (Run the demo app)

1. Create an Applitools account and obtain your API key from the Person Icon > "My API key" menu.

API-key

2. Please set the APPLITOOLS_API_KEY environment variable

  • For Mac and Linux terminals:

    export APPLITOOLS_API_KEY=Your_API_Key_Here

  • For Windows command prompt:

    set APPLITOOLS_API_KEY=Your_API_Key_Here

  • For Windows PowerShell:

    Set-Variable -Name "APPLITOOLS_API_KEY" -Value "Your_API_Key_Here"

3. Install node.js v10.x from https://nodejs.org​

4. Install git from https://git-scm.com​

TIP

Installing git is optional. You need this mainly to clone the demo project from the Github repository. Instead of installing git, you can simply download the Zip file from the repo. Further, If you are Mac, you already have git.

5. Clone the demo app and install dependencies

5.1 git clone https://github.com/applitools/tutorial-cypress.git

5.2 cd tutorial-cypress

5.3 npm install

6. Run the test

Interactive

./node_modules/cypress/bin/cypress open

Click on the actions.spec.js test. This will run 12 tests in about 15 seconds.

CLI

./node_modules/cypress/bin/cypress run --spec "cypress/integration/examples/actions.spec.js"

6. Analyze the result

You should see the results like below: cypress-test-result.png

Below is the video of the test running.

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.

Learn more

Applitools Eyes is a powerful platform for automated visual UI testing that supports full page screenshots, page layout matching, cross-device and browser testing, test batching, baseline branching and merging, automated baseline maintenance, collaboration features, and much more. Applitools has over 40 SDKs supporting a broad range of testing environments.

Reference documentation

To learn more, check out the Applitools Eyes documentation and tutorials for other testing environments.

Request a demo

If you want to see a demo of all our other features, you do request a demo

Knowledge base and Support

You can search our Knowldege base for more information. You can also file a contact our support team and file a Ticket.


Terms & Conditions Privacy Policy GDPR© 2018 Applitools. All rights reserved.

Last Updated: 11/18/2018, 8:38:32 PM