Skip to main content

WebdriverIO Overview

info

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

This SDK enables you to use WebdriverIO with Applitools Eyes.

For information on how to install and configure this SDK, see Testing web apps in JavaScript using WebdriverIO on the Applitools Tutorial site.

Installation​

To install Eyes-WebdriverIO as a local development dependency in your test project:

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

This command will add the @applitools/eyes-webdriverio package to your project's package.json file and install it in the node_modules directory.

Setting API Key and Server URL​

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, set the environment variable APPLITOOLS_API_KEY to the API key provided by Applitools Eyes. For details on how to retrieve your API key, see the Applitools documentation.

To set the API Key on Linux or macOS:

export APPLITOOLS_API_KEY=<API_key>

To set the API Key on Windows:

set APPLITOOLS_API_KEY=<API_key>

Eyes Server URL​

If the Eyes server is not deployed at https://eyes.applitools.com, set the server URL in the environment variable APPLITOOLS_SERVER_URL.

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

To set the server URL on Linux or macOS:

export APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>

To set the server URL on Windows:

set APPLITOOLS_SERVER_URL=<YOUR_SERVER_URL>

Creating Tests​

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

Here is the basic structure of a test:

eyes.open();
  // step 1
  // step 2
  // ...
eyes.closeAsync();

Using the WebdriverIO SDK​

After defining the API key, you can use commands from Eyes-WebdriverIO in your WebdriverIO tests to take screenshots and manage them with Applitools Eyes.

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();
  });
});

In this example, we import the Eyes and Target classes from the @applitools/eyes-webdriverio package. We then define a test case where we navigate to the https://webdriver.io website using browser.get().

Next, we create an instance of the Eyes class and call the open method to start the visual test. We provide a name for the test ("webdriver.io website") and a description ("My first webdriver.io test").

Within the test, we use the check method to capture a screenshot of the home page using the Target.window().fully() option, which captures the entire window.

Finally, we call closeAsync to end the visual test.

Common Methods​

Eyes Constructor​

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

const eyes = new Eyes(runner);

Arguments​

  • runner (optional) - A runner instance that manages tests across multiple Eyes instances. The runner can be an instance of either ClassicRunner or VisualGridRunner. If not provided, a default runner will be used. For more information, see the Runners section below.

open​

The open method is used to create an Eyes test and start a session with the Applitools server.

Syntax​

eyes.open(driver, appName, testName, viewportSize);

Example​

await eyes.open(browser, 'ACME Bank', 'Test Login', {width: 1200, height: 800});

Arguments​

  • driver - The WebDriver instance representing the browser or mobile application being tested.
  • appName - A string that specifies the name of the application under test.
  • testName - A string that specifies the name of the test.
  • viewportSize - An object that defines the size of the viewport.

Batches​

The concept of batches in Applitools allows you to group tests together for easier analysis and management of test results. You can assign a batch ID to tests that are run in different processes or different instances of Eyes.For details, see the Organize tests in batches.

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

check​

The check function in Eyes is used to generate a screenshot of the current page and add it as a checkpoint in the Eyes test. It allows you to compare the captured image with a corresponding baseline image.

Syntax​

eyes.check(tag, checkSettings);

The tag parameter is a string that serves as a name to identify the checkpoint in the Eyes Test Manager. You can assign any value to the tag, and changing it will not impact the test. It is used for organizing and managing checkpoints in the Test Manager. For more information, see How Eyes compares checkpoints and baseline images in the Eyes Knowledge Center.

closeAsync​

The closeAsync method is used to close the Eyes test. It is called at the end of each test, parallel to the eyes.open method. The closeAsync method does not wait for the Eyes server to return a result immediately. Instead, it allows your system to continue running tests while Eyes completes tests in the background.

After executing all the Eyes tests, your code should call Runner.getAllTestResults to retrieve all the test results as a TestResultsSummary.

Syntax​

const testResults = await eyes.closeAsync();

close​

The close method in Eyes is used to close the Eyes test and wait for the Eyes Server to return a single result. It is called at the end of each test, parallel to the eyes.open method. The close command returns a TestResults object that contains detailed test result data.

This method takes an optional boolean parameter. If false, it will not throw an exception if the test found differences (default is true).

info

This is a legacy API as it only returns a single result. We recommend using eyes.closeAsync and eyes.getResults instead.

Syntax​

const testResults = await eyes.close();
// or
const testResults = await eyes.close(false);

getAllTestResults​

Returns an object with the Eyes test results from a given test or test file. This command should be called after closeAsync.

Syntax​

let result = await runner.getAllTestResults(throwErr);
let result = await runner.getAllTestResults();

Type: boolean

Returns: TestResultsSummary

getResults​

Returns TestResults for the last test (open- ... -closeAsync) by the Eyes instance. The getResults method in Eyes is used to retrieve the TestResults for the last test performed by the Eyes instance. It allows you to obtain detailed information about the test results.

By default, calling getResults before calling eyes.closeAsync will throw an error. This ensures that you retrieve the test results only after the test has been closed. However, you have the option to explicitly specify whether an error should be thrown or not by passing a boolean parameter.

Syntax​

const results1 = await eyes.getResults(); // throws an error by default
const results2 = await eyes.getResults(true); // explicitly specifies that an error should be thrown
const results3 = await eyes.getResults(false); // explicitly specifies that an error should NOT be thrown
  • results1 will throw an error if called before eyes.closeAsync.
  • results2 explicitly specifies that an error should be thrown if called before eyes.closeAsync.
  • results3 explicitly specifies that an error should not be thrown if called before eyes.closeAsync.

Runners​

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

  • ClassicRunner - This runner is used when the screenshot capturing is done by the SDK itself. It is suitable for traditional visual testing scenarios where screenshots are captured using the Applitools SDK.
  • VisualGridRunner - This runner is used when the screenshot is taken by the Ultrafast Grid.

For details, see Runners.

Logs​

In WebdriverIO, logs are not automatically outputted to a temp directory.

To manually enable logs:

  1. Set an environment variable:

    export APPLITOOLS_SHOW_LOGS=true

  2. Configure it in the code:

    const { ConsoleLogHandler } = require('@applitools/eyes-webdriverio');
    eyes.setLogHandler(new ConsoleLogHandler(true));

    or

    const { FileLogHandler } = require('@applitools/eyes-webdriverio');
    eyes.setLogHandler(new FileLogHandler(true));