Cypress Integration

Introduction

This guide requires an existing Cypress project.
You can alternatively take a look to our example repository.

Sauce Visual provides an integration with Cypress through a plugin that you can add to any existing Cypress project.

Sauce Visual introduce a new Cypress command:

cy.sauceVisualCheck(): Takes a screenshot and send it to Sauce Visual for comparison.
cy.sauceVisualResults(): Waits for diff calculations to complete and returns a summary of results.

Important

Running Cypress tests on Sauce Labs requires SauceCTL to be installed and configured.

Follow me to learn more

Quickstart

Step 1: Add Sauce Visual for Cypress dependency

Install the Sauce Visual for Cypress plugin in your current project.

npm install --save-dev @saucelabs/cypress-visual-plugin

Step 2: Configure Cypress to use Sauce Visual for Cypress plugin

Import the plugin in Cypress project configuration, at the top of the file:

import { CypressSauceVisual } from '@saucelabs/cypress-visual-plugin';

export default defineConfig({
  e2e: {
    [...]
    setupNodeEvents(on, config) {
      ...
      CypressSauceVisual.register(on, config);
      ...
    },
  },
})

Cypress 12.17.4+
Cypress 12.17.3 and older

import '@saucelabs/cypress-visual-plugin/commands';

import '@saucelabs/cypress-visual-plugin/build/commands';

Step 3: Add visual tests in your project:

context('Sauce Demo', () => {
  it('should render correctly', () => {
    ...
    cy.sauceVisualCheck('visual: my-homepage');
    ...
  })
});

Step 4: Configure your Sauce Labs credentials

Sauce Visual relies on environment variables for authentications.
Both SAUCE_USERNAME and SAUCE_ACCESS_KEY need to be set prior starting your Cypress job.

Username and Access Key can be retrieved from https://app.saucelabs.com/user-settings.

export SAUCE_USERNAME=__YOUR_SAUCE_USER_NAME__
export SAUCE_ACCESS_KEY=__YOUR_SAUCE_ACCESS_KEY__

Step 5: Run the test

Upon executing your tests for the first time under this step, a visual baseline is automatically created in our system. This baseline serves as the standard for all subsequent Cypress tests. As new tests are run, they are compared to this original baseline, with any deviations highlighted to signal visual changes. These comparisons are integral for detecting any unintended visual modifications early in your development cycle. All test builds, including the initial baseline and subsequent runs, can be monitored and managed through the Sauce Labs platform at Sauce Visual Builds.

Remember, the baseline is established during the initial run, and any subsequent visual differences detected will be marked for review.

Advanced usage

Test results summary

cy.sauceVisualResults() returns a summary of test results in format:

{
    QUEUED: number; // Diffs that are pending for processing. Should be 0 in case the test is completed without any timeouts
    EQUAL: number; // Diffs that have no changes detected
    UNAPPROVED: number; // Diffs that have detected changes and waiting for action
    APPROVED: number; // Diffs that have detected changes and have been approved
    REJECTED: number; // Diffs that have detected changes and have been rejected
}

Sample output:

{ APPROVED: 0, EQUAL: 0, UNAPPROVED: 2, REJECTED: 0, QUEUED: 0 }

Sample usage:

const EXPECTED_TOTAL_UNAPPROVED_DIFFS = 0;

cy.sauceVisualResults().its("UNAPPROVED").should("eq", EXPECTED_TOTAL_UNAPPROVED_DIFFS);

Build name

Sauce Visual for Cypress plugin extends Cypress configuration, allowing to define the context, thus acting on which baselines new snapshots will be compared to. (More info on baseline matching)

Options:

region: Sauce Labs Region where the new build will be created (default: us-west-1)
buildName: Name of the build (default: Cypress Visual Testing)
project: Name of the project (default: None)
branch: Name of branch (default: None)
defaultBranch: Name of the main or default branch (default: None)

They need to be set through the saucelabs attribute of e2e configuration.

Example:

