Skip to main content

Using the SDK as a service

What is the service?​

As users of webdriver.io, you may choose to use the SDK directly. However, webdriver.io provides an addon mechanism called Services, which lets you reduce boilerplate code and simplify test logic. Read more about it here.

Eyes-WebdriverIO can be used as a webdriver.io service. Using the service provides several boilerplate operations and default values, and lets you concentrate on the core logic.

What is the difference from just using the SDK directly?​

Here are the main differences between the service and the SDK:

  • No need to call eyes.open and eyes.close. Only eyes.check (or its service equivalent, browser.eyesCheck) is needed. The open and close calls are made between different it's, so each functional test that contains visual checkpoints will appear in Eyes dashboard separately.

  • No need to specify testName and appName in the configuration. These values are automatically extracted from the it's and describe's. The default test name is the containing it, and the default app name is the it's containing describe.

  • No need to instantiate the Eyes class. It is instantiated for you, and configured appropriately from wdio.conf.js.

  • Receiving batch completion notifications when test execution is done.

How to use the service​

First, add Eyes-WebdriverIO to your configuration as a service. Add the following to your webdriver.io configuration file:

Node.js version 16 and later:​

const {EyesService} = require('@applitools/eyes-webdriverio/service')

exports.config = {
  // ...
  services: [[EyesService, {
    // webdriver.io version 6: Eyes service configuration here
  }]],
  // ...
  eyes: {
    // webdriver.io version 5: Eyes service configuration here
  }
}

Node.js version 15 and earlier:​

const {EyesService} = require('@applitools/eyes-webdriverio/dist/service')

exports.config = {
  // ...
  services: [[EyesService, {
    // webdriver.io version 6: Eyes service configuration here
  }]],
  // ...
  eyes: {
    // webdriver.io version 5: Eyes service configuration here
  }
}

The place where configuration of the service needs to be depends on your webdriver.io version. For details see webdriver.io blog.

Configure the service​

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).

Example (WebDriverIO version 6 and later)​

exports.config = {
  // In webdriver.io 6:
  services: [[EyesService, {
    viewportSize: {width: 1200, height: 800},
    matchLevel: 'Layout',
    matchTimeout: 0,
    batch: {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 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.

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'}
    ]
    // ...
  }
}

Verbose logging​

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

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

Override testName and appName​

The following is 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​

How to setup batch notifications:

// wdio.conf.js

exports.config = {
  // ...
  eyes: {
    batch: {notifyOnCompletion: true}
  }
  // ...
}

For more information, see Batch completion notifications in the Eyes Knowledge Center.

Using the service API​

browser.eyesCheck(tag, checkSettings)​

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

browser.eyesGetTestResults()​

Close the current visual test and return the test results.

Example​

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(selector)​

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.

Example​

browser.eyesSetScrollRootElement('.container')

browser.eyesSetConfiguration(configuration)​

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.

browser.eyesGetConfiguration()​

Gets the configuration object that is defined for the underlying Eyes instance.

browser.eyesAddProperty(key, value)​

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

browser.eyesClearProperties()​

Clears any custom key name/value properties.