Visual E2E Testing with Selenium WebDriver

Selenium WebDriver#

Integrate Screener into your existing Selenium WebDriver functional tests.

The following explains how to integrate Screener into your Selenium WebDriver tests, using the language/library of your choice. Any programming language that Selenium WebDriver supports can be used with Screener without needing you to install any additional libraries or SDKs.

It takes only a few minutes to integrate Screener into your existing Selenium WebDriver scripts:

  1. Update WebDriver URL.
  2. Update DesiredCapabilities object.
  3. Add Screener Snapshots in your code wherever you want a visual test.

1. Getting Started#

Before you start, you will need to retrieve the Screener API Key and Test Group ID for the tests you want to run.

API Key#

You need your project's API key, which is available from the Project Dashboard:

API Key

Test Group ID#

Create a Test Group configured to run on a WebDriver client, or select a Test Group that has been configured to run tests "On Client". Only Test Groups that have been configured to run tests "On Client" can be used with your own Selenium WebDriver client.

Test Group on client

You will need your Test Group ID, which is available from the Test Group's Project Dashboard:

Group ID

2. Screener Configuration#

To use Screener, you will need to update your WebDriver URL and DesiredCapabilities object.

Remote WebDriver URL#

https://hub.screener.io/wd/hub

Example Code (using Protractor):#

exports.config = {
seleniumAddress: 'https://hub.screener.io/wd/hub',
specs: ['spec.js'],
capabilities: {
browserName: 'chrome',
screener: {
name: 'My Test',
resolution: '1280x1024',
apiKey: '<your-api-key>',
group: '<your-group-id>'
}
}
};

Configuration Details#

All configurations listed below would go into the desiredCapabilities.screener hash.

Required

apiKey#

Description: The API Key associated with your Screener Account. You can get this from the Screener Dashboard.

name#

Description: The name of your test. Used as both a display label and to uniquely identify your test. It is recommended to include browser/platform information so it can be easily differentiated from other tests.

group#

Description: The Test Group id this test belongs to. You can get this by selecting the desired group in the Screener Dashboard.

resolution#

Description: A width-by-height representation of your desired resolution.

Optional

environment#

Description: An optional string representing the environment or locale associated with this test.

reference#

Description: An object with a combination of id/name/environment key/values. Used to reference another test to diff against. Useful for Cross-Browser testing (comparing a browser to another reference browser), and Localization testing (comparing a locale to another reference locale).

Advanced Configuration (Optional)#

ignore#

Description: A comma-delimited list of css selectors to ignore when performing visual diffs.

options#

Description: An object for enabling/disabling different types of UI validation. All validation types are enabled by default. The validation options are listed below:

structure(Optional) Boolean true/false value, to enable or disable structural validation. Enabled by default.
layout(Optional) Boolean true/false value, to enable or disable layout validation. Enabled by default.
style(Optional) Boolean true/false value, to enable or disable style validation. Enabled by default.
content(Optional) Boolean true/false value, to enable or disable content validation (including text & images). Enabled by default.
text(Optional) Boolean true/false value, to enable or disable text validation. Do not use with "content" option. Enabled by default.
graphic(Optional) Boolean true/false value, to enable or disable validation of images and charts. Do not use with "content" option. Enabled by default.

Example: Example to disable content validation for a locale-to-locale test:

...
screener: {
options: {
structure: true,
layout: true,
style: true,
content: false
}
}
...

3. Screener Snapshots#

To take a Screener Snapshot, we wanted a very simple, safe, and unobtrusive way to integrate it into your existing code without needing to install anything.

A Screener Snapshot is simply a JavaScript comment:

/*@screener.snapshot*/

This allows us to extend the capabilities of Selenium without breaking anything, or requiring the user to install anything. The result is that if you wanted to run against the Screener Hub, then it would take snapshots. If you wanted to run against your own Selenium Grid, then it would do nothing.

This JS comment can be added into your code wherever you want a snapshot to be taken.

Example Code (using Protractor):#

browser.driver.executeScript('/*@screener.snapshot*/', 'State Name');

Snapshot Parameters#

State Name#

Description: (Required) The name of the state associated with the snapshot.

Options#

Description: (Optional) An object with a combination of id/cropTo/ignore key/values.

  • The "id" option is a string which unique identifies this snapshot. Useful if you plan on changing the State Name, and want to retain associations to older tests.
  • The "cropTo" option is a css selector to crop the snapshot to.
  • The "ignore" option is a comma-delimited list of css selectors to ignore for this snapshot when performing visual diffs.

4. Run Tests#

Run your functional tests as you normally would, locally or through your CI process.

To view the progress of your test run in Screener, select the associated Test Group in the Dashboard, and click the History tab:

History

Details and current status of your test runs will be displayed.

5. Code Examples#

Protractor/conf.js#

exports.config = {
seleniumAddress: 'https://hub.screener.io/wd/hub',
specs: ['spec.js'],
capabilities: {
browserName: 'chrome',
screener: {
name: 'My Test',
resolution: '1280x1024',
apiKey: '<your-api-key>',
group: '<your-group-id>'
}
}
};

Protractor/spec.js#

describe('Protractor Example', function() {
it('should take snapshot of homepage', function() {
browser.driver.get('https://screener.io');
browser.driver.executeScript('/*@screener.snapshot*/', 'Home');
});
});

nightwatch.json#

{
"src_folders": ["tests"],
"test_settings": {
"default": {
"selenium_port": 80,
"selenium_host": "hub.screener.io",
"desiredCapabilities": {
"browserName": "chrome",
"screener": {
"name": "My Test",
"resolution": "1280x1024",
"apiKey": "<your-api-key>",
"group": "<your-group-id>"
}
}
}
}
}

tests/basic.js#

module.exports = {
'Nightwatch Example' : function (browser) {
browser
.url('https://screener.io')
.execute('/*@screener.snapshot*/', ['Home'])
.end();
}
};

6. Supported Browsers#

Test script capability:

{
browserName: "chrome"
}

Current Chrome version: 87.0

Last updated on by Kim