Check Settings

The checkSettings method generates a screenshot of the current page and adds it to the Eyes test. It offers various parameters to control what is included in the screenshot. This topic provides examples of some of the common parameters.

Syntax

await eyes.check(checkSettings)

Page Screenshot

Use Target.window() to capture a screenshot of the current viewport, which captures the visible portion of the page as it appears in the browser window.

await eyes.check(Target.window());

Full Page Screenshot

Use the fully() method to capture a full-page screenshot. Eyes will automatically scroll the page to capture the entire content from top to bottom.

To take a full page screenshot, scrolling to the bottom of the page:

Target.window().fully()

Region Screenshot

To include only a specific region in the screenshot, use either a selector or the element itself to define the region.

By Locator

To define a region by locator:

const locator = by.css('.banner');
await eyes.check('region by locator', Target.region(locator));

You can provide a locator, such as by.css('.banner') to specify a region based on a CSS selector. Eyes will capture the content within the region defined by the selector.

By Element

To define a region by element:

const el = element(locator);
await eyes.check('region by element', Target.region(el));

If you already have a reference to the element, you can directly pass it to Target.region() to define the region to capture.

By CSS Selector

To define a region by CSS selector:

await eyes.check('region by CSS selector', Target.region('.banner'));

Alternatively, you can directly pass the CSS selector to Target.region() to specify the region for capturing.

By Coordinates

To specify absolute coordinates for a region:

await eyes.check('region by coordinates', Target.region({
  left: 10,
  top: 20,
  width: 200,
  height: 80
}));

Full Element

For any of the above options, you can append .fully() to capture the entire content of an element that can be scrolled.

await eyes.check('region by element - fully', Target.region(el).fully());

This will ensure that the entire content of the element, even if it requires scrolling, is included in the screenshot.

Frames

Capture Element Inside Frame

To capture a screenshot of an element inside an iframe, use the Target.frame fluent API.

await eyes.check(
  "element inside frame",
  Target.frame("frame-1").region(by.css(".element-inside-frame")),
);

Capture Entire Frame

Use Target.frame("frame-1") to specify the frame to capture. In this example, the region defined by by.css(".element-inside-frame") within the specified frame will be captured.

To capture a screenshot of the entire frame:

await eyes.check("entire frame", Target.frame("frame-1").fully());

Nested Frames

You can append .fully() to the frame definition, for example. Target.frame("frame-1").fully(), will capture the entire content of the specified frame, including any scrolling if needed.

For nested frames, use multiple calls to Target.frame.

await eyes.check(
  "element inside nested frames",
  Target.frame("frame-1")
    .frame("frame-1-1")
    .region(by.css(".nested-element")),
);

In scenarios where you have nested frames, you can use the Target.frame method multiple times to navigate through the frame hierarchy. This allows you to capture elements within the nested frames by specifying the appropriate regions.

Ignore Regions

Differences in ignore region will be ignored and will not be reported in the test results. For example, you may want to ignore banner ad or time field which is different every time that the page is reloaded.

To exclude differences in specific areas from being reported in the test results, you can use ignore regions. These regions will be ignored during the comparison process. For instance, you may want to ignore a banner ad or a time field that changes every time the page is reloaded.

Ignore regions will be excluded from the comparison process.

await eyes.check(
  "viewport screenshot with ignore region",
  Target.window().ignoreRegion(".dynamic-content-here"),
);

In the above code, the .dynamic-content-here element, specified by the CSS selector, will be set as an ignore region. Any differences found within this region will be ignored and not reported in the test results.

Input Types

You can specify ignore regions using the following input types:

String - When providing a string, it will be interpreted as a CSS selector.
by Locator - Defines the ignore region.
Element - Specifies the ignore region by passing an element.
Coordinates ({left, top, width, height}) - If you have specific coordinates for the region, you can define it using the left, top, width, and height properties.

Floating Regions

Define regions that can move without being reported as a difference. This is useful when there are elements on the page that may shift slightly but still should not be considered as visual differences.

