Cypress Tutorial

This tutorial will show you how to automate visual tests using the Applitools Ultrafast Grid with Cypress in JavaScript. Applitools Ultrafast Test Cloud can help you catch functional and visual problems that traditional automation struggles to find. It can also help you to scale your tests to cover all browsers and devices in seconds. The Applitools Eyes SDK for Cypress does not support the Classic runner – it supports only the Ultrafast Grid.

In this tutorial, you will:

  1. Set up your local machine for testing.
  2. Clone the example project repository.
  3. Learn how to automate visual testing with Applitools Eyes.
  4. Run the visual tests and review results in the Applitools dashboard.

After setting up your machine, this tutorial should take about 15 minutes to complete. If you get stuck along the way, please reach out to us for help!

Quickstart

If you prefer a quickstart instead of a full tutorial, clone the example repository and follow the README instructions!

Recognizing project structure

The example project uses:

Setting up your machine

You'll need a few things to run this tutorial:

  1. An Applitools account, which you can register for free.

  2. Node.js version 16 or higher.

  3. A good JavaScript editor like Visual Studio Code.

  4. Up-to-date versions of the following browsers:

Downloading the example project

The example project is located at https://github.com/applitools/example-cypress-javascript-ufg. Clone this repository to your local machine:

$ git clone https://github.com/applitools/example-cypress-javascript-ufg.git
$ cd example-cypress-javascript-ufg
1
2

Note: If you don't have Git installed, then instead of running git clone, you can download the project as a ZIP file and extract it.

Understanding the dependencies

The example project uses npm for package management. It contains the following dependencies for the Applitools Eyes SDK for Cypress as well as Cypress itself:

  "dependencies": {
    "@applitools/eyes-cypress": "^3.26.1",
    "cypress": "^9.7.0"
  }
1
2
3
4

Adding Applitools to Another Cypress Project?

This example project already has the Applitools Eyes SDK as a dependency. If you want to add the Applitools Eyes SDK as a new dependency to another Cypress project, run the following commands:

$ npm install @applitools/eyes-cypress
$ npx eyes-setup
1
2

Understanding the code

The project contains one visual test case, which is located at cypress/integration/acme-bank.spec.js.

acme-bank.spec.js is a Cypress test module that covers login behavior for the ACME Bank demo web app. It uses the Applitools Eyes SDK for Cypress to capture visual checkpoints. The code is rather concise. In-line comments explain every section. Read it top to bottom to understand how it works:

/// <reference types="cypress" />

// This test case spec contains everything needed to run a full visual test against the ACME bank site.
// The file `applitools.config.js` specifies how to run this test against multiple browsers in Applitools Ultrafast Grid.

