Ultrafast Grid Configuration
This article summarizes the API exposed by the Eyes SDK to configure the Ultrafast Grid. For background information on the Ultrafast Grid see the article Introduction to the Ultrafast Grid.
configurationclass allow you to specify which browser and emulated devices the Ultrafast Grid should renderRendering an image is the process of taking the HTML, CSS, text, fonts, images and other resources and generating the screenshot image that is compared to the baseline image. in an Eyes test.
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
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
configuration$addbrowser: Render desktop browsers and mobile devices provided as a list.
Fluent interface example
The snippet below demonstrates how to use the
configuration class fluent API to define browsers and emulated devices for the Ultrafast Grid.
You can add as many browser and device configurations as you want. Assign the configuration to the Eyes instance, using
eyes$setConfiguration, before starting the test (i.e. before calling
class$eyes$open). Once you configure an Eyes instance to render a set of browser configurations, they apply to all the tests that are run using that Eyes instance and can not be changed.
In the above snippet, we've included the configuration method
configuration$setviewportsize to illustrate the recommended best practice where a single Configuration object is used to configure the Ultrafast Grid attributes as well as the global Eyes configuration attributes. You can read more about general Eyes configuration in the article Test suite configuration.
Providing a list of browsers and devices
You can provide the required browser configurations as a list using the
configuration$addbrowsers method. This is useful if, for example, you read the set of devices from a dynamic source like a file or a UI.
- The local browser viewport size: This is the viewport size you pass to the
configuration$setviewportsizemethod and it governs the viewport size of the local browser launched by the test.
- The rendered viewport size: This is the viewport size you pass as a parameter to the
configuration$addbrowsermethod, or is the size implied by the device you pass to the
When you run a test without the Ultrafast Grid, the local browser viewport size determines the baseline used for the test. On the other hand, when you run a test using the Ultrafast Grid, it is the rendered viewport size of each browser configuration which determines the baseline used for that browser configuration, and the local browser is only used to determine the resource required to render the page.
To summarize, if you notice differences in the test results because some DOM elements are missing, make sure that the viewport size you specified for the local browser viewport size is compatible for all the browser configurations of that test. If the browser configurations are not compatible (e.g. they render different layouts with different elements) then run them as separate tests.
- When adding a desktop browser (e.g. using the
configuration$addbrowsermethod), 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$adddeviceemulationmethod), 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 two or more browser configurations are 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.
You can use baseline environments to specify that a specific baseline environment should be used to identify the baseline, instead of the test execution environment. For example, you can assign the name "desktop-browser" to an existing baseline for the Windows/Chrome/1024x768 execution environment. Then you can specify that all the checkpoints should be matched against the "desktop-browser" irrespective of the actual execution environment. For full details on how to use this feature see the article Working with cross-environment tests. This article explains how to specify the baseline environment for a browser configuration.
To specify the execution environment for browser configurations, each of the methods that define a browser configuration also supports an optional baseline environment name parameter.
Before running the test, make sure that the environment names you use are defined in the Eyes Test Manager as described in the article Assign an environment name.
When doing cross browser testing, you should use a match level of
matchlevel$layout. This level focuses on the structure of the page rather than the textual or graphic content, making it more suitable for finding significant differences between browsers. This so done in the snippet above using the method
for a detailed description of the Layout match level and how it differs from the Strict level.