Testing web apps in JavaScript using WebdriverIO | Applitools Documentation

Quickstart for Visual Testing with WebdriverIO

This quickstart will show you how to visually test web apps in JavaScript using WebdriverIO. Visual testing can help you catch problems that traditional automation struggles to find.

After preparing your environment, this three-step quickstart should take about 15 minutes to complete.

Step 1: Preparing your environment

You'll need a few things to run this quickstart:

  1. An Applitools account, which you can register for free.
  2. A recent version of Node.js.
  3. A good JavaScript editor like Visual Studio Code.
  4. An up-to-date version of Google Chrome.

Step 2: Getting your example project

Downloading the example project

The example project is located at https://github.com/applitools/example-webdriverio-javascript. Clone this repository to your local machine:

git clone https://github.com/applitools/example-webdriverio-javascript.git
cd example-webdriverio-javascript

Don't have Git?

Instead of running git clone, you can download the project as a ZIP file and extract it.

Installing the dependencies

The example project uses npm for package management. For WebdriverIO, you must install project dependencies and ChromeDriver. Run the following commands (which work for both example projects on any operating system):

npm install
npm install chromedriver --detect_chromedriver_version

Adding Applitools to Another WebdriverIO Project?

This example project already has the Applitools Eyes SDK as a dependency. If you want to add the Applitools Eyes SDK as a new dependency to another WebdriverIO project, run the following command:

npm install --save-dev @applitools/eyes-webdriverio

Deciding how to run tests

The test uses Selenium WebDriver to automate the browser. There are two places to run your Selenium WebDriver session:

  1. On your local machine (which is the default option)
  2. On Applitools Execution Cloud

If you run WebDriver locally, then you need to set it up and manage it yourself. If you use Execution Cloud, then Applitools will manage WebDriver for you. It will also automatically heal broken locators and wait for elements to be ready. If you would like to try Execution Cloud, please request access. The docs for Execution Cloud provide more information.

There are two ways to test the visual snapshots captured by the test:

  1. Using Applitools Ultrafast Grid for cross-browser testing in the cloud
  2. Using Applitools Classic runner on your local machine

Walking through the code

The project contains one visual test case, which is located at test/acme-bank.test.js.

acme-bank.test.js is a test module that covers login behavior for the ACME Bank demo web app. It uses the Applitools Eyes SDK for WebdriverIO to execute the test. The variables at the top control how tests will run:

Setup varies slightly for these different options. In-line comments explain every section. Read it top to bottom to understand how it works:

'use strict';

const { remote } = require('webdriverio');

const { Eyes,
  ClassicRunner,
  VisualGridRunner,
  RunnerOptions,
  Target,
  RectangleSize,
  Configuration,
  BatchInfo,
  BrowserType,
  ScreenOrientation,
  DeviceName } = require('@applitools/eyes-webdriverio');

describe('ACME Bank', function () {
  const USE_ULTRAFAST_GRID = true;
  const USE_EXECUTION_CLOUD = false;
  var applitoolsApiKey;
  let batch;
  let config;
  let runner;
  let eyes;

before(async () => {
    applitoolsApiKey = process.env.APPLITOOLS_API_KEY;
    if (USE_ULTRAFAST_GRID) {
      runner = new VisualGridRunner(new RunnerOptions().testConcurrency(5));
    }
    else {
      runner = new ClassicRunner();
    }
    const runnerName = (USE_ULTRAFAST_GRID) ? 'Ultrafast Grid' : 'Classic runner';
    batch = new BatchInfo(`Example: WebdriverIO JavaScript with the ${runnerName}`);
    config = new Configuration();
    config.setApiKey(applitoolsApiKey);
    config.setBatch(batch);
    if (USE_ULTRAFAST_GRID) {
      config.addBrowser(800, 600, BrowserType.CHROME);
      config.addBrowser(1600, 1200, BrowserType.FIREFOX);
      config.addBrowser(1024, 768, BrowserType.SAFARI);
      config.addDeviceEmulation(DeviceName.Pixel_2, ScreenOrientation.PORTRAIT);
      config.addDeviceEmulation(DeviceName.Nexus_10, ScreenOrientation.LANDSCAPE);
    }
  });

beforeEach(async function () {
    eyes = new Eyes(runner);
    eyes.setConfiguration(config);
    if (USE_EXECUTION_CLOUD) {
      const executionCloudUrl = new URL(await Eyes.getExecutionCloudUrl());
      const protocol_val = executionCloudUrl.protocol.substring(0, executionCloudUrl.protocol.length - 1);
      browser = await remote({
        logLevel: 'trace',
        protocol: protocol_val,
        hostname: executionCloudUrl.hostname,
        port: Number(executionCloudUrl.port),
        capabilities: {
          browserName: 'chrome',
        }
      });
    }
    browser = await eyes.open(
      browser,
      'ACME Bank',
      this.currentTest.fullTitle(),
      new RectangleSize(1200, 600)
    );
  });

it('should log into a bank account', async () => {
    await browser.url('https://sandbox.applitools.com/bank');
    await eyes.check(Target.window().fully().withName("Login page"));
    await browser.$("#username").setValue("Chris");
    await browser.$("#password").setValue("CorrectHorseBatteryStaple");
    await browser.$("#log-in").click();
    await eyes.check(Target.window().fully().withName("Main page").layout());
  });

afterEach(async () => {
    await eyes.closeAsync();
    await browser.closeWindow();
  });

after(async () => {
    const allTestResults = await runner.getAllTestResults();
    console.log(allTestResults);
  });
});

Step 3: Running your tests

Setting Applitools variables

Before running the visual test, you must find your Applitools API key and set it as an environment variable named APPLITOOLS_API_KEY. You may set it through your IDE (if applicable), or you may set it from the command line like this:

export APPLITOOLS_API_KEY=<your-api-key>
set APPLITOOLS_API_KEY=<your-api-key>

Launching visual tests

To launch the tests, run:

npm test

By default, the test will run headlessly. After your tests run, you should see results in the Eyes Test Manager.

Injecting visual bugs

You can also change the web page to inject visual bugs:

// await browser.url('https://demo.applitools.com');
await browser.url('https://demo.applitools.com/index_v2.html');

If you rerun the tests, then they should yield "unresolved" results for you to review. Visual differences will be highlighted in magenta.

Taking the next steps with Applitools

Congratulations on completing this quickstart! There's still so much to learn about visual testing with Applitools, but you're off to a great start.

Resources for next steps:

  1. Setting match levels for visual checkpoints
  2. Organizing Tests Into Batches
  3. Run A/B Tests