Skip to main content

Visual E2E Testing Setup and Quickstart

Screener End-of-life

The Screener visual testing solution is going to be discontinued on May 31st, 2024. You can migrate to the new Sauce Labs Visual Testing solution by following the integration steps.

If you have any questions, please reach out to your Customer Success Manager or Sauce Labs Support.

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

Sauce Labs Visual E2E Testing is an automated testing method that integrates with your Selenium WebDriver tests and code, enabling you to combine functional and visual regression UI testing across different browsers and resolutions in the same run. You can use any programming language that Selenium WebDriver supports without having to install additional libraries or SDKs.

What You'll Need​

Integration with Existing WebDriver Tests​

Follow the steps below to add Visual E2E Testing functionality to your WebDriver tests.

tip

New to WebDriver? See Quickstart with Sample WebDriver Tests.

From your terminal or IDE, navigate to your WebDriver test location, then set your Sauce Labs username, Sauce Labs access key, and Visual Testing Screener API key as environment variables. This way, you won't have to enter them with each command and your credentials are protected from exposure in your tests.

export SAUCE_USERNAME="Replace with your Sauce Labs username"
export SAUCE_ACCESS_KEY="Replace with your Sauce Labs access key"
export SCREENER_API_KEY="Replace with your Screener API key"

Add Sauce Labs Test Code​

Sauce Capabilities​

In your WebDriver test configuration section, add the sauce:options capability with your Sauce Labs credentials (as environment variables) nested underneath. Here's what you'd write in JavaScript, for example:

JavaScript example
'sauce:options': {
  username: process.env.SAUCE_USERNAME,
  accessKey: process.env.SAUCE_ACCESS_KEY,
},

See Selenium on Sauce Labs for examples in Java, Python, Ruby, and C#.

Sauce Visual E2E Capabilities​

  1. In your WebDriver capabilities, add the sauce:visual capability containing your desired project name and viewport size.
var capabilities = {
  ...
   'sauce:visual': {
     apiKey: process.env.SCREENER_API_KEY,
     projectName: 'my-project',
     viewportSize: '1280x1024'
   }
 }
  1. In your WebDriver capabilities, 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'
}

Sauce Visual Commands​

In your test script, add the below commands, in this order:

  1. Add the @visual.init command to initialize your Visual test and add a name for it.
  2. 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​

From your terminal or IDE, run your test.

View Results​

Go your Visual Testing Dashboard (Sauce Labs Visual Testing > Log in to Visual) to confirm that your test is running. It should take a few minutes to complete.

tip
Click Show Logs > View Logs on Sauce Labs to see your test results on Sauce Labs.
Visual E2E Quickstart accept state
Visual E2E Quickstart accept state

Accept Baseline​

This first test will be labeled as "failed" because there's no existing baseline to compare it against. To resolve this, you'll need to review and accept the new snapshots as your baseline. Go to the Quickstart > Accept Baseline to see an example of how to do this.

Apply UI Changes​

  1. In your website development environment, apply a simple UI change, such as changing the font color or removing an image.
  2. From your IDE or terminal, run your test again.
  3. Go to your Visual Testing Dashboard, then click the changed state and review the change details.

Quickstart with Sample WebDriver Tests​

Don't have WebDriver, but want to try? Follow the steps below to install our sample project and run your first WebDriver test with E2E Testing. In this example, you'll run a simple automated test on our demo website, Swag Labs.

  1. From your terminal, navigate to your machine's home directory, then clone the Visual E2E Quickstart repository:
git clone https://github.com/luishernandezv/visual-e2e
  1. Navigate to your project directory:
cd visual-e2e
  1. Install project dependencies:
npm install

Set your Sauce Labs username, Sauce Labs access key, and Visual Testing Screener API key as environment variables to avoid having to enter them with each command and to protect them from exposure in your tests.

export SAUCE_USERNAME="Replace with your Sauce Labs username"
export SAUCE_ACCESS_KEY="Replace with your Sauce Labs access key"
export SCREENER_API_KEY="Replace with your Screener API key"

Choose Sample Test​

Choose which test in the project you'd like to run:

What's in the tests?
To view a breakdown of what's happening in each test script, click on any of the WebDriver test links above and refer to the comments in the script. For example:
//Navigate to the test site
await browser.url('http://saucedemo.com')
At a high level, each test script:
  1. Adds your Sauce Labs credentials, test capabilities (e.g., project name), Visual E2E Testing commands.
  2. Launches the Sauce Labs demo website in a browser and logs in.
  3. Carries out a Visual E2E test session (i.e., taking UI snapshots).
  4. Ends session.

Run Test​

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

npm run webdriverio

View Results​

Go your Visual Testing Dashboard (Sauce Labs > Visual Testing > Log in to Visual) to confirm that your test is running.

You'll see a new project under the name sauce-demos/swag-labs, plus a new branch called default.
Visual E2E Quickstart running test

The test should take a few minutes to complete.

Accept Baseline​

  1. This first test will be labeled as "failed" because there's no existing baseline to compare it against. To resolve this, review and accept the new snapshots as your baseline:
  2. From your Dashboard, click Review 2 New.
    Visual E2E review new state
  3. Click on the first snapshot, Swag Labs: Login.
    Visual E2E Quickstart first state
  4. Click New > Accept.
    Visual E2E Quickstart running test
  5. Click on the second snapshot (Swag Labs: Products), then New > Accept.
  6. Return to your Visual Testing Dashboard. The two states should now be labeled as Accepted.
    Visual E2E Quickstart accepted states
tip
Click Show Logs > View Logs on Sauce Labs to see your test results on Sauce Labs.
Visual E2E Quickstart accept state
Visual E2E Quickstart accept state

Apply UI Changes​

  1. Next, we'll run a test containing a UI change to the Swag Labs website in which a 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
  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.

Optional Next Steps​