Getting Started with WebDriver

Follow the steps below to integrate Sauce Visual E2E into your Selenium WebDriver tests, using the language/library of your choice. Any programming language that Selenium WebDriver supports can be used without needing to install any additional libraries or SDKs.

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


Verify Requirements

  1. Your WebDriver test(s) use W3C capabilities and Sauce Labs Browsers that are in our supported list.
  2. Your Sauce Labs credentials are set in the "sauce:options" capability:
'sauce:options': {
  username: 'user',
  accesskey: 'xxxxx'


Update WebDriver Capabilities

Add "sauce:visual" capability to your WebDriver test configuration:

WebDriverIO Example:
var capabilities = {
  'sauce:visual': {
    apiKey: process.env.SCREENER_API_KEY,
    projectName: 'my-project',
    viewportSize: '1280x1024'
Java Example:
DesiredCapabilities capabilities = new DesiredCapabilities();
MutableCapabilities sauceVisual = new MutableCapabilities();
sauceVisual.setCapability("apiKey", System.getenv("SCREENER_API_KEY"));
sauceVisual.setCapability("projectName", "my-project");
sauceVisual.setCapability("viewportSize", "1280x1024");
capabilities.setCapability("sauce:visual", sauceVisual);
Python Example:
capabilities = {
  'sauce:visual': {
    'apiKey': os.environ.get('SCREENER_API_KEY'),
    'projectName': 'my-project',
    'viewportSize': '1280x1024'
Ruby Example:
capabilities = {
  "sauce:visual" => {
    apiKey: ENV["SCREENER_API_KEY"],
    projectName: 'my-project',
    viewportSize: '1280x1024'
C# Example:
Dictionary sauceVisual = new Dictionary
    { "apiKey", Environment.GetEnvironmentVariable("SCREENER_API_KEY") },
    { "projectName", "my-project" },
    { "viewportSize", "1280x1024" }
browserOptions.AddAdditionalCapability("sauce:visual", sauceVisual, true);
  • apiKey: get your Screener API Key from here.

Store API Key as an environment variable

Secure your API Key by storing it as an environment variable. For example, store it in an environment variable called SCREENER_API_KEY, and then reference it in NodeJS file with: process.env.SCREENER_API_KEY

For additional configuration options, view the Visual Options documentation.


Connect To Remote Hub

Configure your WebDriver tests to connect to our remote hub at the following url:

WebDriverIO Example:
exports.config = {
  hostname: '',
  port: 443,
  protocol: 'https',
  path: '/wd/hub'
Java Example:
WebDriver driver = new RemoteWebDriver(
   new URL(""),
Python Example:
host = ""
self.driver = webdriver.Remote(host, capabilities)
Ruby Example:
Selenium::WebDriver.for(:remote, url: "", desired_capabilities: caps)
C# Example:
driver = new RemoteWebDriver(new Uri(""), capabilities);


Add Visual Commands

To integrate Visual Commands, we wanted a very simple, safe, and unobtrusive way to integrate it into your existing code without needing to install anything; it is simply a JavaScript comment placed in a WebDriver execute command.

  1. Add a "@visual.init" command to set the name for each test. Add this before capturing snapshots.
  2. Add "@visual.snapshot" commands when you want to capture a visual snapshot; use this whenever you want a snapshot to be taken.

WebDriverIO Example:
it('should take snapshot', () => {
  browser.execute('/*@visual.init*/', 'My Visual Test');
  browser.execute('/*@visual.snapshot*/', 'Home');
Java Example:
public void simpleTest() {
  WebDriver driver = this.getWebDriver();
  JavascriptExecutor js = (JavascriptExecutor) driver;
  js.executeScript("/*@visual.init*/", "My Visual Test");
  js.executeScript("/*@visual.snapshot*/", "Home");
Python Example:
 def test_take_snapshot(self):
    self.driver.execute_script('/*@visual.init*/', 'My Visual Test')
    self.driver.execute_script('/*@visual.snapshot*/', 'Home')
Ruby Example:
it 'should take snapshot' do'')
  driver.execute_script('/*@visual.init*/', 'My Visual Test')
  driver.execute_script('/*@visual.snapshot*/', 'Home')
C# Example:
static void test() {
  IJavaScriptExecutor js = (IJavaScriptExecutor)driver;
  js.ExecuteScript("/*@visual.init*/", "My Visual Test");
  js.ExecuteScript("/*@visual.snapshot*/", "Home");

For more details on commands, view the Visual Commands documentation.

For full examples, view Code Examples.



Great, you're all set!

Now run your first test and view your initial results in the Screener Dashboard.

Note: your initial visual test will fail, and results will be labelled as "New"; Review and Accept them as the baseline.

Next Steps