Integrate Screener into Functional Tests

  1. Overview
  2. Getting Started
  3. Configuration
  4. Snapshots
  5. Run Tests
  6. Code Examples
  7. Supported Browsers

1. Overview

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


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


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

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

Note: Only Test Groups that have been configured to run tests "On Client" can be used with your own Selenium Webdriver Client.

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


3. Screener Configuration

To use Screener, you will need to update your Webdriver url and DesiredCapabilities object.

Remote Webdriver Url

Example Code (using Protractor):

More code examples below
exports.config = {
  seleniumAddress: '',
  specs: ['spec.js'],
  capabilities: {
    browserName: 'chrome',
    screener: {
      name: 'My Test',
      resolution: '1280x1024',
      apiKey: '<your-api-key>',
      group: '<your-group-id>'

Configuration Details

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

apiKey(Required) The API Key associated with your Screener Account. You can get this from the Screener Dashboard.
name(Required) The name of your test. Used as both a display label, and to uniqely identify your test. It is recommended to include browser/platform information so it can be easily differentiated from other tests.
group(Required) The Test Group id this test belongs to. You can get this by selecting the desired group in the Screener Dashboard.
resolution(Required) A <width>x<height> representation of your desired resolution.
environment(Optional) An optional string representing the environment or locale associated with this test.
reference(Optional) 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

View DetailsHide Details
ignore(Optional) A comma-delimited list of css selectors to ignore when performing visual diffs.

(Optional) 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 to disable content validation for a locale-to-locale test:
screener: {
  options: {
    structure: true,
    layout: true,
    style: true,
    content: false


4. 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:


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):

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

Snapshot Parameters

State Name(Required) The name of the state associated with the snapshot.
Options(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.


5. 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:

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


6. Code Examples


exports.config = {
  seleniumAddress: '',
  specs: ['spec.js'],
  capabilities: {
    browserName: 'chrome',
    screener: {
      name: 'My Test',
      resolution: '1280x1024',
      apiKey: '<your-api-key>',
      group: '<your-group-id>'
describe('Protractor Example', function() {
  it('should take snapshot of homepage', function() {
    browser.driver.executeScript('/*@screener.snapshot*/', 'Home');


  "src_folders": ["tests"],
  "test_settings": {
    "default": {
      "selenium_port": 80,
      "selenium_host": "",
      "desiredCapabilities": {
        "browserName": "chrome",
        "screener": {
          "name": "My Test",
          "resolution": "1280x1024",
          "apiKey": "<your-api-key>",
          "group": "<your-group-id>"
module.exports = {
  'Nightwatch Example' : function (browser) {
      .execute('/*@screener.snapshot*/', ['Home'])


require 'capybara/rspec'
require 'selenium/webdriver' 
caps = caps.browser_name = 'chrome' caps[''] = 'My Test' caps['screener.resolution'] = '1280x1024' caps['screener.apiKey'] = '<your-api-key>' caps[''] = '<your-group-id>'
Capybara.register_driver :remote do |app|, :browser => :remote, :url => '', :desired_capabilities => caps) end Capybara.default_driver = :remote Capybara.javascript_driver = :remote
describe 'Capybara Example', :type => :feature do it 'should take snapshot of Homepage' do visit('') page.execute_script('/*@screener.snapshot("Home")*/') end end


 import org.openqa.selenium.*;
 import org.openqa.selenium.remote.*;
 import java.util.*;
 public class Test {
   public static void main(String[] args) throws Exception {
     Map screener = new HashMap();
     screener.put("name", "My Test");
     screener.put("resolution", "1280x1024");
     screener.put("apiKey", "<your-api-key>");
     screener.put("group", "<your-group-id>");
     DesiredCapabilities capabilities = DesiredCapabilities.firefox();
     capabilities.setCapability("screener", screener);
     WebDriver driver = new RemoteWebDriver(
          new URL(""),
     ((JavascriptExecutor) driver).executeScript("/*@screener.snapshot*/", "Home");


using System;
using OpenQA.Selenium;
using OpenQA.Selenium.Remote;
namespace SeleniumTest {
  class Program {
    static void Main(string[] args) {
      IWebDriver driver;
      DesiredCapabilities capability = DesiredCapabilities.Firefox();
      capability.SetCapability("", "My Test");
      capability.SetCapability("screener.resolution", "1280x1024");
      capability.SetCapability("screener.apiKey", "<your-api-key>");
      capability.SetCapability("", "<your-group-id>");
      driver = new RemoteWebDriver(new Uri(""), capability);
      IJavaScriptExecutor js = driver as IJavaScriptExecutor;


 // Facebook PHP Webdriver
 $host = '';
 $capabilities = DesiredCapabilities::firefox();
 $capabilities = array(
   WebDriverCapabilityType::BROWSER_NAME => WebDriverBrowserType::FIREFOX,
   'screener' => array(
     'name' => 'My Test',
     'resolution' => '1280x1024',
     'apiKey' => '<your-api-key>',
     'group' => '<your-group-id>'
 $driver = RemoteWebDriver::create($host, $capabilities);
 $driver->executeScript('/*@screener.snapshot*/', array('Home'));


 from selenium import webdriver
 screener = {
   'name': 'My Test',
   'resolution': '1280x1024',
   'apiKey': '<your-api-key>',
   'group': '<your-group-id>'
 caps = {
   'browserName': 'chrome',
   'screener': screener
 driver = webdriver.Remote(
 driver.execute_script('/*@screener.snapshot*/', 'Home')


 require 'rubygems'
 require 'selenium-webdriver'
 screener = {
   :name => 'My Test',
   :resolution => '1280x1024',
   :apiKey => '<your-api-key>',
   :group => '<your-group-id>'
 caps = {
   :browserName => 'chrome',
   :screener => screener
 driver = Selenium::WebDriver.for(
   :url => '',
   :desired_capabilities => caps)
 driver.get ''

7. Supported Browsers

BrowserDesired Capability
  browserName: "chrome"
Current Chrome version: 87.0
  browserName: "firefox"
Current Firefox version: 83.0
Internet Explorer
  browserName: "internet explorer",
  version: "11"