// This "describe" method contains related test cases with per-test setup and cleanup.
// In this example, there is only one test.
describe('ACME Bank', () => {

    // This method performs setup before each test.
    beforeEach(() => {

        // Open Eyes to start visual testing.
        // Each test should open its own Eyes for its own snapshots.
        cy.eyesOpen({
            appName: 'ACME Bank',                       // The name of the app under test
            testName: Cypress.currentTest.title,        // The name of the test case
        })
    })

    // This test covers login for the Applitools demo site, which is a dummy banking app.
    // The interactions use typical Cypress calls,
    // but the verifications use one-line snapshot calls with Applitools Eyes.
    // If the page ever changes, then Applitools will detect the changes and highlight them in the dashboard.
    // Traditional assertions that scrape the page for text values are not needed here.
    it('should log into a bank account', () => {

        // Load the login page.
        cy.visit('https://demo.applitools.com')

        // Verify the full login page loaded correctly.
        cy.eyesCheckWindow({
            tag: "Login page",
            target: 'window',
            fully: true
        });

        // Perform login.
        cy.get('#username').type('andy')
        cy.get('#password').type('i<3pandas')
        cy.get('#log-in').click()

        // Verify the full main page loaded correctly.
        // This snapshot uses LAYOUT match level to avoid differences in closing time text.
        cy.eyesCheckWindow({
            tag: "Main page",
            target: 'window',
            fully: true,
            matchLevel: 'Layout'
        });
    })

    // This method performs cleanup after each test.
    afterEach(() => {
        
        // Close Eyes to tell the server it should display the results.
        cy.eyesClose()
    })
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

The applitools.config.js file in the project root directory provides the configuration to run this visual test across multiple browsers in the Ultrafast Grid. Its configuration applies to all test cases in the project:

// This config file specifies how to run visual tests with Applitools.
// It applies to all tests in this project.

module.exports = {

    // Concurrency refers to the number of visual checkpoints Applitools will perform in parallel.
    // Warning: If you have a free account, then concurrency will be limited to 1.
    testConcurrency: 5,

    // To connect visual test results to your account,
    // you must set the `APPLITOOLS_API_KEY` environment variable to your Applitools API key.
    // To find it: https://applitools.com/tutorials/getting-started/setting-up-your-environment.html
    // If you don't explicitly set the API key here,
    // then the SDK will automatically read the `APPLITOOLS_API_KEY` environment variable to fetch it.
    apiKey: 'APPLITOOLS_API_KEY',
    
    // A batch is the collection of visual checkpoints for a test suite.
    // Batches are displayed in the dashboard, so use meaningful names.
    batchName: 'Applitools Example: Cypress JavaScript with the Ultrafast Grid',

    // Applitools can run checkpoints for snapshots against any browser in the Ultrafast Grid.
    // This setting defines 5 unique browser configurations to test.
    browser: [

        // Add 3 desktop browsers with different viewports for cross-browser testing in the Ultrafast Grid.
        // Other browsers are also available, like Edge and IE.
        {width: 800, height: 600, name: 'chrome'},
        {width: 1600, height: 1200, name: 'firefox'},
        {width: 1024, height: 768, name: 'safari'},

        // Add 2 mobile emulation devices with different orientations for cross-browser testing in the Ultrafast Grid.
        // Other mobile devices are available, including iOS.
        {deviceName: 'Pixel 2', screenOrientation: 'portrait'},
        {deviceName: 'Nexus 10', screenOrientation: 'landscape'},
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

Preparing for test execution

Before running the visual test, you must find your Applitools API key and set it as an environment variable named APPLITOOLS_API_KEY.

On macOS and Linux:

$ export APPLITOOLS_API_KEY=<your-api-key>
1

On Windows:

> set APPLITOOLS_API_KEY=<your-api-key>
1

Environment Variable Trouble

If you have trouble setting the APPLITOOLS_API_KEY environment variable, you can hard-code your API key into applitools.config.js like this:

// apiKey: 'APPLITOOLS_API_KEY',
apiKey: '<your-api-key>',
1
2

However, be warned: hard-coding secrets is poor practice. Do this only temporarily for debugging, and never commit hard-coded secrets to version control.

Applitools Eyes Server

By default, tests will use the public Applitools Eyes server at eyes.applitools.com. However, if your team is using a private Applitools Eyes server, you can target it by setting the APPLITOOLS_SERVER_URL environment variable.

Next, you must install project dependencies and set up Applitools Eyes. Run the following commands (which work for any OS):

$ npm install
$ npx eyes-setup
1
2

Running the visual test

To open the Cypress window for launching tests, run:

$ npx cypress open
1

If you want to run tests directly from the command line, run this instead:

$ npx cypress run
1

Once your tests run, you should see results in the Applitools dashboard. For your batch, there should be 5 tests (one for each browser configuration), each with 2 visual snapshots.

You can also change the web page to inject visual bugs:

// cy.visit('https://demo.applitools.com')
cy.visit('https://demo.applitools.com/index_v2.html')
1
2

If you rerun the tests, then they should yield "unresolved" results for you to review. Visual differences will be highlighted in magenta. It's up to you to accept (πŸ‘) or reject (πŸ‘Ž) the changes. Applitools will remember your decisions for future analysis.

Having Trouble?

Don't suffer in silence! Let us help you. Please reach out to us to get your project working.

Taking the next steps

Congratulations on completing this tutorial! There's still so much to learn about visual testing with Applitools, but you're off to a great start.

Here are resources for your next steps:

  1. πŸ€– How Applitools Works
  2. πŸ–Ό Analyzing Differences
  3. 🐞 Reporting Bugs
  4. πŸ’₯ Troubleshooting Common Issues
  5. πŸ—Ί Detailed overview of visual testing with Applitools
  6. πŸ‘€ Docs for the Applitools Eyes SDK for Cypress

You can also:

Last Updated: 6/15/2022, 4:46:30 PM