Check Settings

checkSettings generates a screenshot of the current page and adds it to the Applitools Eyes Test.

Syntax

await eyes.check(checkSettings)

Holds the checkpoint's configuration. This is defined using a fluent API, starting with Target.

Page screenshot

• To take a viewport screenshot, call Target.window()
• To take a full page screenshot, call Target.window().fully()

Region screenshot

To take a region screenshot, you can specify either a selector or the element representation itself. For example:

Example

// region by selector
await eyes.check(Target.region('.banner'))

// region by element
const el = await page.$('.banner')
await eyes.check(Target.region(el))

You can specify the absolute coordinates for the required region:

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

For all the above options, you can take the entire content of an element that can be scrolled using .fully().

Frames

To take screenshots of elements inside iframes, you can specify the frame using the Target.frame fluent API. For example:

// element inside frame
await eyes.check(
  Target.frame('frame-1').region('.element-inside frame')
)

To take a screenshot of the entire frame:

// entire frame
await eyes.check(
  Target.frame('frame-1').fully()
)

To create a "frame chain" with multiple calls:

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

Region in shadow DOM

// element inside nested frames
await eyes.check(
  Target.frame('frame-1').frame('frame-1-1').region('.nested-element')
)

Ignore Regions

The test will not report any mismatches in an ignore region. This is useful for example for areas on the screen whose content is different on every run such as a time of day field.

// single region
await eyes.check(
  'viewport screenshot with ignore region',
  Target
    .window()
    .ignoreRegion('.dynamic-content-here')
)

// multiple regions
await eyes.check(
  'viewport screenshot with ignore region',
  Target
    .window()
    .ignoreRegions('.dynamic-content-here', someElement, someCoordinates)
)

Possible input types:

• string (interpreted as css selector)
• element
• coordinates ({left, top, width, height})

Floating Regions

In a Floating Region, the position of a region may move without reporting a mismatch.

// viewport screenshot with floating region
await eyes.check(
  Target
    .window()
    .floatingRegion('.floating-area', 10, 10, 10, 10) // up, down, left, right
)

// multiple regions
await eyes.check(
  Target
    .window()
    .floatingRegions(10, '.floating-area', someElement, someCoordinates) // up, down, left, right all equal to 10
)

Possible input types:

• string (interpreted as css selector)
• element
• coordinates ({left, top, width, height})

Region Match Levels

You can set the following match levels for a region:

• 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:

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

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

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

// multiple regions
Target.window().contentRegions(region1, region2, region3)
Target.window().strictRegions(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.
• 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

Defines an accessibility region and its type.

const {AccessibilityRegionType} = require('@applitools/eyes-puppeteer')

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

// multiple regions is done by chaining the same method
await eyes.check(
  Target.window()
    .accessibilityRegion('.element-1', AccessibilityRegionType.LargeText)
    .accessibilityRegion('.element-2', AccessibilityRegionType.IgnoreContrast)
    .accessibilityRegion('.element-3', AccessibilityRegionType.BoldText)
)

Possible input types:

• string (interpreted as css selector)
• element
• coordinates ({left, top, width, height})

Scroll root element

Normally, Eyes selects the most appropriate element to scroll to execute the Fully keyword. You can use the scrollRootElement element to specify the element to scroll explicitly.

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

Possible input types:

• string (interpreted as css selector)
• element

Tag (withName)

Defines a name for the checkpoint in the Eyes Test Manager. The name may be any string and serves to identify the step to the user in the Test manager.

You can change the tag value without impacting testing in any way since Eyes does not use the tag to identify the baseline step that corresponds to the checkpoint; Eyes matches steps based on their content and position in the sequences of images of the test. For more information, see How Eyes compares checkpoints and baseline images in the Eyes Knowledge Center.

await eyes.check(Target.window().withName('Main page'))

Lazy loading (lazyLoad)

The SDK can scroll the entire page, or a specific length of the page, to make sure all lazyily loaded assets are on the page before performing a check.

Default values

• scrollLength: 300 px
• waitingTime: 2000ms
• maxAmountToScroll: 15,000 px

// lazy loads with default values
await eyes.check(Target.window().lazyLoad())

// lazy loads with options specified
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
}))

Possible input types:

• nothing (enables sensible defaults)
• options object ({maxAmountToScroll, waitingTime, scrollLength})

Other details:

• If an option is omitted, the sensible default for that value will be used
• The SDK will repeatedly scroll the page using the scrollLength until either the page cannot be scrolled further or the maxAmountToScroll has been reached (whichever happens first)
• If more time is needed for additional content to load, increase the waitingTime to a value higher than 500 milliseconds. If additional content lazily loads faster than the default waitingTime, you can improve performance by setting waitingTime a value below 500 milliseconds

Density metrics (densityMetrics)

To set the density metrics for the screenshot, use the densityMetrics method. 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.

// set density metrics
await eyes.check(Target.window().densityMetrics({
  xdpi: 100,
  ydpi: 100,
  scaleRatio: 1
}))

Other checkSettings configuration

• hideScrollbars
• hideCaret
• ignoreDisplacements
• useDom
• enablePatterns
• withName