await eyes.check(
  'viewport screenshot with floating region',
  Target.window().floatingRegion('.floating-area', 10, 10, 10, 10)
);

In the above code, the .floating-area element, specified by the CSS selector, will be defined as a floating region. The last four parameters (10, 10, 10, 10) specify the margins that allow the region to move without triggering a difference. In this case, the region can move up to 10 pixels in any direction without being considered as a visual difference.

Input Types

String - Interpreted as a CSS selector.
by Locator - Defines the floating region.
Element - Specifies the floating region by passing an element.
Coordinates ({left, top, width, height}) - If you have specific coordinates for the region, you can define it using the left, top, width, and height properties.

Region Match Levels

You can set different match levels for a region to control the sensitivity of the comparison. The available match levels are:

Strict - Identifies differences visible to the human eye.
Ignore colors - Similar to the strict match level but ignores changes in colors.
Layout - Checks only the layout, ignoring text and graphics.
Dynamic - Recognizes defined text patterns such as a date, email address, or URL. For details, see Dynamic text match level

For more information, see How to use Eyes match levels.

Following are examples of how to set different match levels for a region in a viewport screenshot:

// viewport screenshot with strict region
await eyes.check(Target.window().strictRegion('.some-element'))

// viewport screenshot with ignore colors region
await eyes.check(Target.window().ignorecolorsRegion('.some-element'))

// viewport screenshot with layout region
await eyes.check(Target.window().layoutRegion('.some-element'))

// multiple regions
Target.window().strictRegions(region1, region2, region3)
Target.window().ignorecolorsRegions(region1, region2, region3)
Target.window().layoutRegions(region1, region2, region3)

// Dynamic regions - default patterns
Target.window().dynamicRegions(region1, region2, region3)

// Multiple dynamic patterns for a single region
await eyes.check('Multiple Dynamic Text Types', Target.window().dynamicRegion(textSection, [
      DynamicTextType.TextField,
      DynamicTextType.Number,
      DynamicTextType.Email,
      DynamicTextType.Date,
      DynamicTextType.Link,
      DynamicTextType.Currency
	  <Custom Pattern name>
    ]))

Dynamic custom pattern name is defined in the Test Manager. For details, see Dynamic text match level

Input Types

String - Interpreted as a CSS selector.
by Locator - Defines the region.
Element - Specifies the match level region by passing an element.
Coordinates ({left, top, width, height}) - If you have specific coordinates for the region, you can define it using the left, top, width, and height properties.

Accessibility Regions

Define areas within the image that should adhere to contrast regulations for WCAG compliance. You can define specific areas within the image that should adhere to contrast regulations. The following types of accessibility regions can be defined:

Ignore Contrast - This region does not generate an alert and is exempt from contrast checks
Regular Text - The area contains text that should be analyzed for WCAG compliance.
Large Text - The area contains large text as defined in WCAG
Bold Text - The area contains bold text as defined in WCAG
Graphical Object - The object contains an image which needs to meet the WCAG regulations

The following example defines an accessibility region with a specific type in a viewport screenshot:

const {
  AccessibilityRegionType,
} = require("@applitools/eyes-webdriverio");

await eyes.check(
  "viewport screenshot with accessibility region",
  Target.window().accessibilityRegion(
    ".some-element",
    AccessibilityRegionType.LargeText,
  ),
);

In the above code, .some-element is specified as the region using a CSS selector. AccessibilityRegionType.LargeText is used to set the accessibility region type to "Large Text".

Input Types

You can define an accessibility region using the following input types:

String - Interpreted as a CSS selector.
by Locator - Defines the accessibility region.
Element - Specifies the accessibility region by passing an element.
Coordinates ({left, top, width, height}) - If you have specific coordinates for the region, you can define it using the left, top, width, and height properties.

For more information about Accessibility validation in Eyes, see The Contrast advisor in the Eyes Knowledge Center.

