Applitools Eyes Service for webdriver.io 5
Offical Applitools Eyes service for version 5 of the webdriver.io automation framework.
Table of contents
- Appendix: Using the service vs. direct SDK
Install npm package
Install the service as a local dev dependency in your tested project:
npm install --save-dev @applitools/eyes-webdriverio5-service
Add the service to webdriver.io's configuration
The config file is normally located at
exportsconfig =// ...services: '@applitools/eyes-webdriverio5-service'// ...
Applitools API key
In order to authenticate via the Applitools server, you need to supply the Applitools service with the API key you got from Applitools. Read more about how to obtain the API key here.
Using an environment variable
To do this, set the environment variable
APPLITOOLS_API_KEY to the API key before running your tests.
For example, on Linux/Mac:
And on Windows:
Using webdriver.io's config file
It's also possible to specify the API key in the webdriver.io config file (normally located at
wdio.conf.js). This should be placed inside the general configuration for the service, under the
// wdio.conf.jsexportsconfig =// ...services: '@applitools/eyes-webdriverio5-service'eyes:apiKey: 'YOUR_API_KEY'// ...
See the Configuration section below for more information on using the config file.
After completing the installation and defining the service and the API key, you will be able to use Eyes commands inside your webdriver.io tests to create visual tests.
Every configuration parameter that exists in the configuration for Applitools' Eyes SDK for webdriver.io can be specified in the
wdio.conf.js file (or any other webdriver.io configuration file specified by the user).
This is provided in the
eyes entry in the configuration file. For example:
exportsconfig =eyes:viewportSize: width: 1200 height: 800matchLevel: 'Layout'matchTimeout: 0batch: name: 'This will appear as the batch name in Eyes dashboard'// ...
Running with the Ultrafast grid
To run tests with the Ultrafast grid, specify the following in the
exportsconfig =eyes:useVisualGrid: true// ...
To specify which viewport sizes and browsers to render on the Ultrafast grid, use the
browsersInfo entry in the configuration. For example:
exportsconfig =eyes:useVisualGrid: truebrowsersInfo:width: 1200 height: 800 name: 'chrome'width: 1200 height: 800 name: 'firefox'width: 1200 height: 800 name: 'safari'width: 1200 height: 800 name: 'edgechromium'width: 1200 height: 800 name: 'ie'deviceName: 'Galaxy S9 Plus'// ...
For troubleshooting, it is possible to enable versbose logging by specifying the following in the
exportsconfig =// ...enableEyesLogs: true// ...
Here's an example for overriding the default values:
const configuration = browserconfigurationconfigurationbrowser
Batch completion notifications
Here's how to setup batch notifications:
// wdio.conf.jsexportsconfig =// ...eyes:batch: notifyOnCompletion: true// ...
For more information about batch notifications, and the remaining steps required to setup notifications, see https://applitools.com/docs/features/batch-completion-notifications.html.
Generate a screenshot of the current page and add it to the Applitools Test.
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. See How Eyes compares checkpoints and baseline images for details.
Holds the checkpoint's configuration. This is defined using the fluent API, starting with
Target. The default is
Target.window().fully(), which takes a full page screenshot.
For example, to take a viewport screenshot:
const Target =// ...browser
Target API can be used to configure more parameters, such as ignore regions, match level, etc.
Close the current visual test and return the test results. For example:
Sets the scroll root element to a specific element on the page. This is the element that will be scrolled when taking a full page screenshot.
Sets a new configuration for the underlying Eyes instance. This will override the configuration specified in the
wdio.conf.js file for the remainder of test execution.
For example, see the Override
Gets the configuration object that's defined for the underlying Eyes instance.
For example, see the Override
Adds a custom key name/value property that will be associated with your tests. You can view these properties and filter and group by these properties in the Test Manager
Clears any custom key name/value properties.
Appendix: Using the service vs. direct SDK
As users of webdriver.io 5, you may choose to use the SDK directly (package name
@applitools/eyes-webdriverio). However, using the Applitools Eyes service provides several boilerplate operations and default values, and lets you concentrate on the core logic.
Here are the main differences between the service and the SDK:
No need to call
eyes.check(or its service equivalent,
browser.eyesCheck) is needed. The
closecalls are made between different
it's, so each functional test that contains visual checkpoints will appear in Eyes dashboard separately.
No need to specify
appNamein the configuration. These values are automatically extracted from the
describe's. The default test name is the containing
it, and the default app name is the
For more information, see Override
No need to instantiate the
Eyesclass. It is instantiated for you, and configured appropriately from
Receiving batch completion notifications when test execution is done. See Batch completion notifications.