Skip to main content

Visual E2E Testing Reference

Visual E2E Commands#

Visual commands can be integrated into existing WebDriver test code simply and safely - no need to install anything.

A Visual command is simply a JavaScript comment sent over WebDriver using the execute command.

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.

Arguments#

ArgumentTypeRequiredDescription
nameStringYesName of Visual test
optionsObjectNoInit command options.

Options available:

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

Code Snippets#

WebDriverIO Example:

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.

Arguments#

ArgumentTypeRequiredDescription
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.
Example
{ ignore: '.selector', cropTo: '#header' }

Code Snippets#

WebDriverIO Examples

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

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#

WebDriverIO Example

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

Example Responses#

Example Response: Success
{  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 use with the sauce:visual capability.

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

Example: 1024x768.

"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.

true
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
iframes

BooleanNoOption to enable the capturing and comparing of iframes content.false
iframesOptions

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