Scroll Root Element

By default, Eyes uses internal logic to identify the most appropriate element to scroll to generate a fully screenshot. You can use the scrollRootElement element to specify the element to scroll explicitly.

To take a full page image with a custom scroll element:

await eyes.check(
  'full page with custom scroll root element',
  Target.window().fully().scrollRootElement('.main-content')
)

In the above code, .main-content is specified as the custom scroll root element using a CSS selector. This element will be used as the explicit scroll root when capturing a full-page screenshot.

Input Types

You can specify the scrollRootElement using the following input types:

String -Interpreted as a CSS selector.
by Locator - Defines the scroll root element.
Element - Specifies the scroll root element by passing an element.

By specifying a custom scroll root element, you have control over the element that will be scrolled to capture the full content of the page. This can be useful when the default scroll logic does not capture the desired content correctly.

Variation Group ID

A Variation Group ID allows you to define and manage groups of similar checkpoints or steps within your tests. This is particularly useful when dealing with variations in scenarios where checkpoint images may intentionally vary between test runs, such as during A/B testing. It can also be used by the system to apply auto-maintenance to similar items when a visual difference is accepted.

You can assign a Variation Group ID to a checkpoint explicitly using the SDK, or Eyes can automatically detect and group similar checkpoints.

To explicitly assign assign a Variation group ID:

await eyes.check(Target.window().variationGroupId('Login button on the right'))

In the above code, the checkpoint is assigned the Variation Group ID 'Login button on the right'. This ID helps Eyes identify that this checkpoint is part of a specific variation group.

For more information, see Automated test maintenance of baseline variations in the Eyes Knowledge Center.

Lazy Loading

Lazy loading is a technique used in web development where content is loaded asynchronously as the user scrolls or interacts with a webpage. When capturing a complete screenshot of a page with lazy loading, you need to simulate the scrolling behavior to load all the content before taking the screenshot.

If a page has lazy loading, to get a complete screenshot of the entire page, you need to load the page, scroll a defined length, wait a defined number of milliseconds, and then scroll again until you reach the end of the page or a specific page length.

Default Values

scrollLength - 300 px
waitingTime - 2000ms
maxAmountToScroll - 15,000 px

To use lazy load with default values:

await eyes.check(Target.window().lazyLoad())

By using the .lazyLoad() method, Applitools Eyes will handle the scrolling process automatically based on the default values. It will scroll the page by 300 pixels, wait for 2000 milliseconds, and repeat this process until either the page cannot be scrolled further or the maximum amount of scrolling (15,000 pixels) is reached.

Customized Values

If you want to customize the lazy loading behavior, you can provide an options object with specific values for maxAmountToScroll, scrollLength, and waitingTime

To use lazy load with customized values:

await eyes.check(Target.window().lazyLoad({
  maxAmountToScroll: 1000,   // total pixels of the page to be scrolled
  scrollLength: 250,  // amount of pixels to use for each scroll attempt
  waitingTime: 500,   // milliseconds to wait in-between each scroll attempt
}))

In the above code, the page will be scrolled a maximum of 1000 pixels, with each scroll attempt moving 250 pixels. It will wait for 500 milliseconds between each scroll attempt.

WebView

When working with native mobile applications that contain webviews, Applitools Eyes allows you to capture and verify the contents of those webviews. You can use the Target.webview() method to automatically switch to the first available webview and capture its contents.

To automatically switch to the first available web view:

await eyes.check(Target.webview())

By using Target.webview() without specifying a webview ID, the Applitools SDK will automatically switch to the first available webview and capture its contents during the check command. After the check is performed, the SDK will switch the driver back to the app context it was in before the check.

If you want to capture the contents of a specific webview identified by its ID, you can provide the webview ID as an argument to the Target.webview() method.

To specify based on the webview ID:

await eyes.check(Target.webview('webview-id'))

In the above code, webview-id represents the ID of the specific webview you want to capture. This allows you to target a specific webview within the application.

