Skip to main content

WebdriverIO JavaScript overview

note

This information is for WebdriverIO v5 and later. If you are using an earlier version of WebdriverIO, see WebdriverIO v4 JavaScript class index.

Applitools Eyes SDK for WebdriverIO.

For information about installing and configuring this SDK, see Testing web apps in JavaScript using WebdriverIO on the Applitools Tutorial site.

Installation​

Install Eyes-WebdriverIO as a local dev dependency in your tested project:

npm i -D @applitools/eyes-webdriverio

Getting started​

To get started with this SDK, you need to set the following:

Entering the Applitools API key​

To authenticate via the Applitools server and run tests, you need to set the environment variable APPLITOOLS_API_KEY to the API key provided from Applitools Eyes. For details how to retrieve your API key, see the Applitools documentation in the Eyes Knowledge Center.

Entering the API Key on Linux or a Mac​

export APPLITOOLS_API_KEY=<API_key>

Entering the API Key on Windows​

set APPLITOOLS_API_KEY=<API_key>

Eyes server URL​

If the Eyes server is not deployed in https://eyes.applitools.com, you need to set the Server URL in the environment variable APPLITOOLS_SERVER_URL before running tests.

The server URL of your Applitools Eyes dashboard is in the format https://<MY_COMPANY>.applitools.com

Entering the server URL on Linux or a Mac​

export APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>

Entering the server URL on Windows​

set APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>

A test in Applitools Eyes always starts with a eyes.open call and ends with eyes.close. The steps in the test are calls to eyes.check between eyes.open and eyes.close calls.

A test is structured as following:

eyes.open
  [step 1]
  [step 2]
  ...
eyes.close

Using the WebdriverIO SDK​

After defining the API key, you will be able to use commands from Eyes-WebdriverIO in your webdriver.io tests to take screenshots and use Applitools Eyes to manage them.

Example​

const {Eyes, Target} = require('@applitools/eyes-webdriverio')

describe('My first visual test', function() {
  it('should check the webdriver.io website', async function() {
    browser.get('https://webdriver.io');

    const eyes = new Eyes();
    await eyes.open(browser, "webdriver.io website", "My first webdriver.io test!")
    await eyes.check('home page', Target.window().fully())
    await eyes.closeAsync()
  });
});

Common methods​

Eyes constructor​

Creates an instance of Eyes, which then exposes methods to run and configure visual tests.

const eyes = new Eyes(runner)
  • runner - A runner instance which manages tests across multiple Eyes instances. The runner can be an instance of either a ClassicRunenr or a VisualGridRunner. For more information, see the Runners section below.

open​

Creates an Eyes test. This will start a session with the Applitools server.

eyes.open(browser, appName, testName, viewportSize)

Visual tests and baselines​

By using the open, check, and close methods on Eyes, you are creating visual tests in Applitools Eyes. A visual test is a sequence of screenshots, compared with a baseline. The baseline is also a sequence of screenshots. The specific baseline to compare against is found by using the values for:

  • Browser
  • Operating system
  • App name
  • Test name
  • Viewport size

The baseline is created automatically when running a test with specific values for these parameters for the first time. For example, you run a test with Chrome on OS X and specify the app name, test name and viewport size via eyes.open(t, 'some app', 'some test', {width: 1200, height: 800}). The first time the test runs with these parameters, a baseline will be created. Any subsequent execution with the same values will compare screenshots against this baseline. The test will actually be created after running eyes.close, and the results of the test are returned as a TestResults object.

For more information, see How Eyes compares checkpoints and baseline images in the Eyes Knowledge Center.

Batches​

You can aggregate tests that are run in different processes, or in different Eyes instances, under the same batch. This is done by providing the same batch ID to these tests.

For instructions, see the Organize tests in batches.

For more information, see How to organize your tests with batches in the Eyes Knowledge Center.

check​

Generates a screenshot of the current page and adds it to the Eyes Test.

Syntax​

eyes.check(tag, checkSettings)

Arguments to eyes.check​

tag​

Defines a name for the checkpoint in the Eyes Test Manager. The name may be any string and serves to identify the step to the user in the Test manager. You may change the tag value without impacting testing in any way since Eyes does not use the tag to identify the baseline step that corresponds to the checkpoint; Eyes matches steps based on their content and position in the sequences of images of the test.

For more information, see How Eyes compares checkpoints and baseline images in the Eyes Knowledge Center.

close​

Closes the Eyes test and check that all screenshots are valid.

It is important to call this at the end of each test, symmetrically to open, or in afterEach().

const testResults = await eyes.closeAsync(throwEx)
  • throwEx - (Boolean) throw an error if visual differences were found, or if the test failed for any other reason. The default is true.

Return value: TestResults.

getResults​

Returns TestResults for all tests that were run in an Eyes instance. If the test was run with the Ultrafast Grid, TestResults includes results for all environments. If you call getResults before eyes.close the method aborts the test.

const results1 = await eyes.getResults() // throws error by default
const results2 = await eyes.getResults(true) // explicitly specifies that error should be thrown
const results3 = await eyes.getResults(false) // explicitly specifies that error should NOT be thrown

Runners​

Used to manage multiple Eyes sessions. There are the following types of runners:

  • ClassicRunner - Used when the screenshot is taken by the SDK itself.

  • VisualGridRunner - Used when the screenshot is taken by the Ultrafast Grid.

For details, see Runners