Skip to main content

Selenium JavaScript overview

This SDK allows you to work with Applitools Eyes using Selenium JavaScript.

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

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.

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

Runner​

This SDK uses the following Runner classes:

ClassicRunner class​

An object of this class is used to manage multiple Eyes sessions when working without the Ultrafast Grid

For a details of arguments, see ClassicRunner class.

Constructor​

To define the class:

const runner = new ClassicRunner();

GetAllTestResults​

This command returns an object with the Eyes test results from a given test or test file. This command should be called after all Eyes tests have been completed.

const allTestResults = await runner.getAllTestResults();
console.log(allTestResults);

VisualGrid runner​

An object of this class is used to manage multiple Eyes sessions when working with the Ultrafast Grid.

For details of arguments, see VisualGridRunner class.

Constructor​

To define the class:

const runner = new VisualGridRunner({testConcurrency: 5});

GetAllTestResults​

This command returns an object with the results from a test or test file. This command should be called after all Eyes tests have been completed.

Example​

const allTestResults = runner.getAllTestResults();
console.log(allTestResults);

Eyes class​

Eyes Class enables visual testing with Applitools Eyes.

Constructor​

To define the class:

const eyes = new Eyes(runner);

eyes.open​

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

eyes.open(driver, "app name", "test name", {width, height})

Where:

  • driver – Your web driver
  • "app name" – The application name, this may be any string. You can set the application name for all tests using the Configuration.setAppName. If the app name is set in Configuration.setAppName, set this parameter to null.
  • "test name" – The name of the test. This name must be unique within the scope of the application name. It may be any string.
  • (width, height)) (Optional) - Defines the viewport size of the browser that will be set before the start of the test. If this parameter is not provided, the viewport size will be based on the current browser window size.

eyes.check​

This command generate a screenshot of the current page and adds it to the Eyes test.

eyes.check(Target.window())

For details of eyes.check arguments, see CheckSettings class.

eyes.close​

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

It is important to call this command at the end of each test, symmetrically to eyes.open. 

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

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

Other Significant classes​

When working with this SDK, you should be familiar with the following classes:

  • BatchInfo class - Call the Configuration.setBatch method with an object of this class to configure the batch for one or more test.

  • Configuration class - Used to create a configuration object that is used to configure an Eyes object by passing it to the Eyes.setConfiguration method.