After the check command is executed, the SDK will automatically switch the driver back to the app context that it was in before performing the check. This ensures seamless integration and allows you to capture and verify the contents of webviews within your native mobile applications.

Density Metrics

You can set the density metrics for capturing screenshots using the densityMetrics() method. This method allows you to specify the exact physical pixels per inch (PPI) of the screen in the X and Y dimensions, as well as the scale ratio.

This method accepts a object value with the following properties:

xdpi - The exact physical pixels per inch of the screen in the X dimension.
ydpi - The exact physical pixels per inch of the screen in the Y dimension.
scaleRatio - The scale ratio.

To set density metrics:

await eyes.check(Target.window().densityMetrics({
  xdpi: 100,
  ydpi: 100,
  scaleRatio: 1
}));

In the above code, the density metrics are set as follows:

xdpi is set to 100, representing the exact physical pixels per inch in the X dimension. ydpi is set to 100, representing the exact physical pixels per inch in the Y dimension. scaleRatio is set to 1, indicating that there is no scaling applied.

By providing these density metrics, you can control the resolution and density of the captured screenshot, ensuring accurate visual comparisons.

Region in Shadow DOM

Capture an element nested inside a shadow DOM.

await eyes.check(
  "region in shadow DOM",
  Target.shadow("EleWithShadowRoot").region("nested-region").fully(),
);

In the above code:

EleWithShadowRoot is the identifier for the element that contains the shadow DOM.
nested-region is the identifier for the region within the shadow DOM that you want to capture.
.fully() indicates that you want to capture the entire region, including its content and any overflow.

By using this approach, you can target specific regions within a shadow DOM for visual validation.

Use DOM

Enriches the Layout match level to include DOM information. This parameter is only relevant if the match type is Layout. The default value is false.

Enable Patterns

Informs Layout to look for repeating patterns in the structure of the page, for example items shopping cart. Once a repeating structure is detected, it will be treated as a single unit and ignore the number of repetitions. Alerts are generated if there are changes such as irregularities or changes in the way internal items are aligned. This parameter requires useDom to be enabled. The default value is False.

await eyes.check(
  "Step Name",
  Target.window()
    .fully()
    .matchLevel(MatchLevel.LAYOUT)
    .useDom(true)
    .enablePatterns(true),
);

Match Timeout

Set the timeout in milliseconds.

config = { matchTimeout: value_number };

Hide Scrollbar

Hide the scrollbar before capturing the screenshot.

config = { hideScrollbars: value_boolean };

Hide Caret

Hide the cursor before capturing the screenshot.

config = { hideCaret: value_boolean };

Syntax​

Page Screenshot​

Full Page Screenshot​

Region Screenshot​

By Locator​

By Element​

By CSS Selector​

By Coordinates​

Full Element​

Frames​

Capture Element Inside Frame​

Capture Entire Frame​

Nested Frames​

Ignore Regions​

Input Types​

Floating Regions​

Input Types​

Region Match Levels​

Input Types​

Accessibility Regions​

Input Types​

Scroll Root Element​

Input Types​

Variation Group ID​

Lazy Loading​

Default Values​

Customized Values​

WebView​

Density Metrics​

Region in Shadow DOM​

Use DOM​

Enable Patterns​

Match Timeout​

Hide Scrollbar​

Hide Caret​

Syntax

Page Screenshot

Full Page Screenshot

Region Screenshot

By Locator

By Element

By CSS Selector

By Coordinates

Full Element

Frames

Capture Element Inside Frame

Capture Entire Frame

Nested Frames

Ignore Regions

Input Types

Floating Regions

Input Types

Region Match Levels

Input Types

Accessibility Regions

Input Types

Scroll Root Element

Input Types

Variation Group ID

Lazy Loading

Default Values

Customized Values

WebView

Density Metrics

Region in Shadow DOM

Use DOM

Enable Patterns

Match Timeout

Hide Scrollbar

Hide Caret