export default defineConfig({
  e2e: {
    [...]
    saucelabs: {
      region: 'eu-central-1',
      buildName: 'SauceDemo - Cypress',
      project: 'Cypress examples',
      branch: 'main',
    },
    [...]
  }
}

Environment variables

Below are the environment variables available for the Sauce Visual for Cypress plugin. Keep in mind that the variables defined in Cypress configuration have precedence over these variables.

Variable Name		Description
`SAUCE_USERNAME`	required	Your Sauce Labs username. You can get this from the header of app.saucelabs.com
`SAUCE_ACCESS_KEY`	required	Your Sauce Labs access key. You can get this from the header of app.saucelabs.com
`SAUCE_REGION`		The region you'd like to run your Visual tests in. Defaults to `us-west-1` if not supplied. Can be one of the following: `'eu-central-1'`, `'us-west-1'` or `'us-east-4'`
`SAUCE_VISUAL_BUILD_NAME`		The name you would like to appear in the Sauce Visual dashboard.
`SAUCE_VISUAL_BRANCH`		The branch name you would like to associate this build with. We recommend using your current VCS branch in CI.
`SAUCE_VISUAL_DEFAULT_BRANCH`		The main branch name you would like to associate this build with. Usually `main` or `master` or alternatively the branch name your current branch was derived from. Follow me to learn more
`SAUCE_VISUAL_PROJECT`		The label / project you would like to associate this build with.
`SAUCE_VISUAL_BUILD_ID`		For advanced users, a user-supplied SauceLabs Visual build ID. Can be used to create builds in advance using the GraphQL API. This can be used to parallelize tests with multiple browsers, shard, or more. By default, this is not set and we create / finish a build during setup / teardown.
`SAUCE_VISUAL_CUSTOM_ID`		For advanced users, a user-supplied custom ID to identify this build. Can be used in CI to identify / check / re-check the status of a single build. Usage suggestions: CI pipeline ID.

Working with custom ID

Linking all your Sauce Visual tests to one build ID can streamline your workflow, especially in CI setups. This enables easy management using the Sauce Visual CLI, like creating builds with custom IDs, adding snapshots, and completing builds. This way, you can efficiently handle multiple tests grouped under the same build in Sauce Visual.

When you use SAUCE_VISUAL_CUSTOM_ID, Sauce Visual checks if there's an existing build with that ID. If found, your tests are linked to it; otherwise, Sauce Visual creates a new build. In contrast, using SAUCE_VISUAL_BUILD_ID requires an existing build with the provided ID; otherwise, an error occurs.

Ignored regions

Component-based ignored region

Sauce Visual provides a way to ignore a list of components.

An ignored component can be a specific element from the page.

Those ignored components are specified when requesting a new snapshot.

Example:

cy.sauceVisualCheck('login-page', {
  ignoredRegions: [
    cy.get('[data-test="username"]'),
  ]
});

User-specified ignored region

Alternatively, ignored regions can be user-specified areas. A region is defined by four elements.

x, y: The location of the top-left corner of the ignored region
width: The width of the region to ignore
height: The height of the region to ignore

Note: all values are pixels

Example:

cy.sauceVisualCheck('login-page', {
  ignoredRegions: [
    {
      x: 240,
      y: 800,
      width: 1520,
      height: 408
    }
  ],
});

Selective Diffing

Sauce Visual allows selective diffing that permits to ignore changes from a certain kind (more information here).

warning

Selective diffing is only available with Balanced diffing method AND with DOM capture enabled.

Screenshot-wide configuration

Sauce Visual Binding allows to configure which kinds of changes should be effective on snapshot.

Example:

    cy.sauceVisualCheck('login-page', {
      diffingMethod: DiffingMethod.Balanced,
      captureDom: true,
      // Content changes won't be reported as a difference
      diffingOptions: {
        content: false,
        dimensions: true,
        position: true,
        structure: true,
        style: true,
        visual: true,
      },
    });

Area-specific configuration

Sauce Visual Binding allows to configure which kinds of changes should be effective specific regions of the snapshot.

Example:

    cy.sauceVisualCheck('login-page', {
      diffingMethod: DiffingMethod.Balanced,
      captureDom: true,
      regions: [
        // Any change will be ignored.
        { element: cy.get('[data-test="username"]'), enableOnly: [] },
        // Only style changes won't be ignored.
        { element: cy.get('[data-test="password"]'), enableOnly: ['style'] },
      ],
    })

Specifying options for Cypress Screenshot

Sauce Visual relies on the native screenshot feature from Cypress. Options in cy.snapshot can be specified in the cy.visualCheck command.

The field cypress from options will be transmitted as it to cy.screenshot command. (See Cypress documentation)

Example:

cy.sauceVisualCheck('login-page', {
  cypress: {
    capture: 'viewport',
  }
});

Capturing the DOM snapshot

Sauce Visual does not capture dom snapshot by default. It can be changed in sauceVisualCheck options.

Example:

cy.sauceVisualCheck('login-page', {
    captureDom: true
});

Full page screenshots

Cypress natively offers full page screenshots -- you can pass options into our sauceVisualCheck function in order to enable it for your visual checks.

Example:

cy.sauceVisualCheck('Inventory Page', {
    cypress: {
        // One or more options to be passed directly to the cy.screenshot() function call.
        capture: 'fullPage',
    },
});

Clip to an Element

You can clip to a specific element on the page by using the clipSelector option.

Example:

cy.sauceVisualCheck('Inventory Page', {
    clipSelector: '.your-css-selector',
});

Limitations

Sauce Visual for Cypress DOES NOT support cypress open.

Screenshots will be captured and sent to Sauce Labs only when cypress run is executed.

Example

An example project is available here.

Introduction​

Quickstart​

Step 1: Add Sauce Visual for Cypress dependency​

Step 2: Configure Cypress to use Sauce Visual for Cypress plugin​

Step 3: Add visual tests in your project:​

Step 4: Configure your Sauce Labs credentials​

Step 5: Run the test​

Advanced usage​

Test results summary​

Build name​

Environment variables​

Working with custom ID​

Ignored regions​

Component-based ignored region​

User-specified ignored region​

Selective Diffing​

Screenshot-wide configuration​

Area-specific configuration​

Specifying options for Cypress Screenshot​

Capturing the DOM snapshot​

Full page screenshots​

Clip to an Element​

Limitations​

Example​

Introduction

Quickstart

Step 1: Add Sauce Visual for Cypress dependency

Step 2: Configure Cypress to use Sauce Visual for Cypress plugin

Step 3: Add visual tests in your project:

Step 4: Configure your Sauce Labs credentials

Step 5: Run the test

Advanced usage

Test results summary

Build name

Environment variables

Working with custom ID

Ignored regions

Component-based ignored region

User-specified ignored region

Selective Diffing

Screenshot-wide configuration

Area-specific configuration

Specifying options for Cypress Screenshot

Capturing the DOM snapshot

Full page screenshots

Clip to an Element

Limitations

Example