Writing visual tests that use the Visual 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 Visual GridThe Visual 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 Visual Grid the Eyes SDK captures the DOM and other resource using the browser and sends it to the Visual Grid server, where the checkpoint images is generated concurrently with other checkpoint in your test suite.

Using the Visual 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 Visual Grid and what it can do for you, see the article Introduction to the Visual 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 Visual Grid, which provides a step-by-step guide to changing legacy code to use the Visual Grid.

Overview

Most aspects of coding Eyes visual tests is the same irrespective of whether you use the Visual 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 Visual Grid
Specify which browsers and devices the Visual Grid should render

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

Specifying the use of the Visual Grid

The snippet below illustrates how you can easily switch to using the Visual 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 Visual 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 Visual 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 Visual Grid should render

The configuration object stores the required values of Visual 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 Visual 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 Visual 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 Visual 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 Visual 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 Visual 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 Eyes baseline 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 Visual Grid.

Example

The code below shows a complete example of a test that runs using the Visual 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.