Skip to main content

Visual E2E Testing Reference

Visual E2E Commands

Visual E2E commands can be integrated into existing WebDriver test code simply and safely. Each command is simply a JavaScript comment placed in a WebDriver execute command no need to install anything.

Init command

The Init command (/*@visual.init*/) is used to initialize and name a Visual test. This command must be added before any snapshot commands. It can be used multiple times in a browser session to initialize multiple visual tests.


nameStringYesName of Visual test
optionsObjectNoInit command options.

Options available:

  • ignore: comma-delimited list of css-selectors to ignore in all snapshots in test.
{ ignore: '.selector' }

Code Snippets

browser.execute('/*@visual.init*/', 'My Visual Test');
browser.execute('/*@visual.init*/', 'My Visual Test', {ignore: '.selector'});

Snapshot command

The Snapshot command (/*@visual.snapshot*/) is used to capture a visual snapshot. This JS comment can be added into your code wherever you want a snapshot to be taken, and can be used multiple times.

The above Init command must be called first before any snapshots are taken, or an error will occur.


nameStringYesName of Snapshot
optionsObjectNoSnapshot command options.

Options available:

  • ignore: comma-delimited list of css-selectors to ignore in snapshot.
  • cropTo: single css-selector to crop the snapshot to.
  • scrollAndStitchScreenshot: boolean option to capture a full-page screenshot using a scrolling and stitching strategy instead of using native browser full-page screenshot capabilities.

Code Snippets

browser.execute('/*@visual.snapshot*/', 'State Name');

Example with ignore option:

browser.execute('/*@visual.snapshot*/', 'State Name', {ignore: '.selector'});

Example with cropTo option:

browser.execute('/*@visual.snapshot*/', 'State Name', {ignore: '.selector', cropTo: '#header'});

Example with scrollAndStitchScreenshot option:

browser.execute('/*@visual.snapshot*/', 'State Name', {ignore: '.selector', cropTo: '#header', scrollAndStitchScreenshot: true});

End command

The End command (/*@visual.end*/) is used to wait and get visual results. This command should be the last visual command in your browser session, used after all your visual snapshots.

The response will contain the following properties:

passedWhether or not the test passed.
statusThe test status. Possible values: success, failure, error, timeout, cancelled.
totalsVisual regression result totals.
statesList of all snapshots, including name, status and URL. NOTE: URLs are not permalinks; URL will direct to the latest results for the snapshot.
messageError message.

Code Snippets

const result = browser.execute('/*@visual.end*/');
assert.ok(result.passed, result.message);

Example Responses

passed: true,
status: 'success',
totals: {new: 0, changed: 0, accepted: 2, rejected: 0, all: 2},
states: [
{name: 'State 1', groupName: 'Test 1', status: 'accepted', url: '...'}
{name: 'State 2', groupName: 'Test 1', status: 'accepted', url: '...'}
message: null

sauce:visual Capability Options

Below are the available options that you can define with the sauce:visual capability.

projectNameStringYesProject name.
apiKeyStringYesAPI Key for user's Screener account.
viewportSizeStringNoA <width>x<height> representation of desired viewport size.

Example: 1024x768.

branchStringNoBranch or environment name.

Example: main.

baseBranchStringNoBranch name of project's base branch. Used for baseline branching and merging.

Example: main.

diffOptionsObjectNoVisual diff options to control validations.

Options available:

  • structure: enable or disable structural changes. Defaults to true.
  • layout: enable or disable layout changes. Defaults to true.
  • style: enable or disable style changes. Defaults to true.
  • content: enable or disable content changes. Defaults to true.
  • minLayoutPosition: Optional threshold for Layout position changes (in css pixels).
  • minLayoutDimension: Optional threshold for Layout dimension changes (in css pixels).
  • minShiftGraphic: Optional threshold for pixel shifts in graphics (in css pixels).
structure: true,
layout: true,
style: true,
content: true,
minLayoutPosition: 4,
minLayoutDimension: 10
minShiftGraphic: 2
ignoreStringNoA comma-delimited list of css selectors to ignore when performing visual diffs.

Example: #some-id, .some-selector.

failOnNewStatesBooleanNoOption to set build to failure when new states are found, and to disable using new states as a baseline.

This option defaults to true, and can be set to false if user wants new states to automatically be the visual baseline without needing to review and accept them.

alwaysAcceptBaseBranchBooleanNoOption to automatically accept new and changed states in base branch. Assumes base branch should always be correct.false
disableBranchBaselineBooleanNoOption to disable independent baseline for each feature branch, and only use base branch as baseline. Must be used with "baseBranch" option.false
scrollAndStitchScreenshotsBooleanNoOption to capture a full-page screenshot using a scrolling and stitching strategy instead of using native browser full-page screenshot capabilities.false
disableCORSBooleanNoOption to disable adding CORS headers. By default, CORS headers are set for all cross-origin requests.false

BooleanNoOption to enable the capturing and comparing of iframes content. Pseudo states on iframes like hover, focus, focus-within, and active are not supported.false

ObjectNoOptions to control the capturing and comparing of iframes content.
maxFrames: Infinity