@applitools/eyes-webdriverio5-service

Table of contents

• Installation
  • Install npm package
  • Add the service to webdriver.io's configuration
  • Applitools API key
    • Using an environment variable
    • Using webdriver.io's config file
• Usage
  • Example
  • Configuration
    • Running with the Ultrafast grid
    • Verbose logging
    • Override testName and appName
    • Batch completion notifications
  • Commands
    • browser.eyesCheck(tag, checkSettings)
    • browser.eyesGetTestResults()
    • browser.eyesSetScrollRootElement(By)
    • browser.eyesSetConfiguration(configuration)
    • browser.eyesGetConfiguration()
    • browser.eyesAddProperty(key, value)
    • browser.eyesClearProperties()
  • Appendix: Using the service vs. direct SDK

Installation

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 wdio.conf.js:

exports.config = {
  // ...
  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:

export APPLITOOLS_API_KEY=<your_key>

And on Windows:

set APPLITOOLS_API_KEY=<your_key>

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 eyes property:

// wdio.conf.js

exports.config = {
  // ...
  services: ['@applitools/eyes-webdriverio5-service'],
  eyes: {
    apiKey: 'YOUR_API_KEY',
  }
  // ...
}

See the Configuration section below for more information on using the config file.

Usage

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.

Example

describe('webdriver.io page', () => {
  it('is visually perfect', () => {
    browser.url('https://webdriver.io')
    browser.eyesCheck('homepage')
  })
})

Configuration

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:

exports.config = {
  eyes: {
    viewportSize: {width: 1200, height: 800},
    matchLevel: 'Layout',
    matchTimeout: 0,
    batch: {name: 'This will appear as the batch name in Eyes dashboard'},
    // ...
  }
}

For more information, visit our documentation page: https://applitools.com/docs/api/eyes-sdk/index-gen/class-configuration-webdriverio_sdk5-javascript.html

Running with the Ultrafast grid

To run tests with the Ultrafast grid, specify the following in the wdio.conf.js file:

exports.config = {
  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:

exports.config = {
  eyes: {
    useVisualGrid: true,
    browsersInfo: [
      {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'}
    ]
    // ...
  }
}

To specify the maximum concurrency rate according to your team/organization's plan:

exports.config = {
  eyes: {
    useVisualGrid: true,
    testConcurrency: 50, // default: 5
    // ...
  }
}

Verbose logging

For troubleshooting, it is possible to enable versbose logging by specifying the following in the wdio.conf.js file:

exports.config = {
  // ...
  enableEyesLogs: true,
  // ...
}

Override testName and appName

Here's an example for overriding the default values:

const configuration = browser.eyesGetConfiguration()
configuration.setAppName('<YOUR_APP_NAME>')
configuration.setTestName('<YOUR_TEST_NAME>')
browser.eyesSetConfiguration(configuration)

Batch completion notifications

Here's how to setup batch notifications:

// wdio.conf.js

exports.config = {
  // ...
  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_.

const {Target} = require('@applitools/eyes-webdriverio5-service')

// ...

browser.eyesCheck(tag, Target.window())

describe('webdriver.io page', () => {
  it('is visually perfect', () => {
    browser.url('https://webdriver.io')
    browser.eyesCheck('homepage')
    $('a[href="/docs/gettingstarted.html"]').click()
    browser.eyesCheck('getting started page')
    const testResults = browser.eyesGetTestResults()

    // example for using the testResults -
    // fail the test if visual differences were found
    if (testResults.getStatus() !== 'Passed') {
      const testName = `'${testResults.getName()}' of '${testResults.getAppName()}'`
      throw new Error(`Test ${testName} detected differences! See details at: ${testResults.getUrl()}`)
    }
  })
})

browser.eyesSetScrollRootElement('.container')