Using viewports in Eyes

The viewport is the visible area of an application within the application window. The viewport size can impact the layout of a page. For example, changing the width of the browser might change the way a paragraph of text is rendered. If the page is designed to be responsive, elements such as menus may be displayed in different ways, fonts size may change, and images may be scaled. Note that the notion viewport is platform specific. For example, on mobile phones the user does not control the size of the browser window.

Note that the specification and impact of the viewport is differently when you use the Classic model and when you use the Ultrafast Grid. The article starts with an explanation of the Classic mode. How this is different when using the Ultrafast Grid is explained in section The viewport size when using the Ultrafast Grid.

How does the viewport impact your tests?

Since the visual look of a page can be dependent on the viewport size, Eyes maintains an independent baseline (i.e. a sequence of baseline images) for every viewport size.

On platforms that allow control over the window size, such as desktop browsers, if the viewport size is defined explicitly in the test using the SDK, then when the test calls the open() method, Eyes calculates and adjusts the operating window size so that the viewport size will be the dimensions requested. On platforms where the user can't control the viewport size, for example on mobile phones, you should not set the viewport size explicitly.

On the first run of a test, Eyes stores the viewport size, along with the operating system and application platform, as the execution environment of the baseline. By default, on subsequent test runs, Eyes compares the checkpoint images to the baselines images taken from the baseline whose execution environment matches the execution environment of the current run.

Using the SDK to set the viewport size

Setting the viewport size is optional. If you do not set a viewport size, then Eyes will work with whatever viewport size is set by the application or by the underlying infrastructure.

The Eyes SDK provides two ways to set the viewport size. One way is to pass the size as a parameter to the open method. This parameter is optional.


                                
You can also set the size using the SDK method setViewportSize.

                                
In this case, you should not pass a viewport size to the open call (the parameter is optional).

                                
To set the viewport size attribute of the baseline, you should call this method before calling the Eyes open method. 

                                
If you call setViewportSize after calling the open method, then this will only change the physical window size and will not impact the baseline definition. However, it may change the layout, and hence the content of the screenshot captured, so you should do this consistently in all test runs, otherwise you might get mismatches.

                                
The call to open will abort the test and throw an exception if the viewport size is set to a size that results in an operating system window that is larger than the desktop. This can happen if the browser and operating system window add extra toolbars or panels. It can also happen if your operating system scales the display. For example, if the display is scaled by 200%, then setting a viewport size of 800x600 would imply a minimal window size of 1600x1200. To avoid problems related to browser differences, it is advisable to use a viewport size that is smaller ( about 50 pixels less) than the maximum value.

                                
The viewport size when using the Ultrafast Grid

                                
The process described so far relates to the classic way of working with Eyes, i.e. when the screen is captured using a browser created by the test and accessed by the SDK. 

                                
When you use the Ultrafast Grid setting the viewport size as described above is still necessary but the impact is different in several aspects:

                                
    
                                    
  • 
                                        
    The browser created by the test is used by the SDK to discover the required resources, to run any on page Javascript and to create the DOM, but not to capture the screen image.
    
                                    
    • 
                                    
  • 
                                        
    The viewport size use for the baseline is not based on the viewport size defined for the browser used by the test, but is defined individually for each execution environment configured for the Ultrafast Grid using the method  class$configuration$addbrowser. The viewport is defined explicitly when browsers are specified using  desktopbrowserinfo$desktopbrowserinfo. The viewport is defined implicitly when devices are specified using  chromeemulationinfo$chromeemulationinfo or  iosdeviceinfo$iosdeviceinfo 
    
                                    
    • 
                                

                                
Note that the DOM is created based on the test browser viewport size, including running any on-page Javascript, but the application of CSS and rendering is done by the Ultrafast Grid. If the Javascript has any dependency on the viewport size then this needs special handling as is described in the article Handling viewport-dependent JavaScript.

                                
Obtaining the viewport size

                                
You can obtain the current viewport size set for the browser used by the test using the SDK method . class$eyes$getviewportsize.