The Eyes SDK check Fluent API

You can define checkpoints using two coding styles. One style is a classical method, typified by calls such as eyes$checkwindow, eyes$checkregion - we'll refer to this as the checkXXX style, where each XXX is a specific type of target (window, region, frame) and has parameters that allow a certain amount of configuration of how the image is captured.

The second style is the Fluent API. In this style, instead of a method for each type of target, a single method, eyes$check is used, and this takes as a parameter a chain of methods that define the type of target and optional configuration.

You are not limited to choose between one style or the other. For each checkpoint you can use whichever style is simplest or most convenient. You may find that the target specific methods checkXXX are more convenient in the trivial cases where you simply want to check an entire target and don't need any special configuration, whereas the Fluent API is simpler when you need configuration, especially if it is of the type not supported directly by the checkXXX methods.

This article provides an overview of the Fluent API, with example snippets. The examples also include some calls to the equivalent checkXXX methods in order to allow a comparison between the two styles.

Introduction to the Fluent API

In the Fluent API you create and configure checkpoints using the eyes$check method. You pass this method a parameter that is created from a chain of methods calls from the target and checksettings classes. The particular chain of methods you call, determines the target that will be checked and how it is configured.

Let's look at an example to see what this looks like in practice:


                                
Each method returns a clone of the calling object so that additional calls to methods of that object can be chained directly to the return value.

                                
In the sections that follow, we will explain the methods available for chaining and where they might be used. Full details are available on the method reference page which you can access by clicking on the method name. 

                                
Overview

                                
To define a checkpoint you first select a target, and then you can optionally configure the image capture and match processing. It is convenient to describe three "families" of methods:
                                    
    
                                        
  •  Define the target area - this may be the entire window, an area defined by a web element (e.g. an <iframe>, or a <div> elements) or an  area defined by fixed pixel coordinates.
    • 
                                        
  • Target configuration - optional settings that affect how the image is captured and processed, e.g., the match level, timeout adjustment, whether to match the viewport area or the entire page.
    • 
                                        
  •  Region Configuration – giving special treatment to particular elements or regions in the content, i.e., ignore, floating and match level regions. 
    • 
                                    

                                

                                
For every checkpoint, you have to call one of the method that define the target area. The configuration and  special processing calls are all optional. These methods  are described in more detail in the sections that follow. 

                                
Define the target area

                                
The simplest way to define a target is to specify that the entire window should be matched. This is done using the 
		 target$window target$window 
			
			method:

                                

			By default this method will match that part of the window that is visible in the viewport. We will soon describe the  checksettings$fully
			method tells Eyes that the entire content of the window should be captured and not just what is visible in the viewport.

                                
You can also request that Eyes only check a rectangular sub-region of the page. You can define the region in various ways:
                                    
    
                                        
  • Provide a   by locator or a  webelement reference to an element. Eyes will use the region defined by the CSS box of that element.
    • 
                                        
  • Provide a rectangular region in pixels.
    • 
                                        
  • Provide a locator or element to an iframe embedded in the main page, or nested within another iframe, or a region within that iframe.
    • 
                                    

                                

                                
Here are some examples of targeting a region in the main window:

                                
Here are some examples of targeting a frame or a region in a frame:

                                
Configuration

                                
You can configure all of the checkpoints in a test globally using commands such as:
                                    
    
                                        
  • 
                                             eyes$setforcefullpagescreenshot
                                        
    • 
                                        
  • 
                                             eyes$setmatchlevel
                                        
    • 
                                        
  • 
                                             eyes$setmatchtimeout
                                        
    • 
                                        
  • 
                                             eyes$setignorecaret
                                        
    • 
                                    

                                

                                
