Skip to main content

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​

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.

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');
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);
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:

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:

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.

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.

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:

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.

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.

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.

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.

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

eyes.check('viewport screenshot with ignore colors region', Target.window().ignoreColorsRegion('.some-element'));
eyes.check('viewport screenshot with strict region', Target.window().strictRegion('.some-element'));
eyes.check('viewport screenshot with layout region', Target.window().layoutRegion('.some-element'));

In the above code, .some-element is specified as the region using a CSS selector. The ignoreColorsRegion, strictRegion, and layoutRegion methods are used to set the match level for the respective regions.

You can specify the match level for a region using the same input types as mentioned earlier.

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.

For more information, see How to use Eyes match levels in the Eyes Knowledge Center.

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");

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:

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:

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:


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:

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:

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: 

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:

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.

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.

 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 };