Handling viewport-dependent JavaScript

There are cases where a tested page contains JavaScript that determines the content or layout of the page based on the viewport width. In some cases, the test needs to provide the Eyes SDK with extra information in order that the page image is rendered correctly.

One example is when a page uses JavaScript to adjust the page content or layout as a function of the viewport width and the test uses the Ultrafast Grid to test multiple execution environments An execution environment is defined as a triplet of <OS, browser, viewport size>. When a test runs, its' execution environment, is defined by the platform on which the test runs or if run on the Ultrafast Grid, by the configuration of the Ultrafast Grid. A baseline is also associated with an execution environment. By default, the baseline chosen for a test is the baseline that has the same application name, test name, and execution environment as the test. with different viewport widths. Conflict can arise since the JavaScript executes on the test browser using its viewport size, and the Ultrafast Grid execution environments are rendered using the viewport size defined for that execution environment.

This article describes SDK layout breakpoints that can be used to visually test such pages successfully by extracting the DOM sent to the Ultrafast Grid at multiple page widths.

Note that no special handling is required if only CSS is used to adapt the page content to the viewport width.

Overview

When the test loads a page into the test browser, the test browser loads the page, executes any JavaScript loaded with that page and creates a DOM. The SDK then sends this DOM to the Ultrafast Grid where it is rendered for each configured execution environment.

When the Ultrafast Grid sizes the browser, device emulator, or simulator to match the viewport size of the execution environment, CSS is applied so that any viewport-width-dependent layout will have the expected effect. However, the on-page JavaScript is not executed. If the JavaScript impacts the DOM and is viewport-width-dependent, then the page may be rendered incorrectly.

To achieve correct rendering in such cases you can configure Eyes to use a set of layout breakpoints. Each such breakpoint defines a viewport widths at which the SDK should resize the browser, and extract the DOM. For each such width, the JavaScript executes, and the resulting viewport-width dependent DOM is sent to the Ultrafast Grid. As a result, the Ultrafast Grid has a set of resulting viewport-width dependent DOMs and for each execution environment it can use the DOM that best matches the execution environment viewport.

For a more detailed explanation see section Handling viewport-dependent JavaScript.

Controlling viewport width

Eyes allows you to control the use of layout breakpoints in the following ways:

These are described in detail in the following sections and concrete examples are given in the SDK methods for defining layout breakpoints section.

Setting layout breakpoints

There are two ways to control the breakpoints at which the SDK generates a DOM:

  • The default handling is that the SDK generates a DOM for each distinct viewport width used by the configured execution environment.

    Alternatively, you can specify a list of viewport widths to use. Then, for each execution environment, Eyes uses the DOM created with the widest viewport width that is smaller than the execution environment viewport width.

For example, say you have specified execution environments with widths of 600, 700, 800, 900 and 1500. By default, Eyes generates five DOMs, one for each width. Alternatively, if you know that the JavaScript changes the page layout at widths of 640, 768 and 1024, then you can specify these values as the layout breakpoints so that the SDK extracts three DOMs at these widths and an additional DOM at 639 since there is an execution environment with a width less then the smallest layout breakpoint specified (600 < 640). The following table summarizes the viewport widths at which the DOM is captured for these two options.

Configuration Widths at which DOM in generated
Default breakpoints

600, 700, 800, 900 and 1500

Explicit Breakpoints

640, 768 and 1024

639 - used for widths < 640 (i.e. 600)

640 - used for widths 640-767 (i.e. 600, 700)

768 - used for widths 768-1023 (i.e. 800, 900)

1024 - used for widths > 1024 (i.e. 1500)

Global and checkpoint layout breakpoints

You can enable and define the viewport widths globally by setting a Configuration object that is assigned to the test. You can then override the setting for particular breakpoints, either to disable layout breakpoints, or to change the layout breakpoints used.

If you only need layout breakpoints for some of the checkpoints, then only set them for those checkpoints, and don't enable layout breakpoints globally using Configuration.

SDK methods for defining layout breakpoints

The section that follows gives examples that illustrate how to:

Enable layout breakpoints globally

The class$configuration$setlayoutbreakpoints method allows you to enable layout breakpoints, and optionally to define the layout breakpoint widths for all of the checkpoints in a test. The sections that follow illustrate how to do this.

Enable layout breakpoints globally with default widths

To enable default layout breakpoints, call the method class$configuration$setlayoutbreakpoints, passing a parameter value of trueconst. When used in this way, the DOM is sampled at each distinct viewport width defined by the execution environments, as described in detail in the Setting layout breakpoints section.


                                
Enable  layout breakpoints globally with defined widths

                                
If you pass the method  class$configuration$setlayoutbreakpoints with one or more integers, then this both enables layout breakpoints and defines the layout breakpoint widths explicitly. The SDK creates a DOM at each of these viewport widths, and if at least one execution environment has a width less than the smallest width given, then an additional DOM is sampled at the minimum defined viewport width, less one (639 in this example). 

                                
Enable  layout breakpoints for a specific checkpoint 

                                
In addition to enabling layout breakpoints and defining the viewport widths to be used globally, you can override these settings for a particular checkpoint using the method  class$checksettings$layoutbreakpoints. If only a few checkpoints require layout breakpoints, then you can simply specify layout breakpoints for the checkpoints that need them rather than defining them globally. In the following snippets, we see the use of this method in three ways:

                                
                                
Enable layout breakpoints with default viewport width handling

                                
The following snippet illustrates how to execute a checkpoint using the default layout breakpoints, even if other layout breakpoints were set explicitly globally, as described in Enable  layout breakpoints with explicitly defined  viewport widths. 

                                
Enable  layout breakpoints with explicitly defined  viewport widths

                                
The following snippet illustrates how to execute a checkpoint using explicit layout breakpoints, even if globally the use of default layout breakpoints was specified, as described in Enable  layout breakpoints globally.

                                
Disable layout breakpoints for a particular checkpoint

                                
The following snippet shows how to disable layout breakpoints for a particular checkpoint, after you have enabled at the global level, as described in Enable  layout breakpoints globally.