If a particular checkpoint needs a configuration that is different from the default, then you could use the global methods to set the configuration you need before calling checkXXX, and then call them again with the default value after calling the checkXXX. The Fluent API provides simple checkpoint specific configuration by chaining configuration methods  to the targeting method;  we will see examples of this below. 

                                
There are two types of checkpoint configurations. Target configurations affects the overall processing of the target, whereas region configurations define areas that will be processed differently from the rest of the target. 

                                
Target configuration

                                
The following target configuration methods are defined - availability may depend on your SDK:
			
                                    
    
                                        
  • 
                                             checksettings$fully : Request that the entire content on the page is matched and not just the viewport (i.e., Eyes may need to use scrolling to take multiple screenshots and stitch them together into a single image).
    • 
                                        
  • 
                                             checksettings$setscrollrootelement : Used to define explicitly the element on the page that is  scrolled when the full page is rendered.
    • 
                                        
  • 
                                             checksettings$matchlevel : Specify the match level that should be used for the target area.
    • 
                                        
  • 
                                             checksettings$timeout : Specify the maximum amount of time that Eyes should retry capturing the window content if there are mismatches. This is used when a window rendering is slow, and the capture is done before the rendering is complete.
    • 
                                        
  • 
                                             checksettings$ignorecaret : Specify that Eyes should eliminate mismatches reported because of artifacts introduced by a blinking cursor.
    • 
                                        
  • 
                                             checksettings$beforerenderscreenshothook : Specifies JavaScript code to be executed by the browser that renders the page before the page is rendered.
    • 
                                        
  • 
                                             checksettings$ignoredisplacements : Specifies the state of the ignore displacements flag for this checkpoint when the 
					step for the checkpoint is viewed in the Test Manager See Hide displacement diffs tool for details.
    • 
                                        
  • 
                                             checksettings$senddom : Specifies if DOM data should be sent to Eyes for use in matching and in Root Cause Analysis .
    • 
                                        
  • 
                                             checksettings$withname : Specifies a tag for this target (instead of a parameter to the   eyes$check method.
    • 
                                    

                                

                                
Each of these methods is optional but should not be called more than once. They may be called in any order.

                                
The  checksettings$fully method

                                
If a true value is passed to this method, or no value at all, then Eyes will capture multiple sub-images of the target at different scrolling offsets so that the captured image includes all of the content in the target area. As shown in the examples, the target may be the entire window, a region of the window, an embedded frame or a region of a frame. The scrolling is always done at the level of the target frame, unless you use the method  checksettings$setscrollrootelement. If a false value is passed as a parameter, or this method is not called then the checkpoint image will only contain the content visible in the viewport.

                                

            The  checksettings$matchlevel method

                                
The match level defines what types of mismatches will be reported by the Eyes matching algorithm. 
		The default, strict match level detects differences that are visible to the human eye.
			The ignorecolors match level detects differences that are visible to the human eye but ignores changes in color (in previous versions of Eyes this was known as Content).
			The layout match level detects differences in the page structure.	For further information see How to use Eyes match levels

                                
You set the match level for a particular target, by passing the level as a parameter to the matchLevel method. Alternatively, you can also call one of the following shortcut methods: layout, strict, ignore colors.

                                
You set the match level for a particular target, by passing the level as a parameter to the matchLevel method. Alternatively, you can also call one of the following shortcut methods: layout, strict, ignorecolors.

                                
The match level you specify here overrides the default strict level or the level defined at the global level using  eyes$setmatchlevel.

                                

            The  checksettings$timeout method

                                
If a page render is slow, then Eyes may report mismatches caused by a capture that was done before the rendering was complete. To mitigate this case, when Eyes detects mismatches in a checkpoint, it will retry the capture and matching for up to two seconds.   If the default time (two seconds) is not suitable for a particular target, you can change it for that target as follows:

                                
Passing this method a value of zero disables the timeout mechanism for this target.

                                

            The  checksettings$ignorecaret method

                                
If the target area contains a blinking cursor, then this can cause mismatches, since the cursor may be visible or invisible when the page image is captured. You can call this method to instruct Eyes to detect artifacts caused by a blinking cursor, and not report a mismatch if found:

                                

            The  checksettings$withname method

                                
You can (and should) provide a tag for all checkpoints to describe what it represents. This tag is displayed with the step image in the Test Manager, note however that it is not used by Eyes to identify the checkpoint See How Eyes compares checkpoints and baseline images for more details. 
		

                                
When a check is used with a single target, then the tag can be defined by the first parameter of the  check method or by adding this method to the chain of calls. When  check defines more than one target, then the  checksettings$withname should be called on each target to assign it its tag:

                                
Region Configuration

                                
Sometimes, specific elements or areas of the target needs to be configured differently from the overall target content. Eyes supports the following types of region configuration:
                                    
    
                                        
  •  Ignore regions: Specify that one or more areas in the target should be considered matched irrespective of their content. This is useful for example for areas on the screen whose content is different on every run such as a time of day field.
    • 
                                        
  •  Floating regions: Specify that a given inner area can legitimately be positioned anywhere in an enclosing outer area. For example, an icon that is to the right of a variable width text field may move horizontally depending on the size of the text.  
    • 
                                        
  •  Match Level regions: Specify that a region should be matched with a match level that is different from the match level of the rest of the target area.
    • 
                                    

                                

                                
Unlike the target configuration methods that are called once per target, these methods can be called multiple times, to define multiple regions with different handling.

                                
The Eyes SDK generates a unique ID for each coded region so that the region can be compared even if the location of the region has changed. You can override the generated Id by using the regionId parameter as part of the Region targeting. For details, see ignore-method.

                                
You can also define these regions interactively and visually in the Test Manager, but defining them in the code is typically more flexible and robust. A region defined in the Test Manager will only apply only to the baseline where it was applied, and the area will be defined in hard-coded pixel values. A region defined in the code  will apply to whatever baseline the test runs with, and can be defined  using an element selector, so the  special handling will apply to that element even if its layout position changes.

                                

            The  checksettings$ignore method

                                
The regions you specify with this method will ignored, i.e. the area defined by the region be considered "matched" irrespective of their content, or the content of the baseline. You can specify the region in one of several ways:
                                    
    
                                        
  •  By specifying a  by selector.
    • 
                                        
  •  By providing a reference to an element using a  webelement
    • 
                                        
  •  By providing an explicit top left coordinate and dimension of the area in pixels.
    • 
                                    

                                    
If you want to define more than one area, then you can pass a series of comma-separated values (Example 10a) or pass an array of values (Example 10b), or pass a  by that resolves to multiple elements (Example 10c), and you can also call this method multiple times (shown in all the examples).

                                

                                

            The  checksettings$floating method

                                
A floating region defines that a given inner region area should be checked within the bounds of a larger outer region. The entire outer region will be considered matched if the inner region matches any area within the outer region. For example, you can use a floating region, when a page has a variable width text element, and the neighboring field moves, depending on the length of the neighboring text item.

                                
You can specify the floating region position and size in different ways:
                                    
    
                                        
  • By specifying a  by selector
    • 
                                        
  • By providing a  webelement
    • 
                                        
  • By providing an explicit top left coordinate and dimension of the area in pixels.
    • 
                                    

                                    
You can either provide the offsets in each of the directions, or else you can provide a single value that defines the offset for all the directions. The version of the method that takes a single value allows you to pass multiple region objects. 

                                

                                
Setting a match level in a region

                                
This configuration method allows you to specify that one or more areas should use a match level that is different from the match level specified at the global and the overall target area. Three methods are provided, to specify the layout, strict and content Match levels. As for other configuration methods, you can define the region by providing using  by or by providing a  webelement or by providing an explicit area in pixels.

                                
Note that calling one of these methods without a parameter specifies the match level for the entire target, whereas when you call these methods with a region, you are specifying sub-regions that define a different match level than the rest of the target area. To avoid confusion you may choose to always use  checksettings$matchlevel to set the target match level and the other methods to define regions that require a match level that is different from the rest of the target area.
		

                                
Summary

                                
The “Railroad diagram” below, summarizes how the methods may be called. Imagine that you are traveling on a train that follows the lines between the methods from left to right,  remember you’re not allowed to take sharp corners or travel backward! Any path you can follow is a legitimate chain of call for these methods. 

                                
 For simplicity, not all legal paths are shown, for example the methods may be chained in any order. The main point of the diagram is to show the three types of methods, and to show that for a given target:
		

                                
    
                                    
  • Only one target section method may be used.
    • 
                                    
  • All the target configuration methods are optional, but should not be called more than once.
    • 
                                    
  • The region methods are optional and may be called multiple times.
    • 
                                

                                
		Note that some of the methods appear both as target configuration and as region configuration methods. The difference is that the target configuration methods are called without a parameter (and hence apply to all the target), and the region configurations take one or more regions as a parameter.
 The names of the method are the names used in Java, in the other SDKs the names are similar, but are changed to meet the Language naming conventions (The method name starts with an upper case letter for C#, and for Python and Ruby underscores are used instead of CamelCase).


                                

                                

                                
For further information, see the following videos:

                                
Greater Flexibility in Visual Assertions With Fluent API from Applitools
                                

                                

                                

                                
How To Test and Validate iFrames - Applitools Eyes