Visual E2E Commands Reference

Visual commands can be integrated into existing WebDriver test code simply and safely without needing to install anything.

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


Init Command

The Init command 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.

/*@visual.init*/

Arguments:
ArgumentTypeRequiredDescription
nameStringYesName of Visual test
optionsObjectNo

Init command options.

Options available:

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

Example:

{ ignore: '.selector' }


WebDriverIO Examples:
browser.execute('/*@visual.init*/', 'My Visual Test');
browser.execute('/*@visual.init*/', 'My Visual Test', {ignore: '.selector'});
Java Example:
((JavascriptExecutor) driver).executeScript("/*@visual.init*/", "My Visual Test");
Python Example:
self.driver.execute_script('/*@visual.init*/', 'My Visual Test')
Ruby Example:
driver.execute_script('/*@visual.init*/', 'My Visual Test')
C# Example:
((IJavaScriptExecutor) driver).ExecuteScript("/*@visual.init*/", "My Visual Test");


Snapshot Command

The Snapshot command 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.

/*@visual.snapshot*/

Arguments:
ArgumentTypeRequiredDescription
nameStringYesName of Snapshot
optionsObjectNo

Snapshot 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' }


WebDriverIO Examples:
browser.execute('/*@visual.snapshot*/', 'State Name');
 
// example with ignore option
browser.execute('/*@visual.snapshot*/', 'State Name', {ignore: '.selector'});
Java Example:
((JavascriptExecutor) driver).executeScript("/*@visual.snapshot*/", "State Name");
 
// example with ignore option
HashMap options = new HashMap();
options.put("ignore", ".selector");
((JavascriptExecutor) driver).executeScript("/*@visual.snapshot*/", "State Name", options);
Python Example:
self.driver.execute_script('/*@visual.snapshot*/', 'State Name')
Ruby Example:
driver.execute_script('/*@visual.snapshot*/', 'State Name')
C# Example:
((IJavaScriptExecutor) driver).ExecuteScript("/*@visual.snapshot*/", "State Name");


End Command

The End command 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.

/*@visual.end*/

The response contains the following properties:
passedWhether or not the test passed.
statusThe test status. One of: success, failure, error, timeout, cancelled.
totalsVisual regression result totals.
states
List of all snapshots, including name, status and url.
 
Note: url's are not permalinks; url will direct to the latest results for the snapshot.
messageError message.


An example of a successful response:
{
  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
}
An example of a failure response:
{
  passed: false,
  status: 'failure',
  totals: {new: 0, changed: 1, accepted: 1, rejected: 0, all: 2},
  states: [
    {name: 'State 1', groupName: 'Test 1', status: 'accepted', url: '...'}
    {name: 'State 2', groupName: 'Test 1', status: 'changed', url: '...'}
  ],
  message: '1 visual regression found. Test failed.'
}


WebDriverIO Example:
const result = browser.execute('/*@visual.end*/');
assert.ok(result.passed, result.message);
Java Example:
Map response = (Map)((JavascriptExecutor) driver).executeScript("/*@visual.end*/");
Assert.assertTrue((Boolean)response.get("passed"), (String)response.get("message"));
Python Example:
result = self.driver.execute_script('/*@visual.end*/')
assert result['passed'] is True
Ruby Example:
result = driver.execute_script('/*@visual.end*/')
expect(result['passed']).to be_truthy, result['message']
C# Example:
var response = ((IJavaScriptExecutor) driver).ExecuteScript("/*@visual.end*/") as Dictionary;
Assert.IsTrue((Boolean)response["passed"], (String)response["message"]);