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:

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:

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, reports all mismatches that are visible to the eye. The content match level, is a bit more lenient, for example, it disregards color. The layout match level checks that the general "look" of a target (e.g., text and image elements, their alignment and position relative to each other) but ignores differences such as the actual text.

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


                                

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.

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).