Skip to main content

Setting Up Visual E2E Testing with WebDriver

Screener Docs are Now Sauce Docs
As part of our efforts to bring you a unified documentation site, we've migrated all Visual Docs from Screener.io to Sauce Docs.

Follow the steps below to integrate Visual E2E Testing into your Selenium WebDriver tests. You can use any programming language that Selenium WebDriver supports without having to install additional libraries or SDKs. Whether you're an experienced WebDriver user or have never used it, we've got you covered in the Quickstart steps below.

What You'll Need#

Quickstart with Existing WebDriver Tests#

caution

If you're new to WebDriver, head to Quickstart with Sample WebDriver Tests.

Follow the steps below to integrate Visual E2E functionality with your existing Selenium WebDriver tests.

Set Environment Variables#

  1. Set your Sauce Labs username, Sauce Labs access key, and Screener API key as environment variables:

    What is this?
    PROTECT YOUR CREDENTIALS

    To protect your authentication data from exposure, the example code in this Quickstart requires you to set your Sauce Labs credentials as environment variables. We recommend doing this for all Sauce Labs automated tests.

    export SAUCE_USERNAME="REPLACE WITH SAUCE USERNAME"
    export SAUCE_ACCESS_KEY="REPLACE WITH SAUCE ACCESS KEY"
    export SCREENER_API_KEY="REPLACE WITH SCREENER API KEY"

Add Sauce Capabilities to Test#

  1. Add the sauce:options capability containing your Sauce Labs credentials to your WebDriver test configuration.
    JavaScript example
    'sauce:options': {  username: process.env.SAUCE_USERNAME,  accessKey: process.env.SAUCE_ACCESS_KEY,},
  2. Add the sauce:visual capability containing your project name and viewport size.
var capabilities = {  ...  'sauce:visual': {    apiKey: process.env.SCREENER_API_KEY,    projectName: 'my-project',    viewportSize: '1280x1024'  }}
  1. Configure your test to connect to our remote hub, https://hub.screener.io.
exports.config = {  hostname: 'hub.screener.io',  port: 443,  protocol: 'https',  path: '/wd/hub'}

Add Visual E2E Commands#

  1. Add the @visual.init command to set the name for each test, prior to capturing snapshots. Then add the @visual.snapshot command in the places where you want to capture a visual snapshot.
it('should take snapshot', () => {  browser.url('https://screener.io');  browser.execute('/*@visual.init*/', 'My Visual Test');  browser.execute('/*@visual.snapshot*/', 'Home');});

Run Test#

  1. Run your test.

View Results#

  1. Go to the Visual Testing (Screener) Dashboard to view your test results.

Accept Baseline#

  1. Review and accept your baseline.

Quickstart with Sample WebDriver Tests#

If you've never used WebDriver, follow the steps below to launch a sample WebDriver test with Visual E2E.

Example 1#

In this example, you'll run a simple automated test on our demo website, Swag Labs.

Set Up Project#

  1. From your terminal, clone the Visual E2E Quickstart repository to your local machine:
    git clone https://github.com/luishernandezv/visual-e2e
  2. Navigate to the file path where you downloaded the repository (i.e., cd visual-e2e or cd download/visual-e2e).
    tip

    For the best experience, open the visual-e2e repository in an IDE.

  3. Install dependencies:
    npm install

Set Environment Variables#

  1. Set your Sauce Labs username, Sauce Labs access key, and Screener API key as environment variables:

    What is this?
    PROTECT YOUR CREDENTIALS

    To protect your authentication data from exposure, the example code in this Quickstart requires you to set your Sauce Labs credentials as environment variables. We recommend doing this for all Sauce Labs automated tests.

    export SAUCE_USERNAME="REPLACE WITH SAUCE USERNAME"
    export SAUCE_ACCESS_KEY="REPLACE WITH SAUCE ACCESS KEY"
    export SCREENER_API_KEY="REPLACE WITH SCREENER API KEY"

Set Up Test#

  1. Choose which test script you'd like to run. No need to edit them.


    Click here to view the test script breakdown.
    Sauce Labs credentials
    loading...
    Visual Testing API key and project name
    loading...
    WebDriver configuration with our remote hub
    loading...
    Test Details
    loading...

    What's in the test:

Run Test#

  1. In your terminal, enter the run command corresponding to the test framework you chose in the previous step:

    npm run webdriverio

View Test Results#

  1. Go your Visual Testing Dashboard (Sauce Labs > SAUCE APPS > Visual > Login) to confirm that your test is running. It should take a few minutes to complete. You'll see a new project under the name "sauce-demos/swag-labs", plus a new branch called "default".
    Visual E2E Quickstart running test

Accept Baseline#

  1. This first test will be labeled as "failed" because there's no existing baseline for Visual E2E to compare against. To resolve this, you'll need to review and accept the new snapshots as your baseline:

    • Click Review 2 New.
      Visual E2E review new state
    • Click on the first snapshot, Swag Labs: Login.
      Visual E2E Quickstart first state
    • Click New > Accept.
      Visual E2E Quickstart running test
    • Click on the second snapshot (Swag Labs: Products), then New > Accept.
  2. Return to your Visual Testing Dashboard. The two states should now be labeled as Accepted.
    Visual E2E Quickstart accepted states

  3. Click Show Logs > View Logs on Sauce Labs to view your test results on Sauce Labs in greater detail.
    Visual E2E Quickstart accept stateVisual E2E Quickstart accept state

Apply UI Changes#

  1. Next, we will run a test containing a UI change to the Swag Labs website (login button color changes from red to green). The change is pre-written into the test scripts and will activate once you execute the run command corresponding to the framework you used in the Run Test step:

    npm run webdriverio-changes

Review Changes#

  1. On your Visual Testing Dashboard, you should see a new test running under the same project and branch. Because an element changed in one of your baseline snapshots, the test will be labeled as "failed". To resolve this, you'll need to review and accept them:
    • Click Review 1 Changed.
      Visual E2E Quickstart changed state
    • You'll see that the login button color has changed from red to green. Click Changed > Accept.
      Visual E2E Quickstart accept state
  2. Return to your Visual Testing Dashboard. The two states should now be labeled as Accepted. If you run this test again using the run commands under Apply UI Changes, the result will be labeled Success.

For each build, you should receive an email summary indicating the pass/fail status, delivered to the address associated with your Sauce Labs account.

Example 2#

  1. From your terminal, clone the Sauce Labs JS Training repository to your machine:

    git clone https://github.com/saucelabs-training/demo-js.git
  2. Navigate to the section of our JS repository containing Visual E2E WebdriverIO examples:

    cd webdriverio/webdriver/examples/visual-e2e
    tip

    For best experience, open the visual-e2e repository in an IDE.

  3. Install all dependencies:

    npm install
  4. Run one or both of the following tests using the below run commands:

    Simple test on the Sauce Labs US Data Center:

    npm run test.visual.sauce
  5. View your test results.

Useful Settings#

Timeouts#

If you're using several visual assertions in your test, you may need to increase the timeout value in your configuration to help with test stability.

A single assertion can take up to 45 seconds. So if you had a WebdriverIO test with three snapshots (/*@visual.snapshot*/), for example, you'd need to set your timeout value above 180000 milliseconds (3 mins) to prevent your test from failing.

Advanced Debugging#

To view more in-depth debugging details on Sauce Labs, add extendedDebugging to your test capabilities:

'sauce:options': {  username: process.env.SAUCE_USERNAME,  accessKey: process.env.SAUCE_ACCESS_KEY,  extendedDebugging: true,},

Next Steps#

More Information#