Writing visual tests that use the Ultrafast Grid

In a previous article, we described how to write an Eyes visual test using the classicrunner. When using the classicrunner, the Eyes SDK uses the browser to capture checkpoints. The current article explains how to adapt this code so that is uses the Ultrafast GridThe Ultrafast Grid is an Applitools service that offloads the generation of checkpoint images from the browser running in your test computer to a server running in the cloud. This greatly decreases the test run time, and also allows you to run a test on multiple browsers and emulated devices.. When using the Ultrafast Grid the Eyes SDK captures the DOM and other resource using the browser and sends it to the Ultrafast Grid server, where the checkpoint images is generated concurrently with other checkpoint in your test suite.

Using the Ultrafast Grid considerably reduces test time and also enables you to test multiple browsers and mobile devices in a single test run, with almost no additional test time. For a full description of the Ultrafast Grid and what it can do for you, see the article Introduction to the Ultrafast Grid.

If you have existing legacy Eyes test which does not use the classicrunner, then we recommend reading the article Migrating code to use the Ultrafast Grid, which provides a step-by-step guide to changing legacy code to use the Ultrafast Grid.

Overview

Most aspects of coding Eyes visual tests is the same irrespective of whether you use the Ultrafast Grid or not. The only difference is in how you set up the test suite. This setup consists of two steps:

Specifying the use of the Ultrafast Grid
Specify which browsers and devices the Ultrafast Grid should render

These steps are typically done as part of the process of setting up the test suite.

Specifying the use of the Ultrafast Grid

The snippet below illustrates how you can easily switch to using the Ultrafast Grid by assigning the runner an instance of a visualgridrunner class instead of a classicrunner class.

The type of runner you pass to the Eyes constructor when you create it for each test determines if its checkpoints are rendered using the Ultrafast Grid or not.

The integer value passed to the VisualGridRunner constructor limits the maximum number of Eyes tests that interact concurrently with the Eyes Server and the Ultrafast Grid. Increasing the concurrency value can allow your test suite to run faster, but the maximum possible concurrency depends on your Eyes plan.

Specify which browsers and devices the Ultrafast Grid should render

The configuration object stores the required values of Ultrafast Grid and Eyes attributes. After the Eyes instance is created, the Configuration object is applied to the Eyes instance using the method class$eyes$setconfiguration. The following snippet illustrates this, configuring the Ultrafast Grid with a variety of desktop browsers and emulated devices. It also adds some Eyes configurations that are typically common for all tests. Some of the Eyes configurations which are recommended when using the classicrunner are not required here, since they are always enabled when using the visualgridrunner.

The Eyes SDK provides a number of methods to specify the set of desktop browsers and mobile device emulations that the Ultrafast Grid renders for each checkpoint:

configuration$addbrowser: Render pages on a specified desktop browser (e.g. Chrome, Firefox, IE 11), using a given viewport size. For a list of supported browsers see BrowserType.
configuration.adddeviceemulation: Render pages on an emulated device of a particular brand and model Chrome browser device emulationThe Ultrafast Grid implements mobiles device rendering using Google Chrome Mobile device emulation. The accuracy of the rendering is subject to the possibilities and limitations of that tool. In general, the emulation is an approximation to the page look and feel on a particular mobile device. The most significant factor being the layout, which is impacted by the screen resolution (i.e. viewport size). The actual rendering on the mobile device may be on a different browser, may run on a different operating systems and may run with different hardware - all of which can affect the exact image rendered on a real device. (e.g. iPhone, Samsung Galaxy, Nexus and more). The viewport size is implicit and dictated by the device screen. However, you can specify the orientation of the device (portrait or landscape). For a full list of currently supported devices see DeviceName.
configuration$addbrowser: Render desktop browsers and mobile devices provided as a list.

The snippet provides an example of the use of configuration$addbrowser and configuration.adddeviceemulation. For full details regarding these methods and for more options available see the article Ultrafast Grid Configuration.

You can add as many browser and device configurations as you require. Once you configure an Eyes instance to render on a set of browser configurations, they apply to all the tests that are run using that Eyes instance.

The browser baseline

By default, when running tests using the Ultrafast Grid, every browser configuration uses the baseline

Defines the sequence of images to which the sequence of images captured at checkpoints will be compared. A test can have multiple baselines, each of which is characterized by the execution environment it ran on (operating system, browser and viewport size). A baseline can have instances in multiple branches. implied by the execution environment of that configuration, i.e. the Browser, Viewport size and Operating system:

When adding a desktop browser (e.g. using the configuration$addbrowser method), the Browser and Viewport size baseline attributes are defined by the parameters pf the method. The Operating system attributes will depend on the browser type - Microsoft browsers run on a Windows operating system and other browsers run on a Linux system.
When adding an emulated mobile device (e.g. using the configuration$adddeviceemulation method), the Browser attributes will be "Chrome", the Viewport size will be based on the screen size of that device, and the Operating system attributes will be the name of the native operating system for that device.

If browser configuration has a different layout, then you may very well need a separate baseline for each browser configuration. However, if two or more browser configurations are actually supposed to look the same, then you can use the Eyesbaseline environmentThe baseline environment is a name associated with a particular execution environment (OS, browser, viewport size). When you run a test against a particular baseline environment, Eyes matches the checkpoints against the baseline implied by the baseline environment instead of the baseline implied by the execution environment of the test. feature to do cross-browser testing by specifying a common baseline for multiple browser configurations. For details on how to do this see Setting up the baseline environment when using the Ultrafast Grid.

Example

The code below shows a complete example of a test that runs using the Ultrafast Grid.

The examples are based on TestNG (Java), Node (C#) and Mocha (JavaScript). To adapt them to a different test infrastructure, implement the 4 before/after methods following the pattern illustrated in this example. In the case of the aftertestinstance method, adapt the assignment to testpassed to checks if the test passed or not using the facilities provided by your infrastructure.

If you run this code, in the test manager results you will see on set of results for each of the desktop browsers and mobile devices that are configured in the test.