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.

Configuration methods

The following methods from the configuration class allow you to specify which browser and emulated or simulated devices the Ultrafast Grid should render Rendering 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:

addBrowser: Render a page on any type of desktop browser, emulated mobile device or simulated iOS device.
addBrowsers: Render pages on a list of targets, each of which may be a desktop browser, an emulated mobile device or a simulated iOS device.

These methods take as parameters objects that define the type of rendering on the target browser or moble device:

DesktopBrowserInfo: The page is rendered using a desktop browser you specify using the type BrowserType.
IosDeviceInfo: The page is rendered using Chrome device emulation for the device specified by the type IosDeviceName..
ChromeEmulationInfo: The page is rendered on a Safari browser running on a mobile simulator that simulates the device specified by the type DeviceName.

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 viewport

When working with the Ultrafast Grid, you specify two types of viewport sizes:

The local browser viewport size: This is the viewport size you pass to the configuration$setviewportsize method 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$addbrowser method, or is the size implied by the device you pass to the configuration$adddeviceemulation method.

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.

In many cases, the value set as the local browser viewport size, is not critical since all elements of the page are available in the DOM irrespective of the viewport size. However, on some sites, the viewport size affects what is downloaded to the browser. For example, consider a site that is responsive and to minimize drawing time, it runs JavaScript that only creates and displays a sidebar menu when the browser is wide. When the browser is narrow, it only displays a hamburger icon and only generates the menu when the hamburger icon is clicked. In this case, if you set a narrow viewport for the local browser, the DOM extracted by the SDK and sent to the Ultrafast Grid includes the hamburger icon element, but not the sidebar menu. If the rendered viewport size is set to a wide value, the layout on the Ultrafast Grid will adjust to include the side menu but the side menu element won't be found in the DOM.

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.

The 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 two or more browser configurations are supposed to look the same, then you can use the Eyes baseline environment The 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.

Setting up the baseline environment when using the Ultrafast Grid

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 Running 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 configuration$setmatchlevel. See matchlevel for a detailed description of the Layout match level and how it differs from the Strict level.