Specifying Type Of Checkpoint In Cypress

Types of Checkpoints

There are 3 different types of checkpoints that can be taken with the Cypress SDK:

1. Full Page (default): Capture the entire page
2. Viewport: Capture what is shown in the browser's viewport without scrolling
3. Region: Capture a specific portion of a page based on coordinates or a specific Element on the page

The type of screenshot captured is configured using the target and fully configuration options:

Name	Target	Fully	Description
Full Page Screenshot	'window' (default)	true (default)	Captures a fullpage screenshot.
Viewport Screenshot	'window' (default)	false	Captures only what is shown in the browser's viewport.
Full Region Screenshot	'region'	true (default)	Capture a specific region on the page coupled with a region or selector configuration indicating the region bounds. If the region you're targeting is scrollable, captures the full region including the parts hidden by the scroll bar.
Region Screenshot	'region'	false	Capture a specific region on the page coupled with a region or selector configuration indicating the region bounds. Only captures the visible portion of the region on the page and will not scroll.

Full Page

// Capture a full page screenshot
cy.eyesCheckWindow({
    tag: "Login page",  // optional
    target: 'window',   // default
    fully: true         // default
});

Since this is the default behavior, the target and fully values are not required in this case however they are included for clarity.

Viewport

// Capture a viewport screenshot
cy.eyesCheckWindow({
    tag: "Login page",  // optional
    target: 'window',   // default
    fully: false
});

Setting fully: false indicates that we want to capture only what's shown in the browser's viewport.

Region

To capture a region screenshot, change the target parameter to region. Then, we must specify the desired region using the selector, element or region configuration option.

Region (Element Selector)

cy.eyesCheckWindow({
    target: 'region',
    selector: '.my-element'
});

This will capture the region of the page defined by the Element's bounding box taht is passed into the selector configuration option.

The selector option will accept a CSS Selector by default but you can also specify an xPath:

cy.eyesCheckWindow({
    target: 'region',
    selector: {
        type: 'xpath',
        selector: '//button[1]'
    }
});

Region (Element Reference)

cy.document()
.then(doc => {
    const el = document.querySelector('div')
    cy.eyesCheckWindow({
        target: 'region',
        element: el
    })
})

Above, we're selecting an element on the page and then passing that element reference directly to the element configuration option.

Region (Coordinates)

cy.eyesCheckWindow({
    target: 'region',
    region: {top: 100, left: 0, width: 1000, height: 200}
});

This will capture the region of the page defined by the coordinates passed into the region configuration option.

Region (Full)

If the HTML element or selector you're targeting is scrollable, you can capture the entire scrollable element by adding the fully: true configuration option:

cy.eyesCheckWindow({
    target: 'region',
    selector: '.my-element',
    fully: true
});

Region (Shadow DOM)

If you're targeting a region within Shadow DOM, you'll need to pass an array of JSON objects to the selector confifguration containing:

• The shadow root element selector (css selector only)
• The element you're trying to capture (css selector only)

cy.eyesCheckWindow({
    target: 'region',
    selector: [
        {
            type: 'css',
            selector: '.shadow-root',
            nodeType: 'shadow-root'
        },
        {
            type: 'css',
            selector: '.target-element',
            nodeType: 'element'
        }
    ]
});

Match levels

You can configure the Visual AI match level for each checkpoint by using the matchLevel configuration argument.

Strict Match Level (Default)

cy.eyesCheckWindow({
    matchLevel: 'Strict'
});

Layout Match Level

cy.eyesCheckWindow({
    matchLevel: 'Layout'
});

Ignore Colors Match Level

cy.eyesCheckWindow({
    matchLevel: 'Ignore Colors'
});

Coded Regions

Applitools SDKs allow you to configure your Visual AI checkpoints with regions that peform different functions:

Region	Type	Description
Layout	Match Level	Apply the Layout Match Level at the specified region of the page
Ignore Colors	Match Level	Apply the Ignore Colors Match Level at the specified region of the page
Strict	Match Level	Apply the Strict Match Level at the specified region of the page
Ignore	Match Level	Ignore visual AI validation at the specified region of the page
Float	Utility	Allow a specified element to move in a predetermined space before failing the test
Accessibility	Utility	Perform an Accessibility AI checkpoint on the specified region

In Depth Guides

Checkout our in depth guides on Choosing a Match Level as well as Working with Regions for more details.

The above configuration options accept the following types of input:

Name	Description	Example
Coordinates	An object containing top, left, width and height properties	layout: {top: 100, left: 0, width: 1000, height: 100}
CSS Selector	A CSS selector that references an element on the page	ignore: {selector: '.my-selector'}
xPath Selector	An xPath selector that references an element on the page	ignoreColors: {type: 'xPath', selector: '//button[1]'}
Element Reference	A variable containing a reference to an element on the page	layout: elemRef

danger

When using a selector argument, all elements that match the specified selector will have a region around them. Be sure to choose your selector carefully to avoid unexpected results.

Each region type will accept a single argument or an array of arguments of any type.

Layout Region

To specify a Layout Match Level region, use the layout configuration option:

cy.eyesCheckWindow({
    // Pass a single option
    layout: {selector: '.my-selector'}
});

cy.eyesCheckWindow({
    // Pass an array to select multiple regions
    layout: [
        {top: 100, left: 0, width: 1000, height: 100},
        {selector: '.my-selector'}
    ]
});

cy.get('.my-selector').then($el => {
    // Pass element reference
    cy.eyesCheckWindow({
        layout: $el
    });
})

Ignore Colors Region

To specify a Strict Match Level region, use the ignoreColors configuration option:

cy.eyesCheckWindow({
    // Pass a single option
    strict: {selector: '.my-selector'}
});

cy.eyesCheckWindow({
    // Pass an array to select multiple regions
    strict: [
        {top: 100, left: 0, width: 1000, height: 100},
        {selector: '.my-selector'}
    ]
});

cy.get('.my-selector').then($el => {
    // Pass element reference
    cy.eyesCheckWindow({
        layout: $el
    });
})

Strict Region

To specify a Strict Match Level region, use the strict configuration option:

cy.eyesCheckWindow({
    // Pass a single option
    strict: {selector: '.my-selector'}
});

cy.eyesCheckWindow({
    // Pass an array to select multiple regions
    strict: [
        {top: 100, left: 0, width: 1000, height: 100},
        {selector: '.my-selector'}
    ]
});

cy.get('.my-selector').then($el => {
    // Pass element reference
    cy.eyesCheckWindow({
        layout: $el
    });
})

Ignore Region

To specify an Ignore region, use the ignore configuration option:

cy.eyesCheckWindow({
    // Pass a single option
    ignore: {selector: '.my-selector'}
});

cy.eyesCheckWindow({
    // Pass an array to select multiple regions
    ignore: [
        {top: 100, left: 0, width: 1000, height: 100},
        {selector: '.my-selector'}
    ]
});

cy.get('.my-selector').then($el => {
    // Pass element reference
    cy.eyesCheckWindow({
        ignore: $el
    });
})

Float Region

To specify a Float region, use the floating configuration option. This region type requires some extra options as arguments.

A floating region is actually a combination of two regions:

1. a region around the element that you're selecting
2. a "bounding" region that specifies where this element can "float" or move until it is flagged as a difference.

tip

You can read more about floating regions and how to use them here.

In addition to the selector, region or element option, you must also configure the following options that define the 2nd "bounding" region mentioned above:

1. maxUpOffset
2. maxDownOffset
3. maxLeftOffset
4. maxRightOffset

cy.eyesCheckWindow({
    // Pass a single option
    floating: {selector: '.my-selector', maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20}
});

cy.eyesCheckWindow({
    // pass an array to select multiple regions
    floating: [
        {top: 100, left: 0, width: 1000, height: 100, maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20},
        {selector: '.some-div-to-float', maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20}
    ]
});

cy.get('.my-selector').then($el => {
    // Pass element reference
    cy.eyesCheckWindow({
        floating: {element: $el, maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20}
    });
})

Accessibility Region

To specify an Accessibility region, use the accessibility configuration option. This region type requires some extra options as arguments.

In addition to the selector, region or element option, you must also configure the accessibilityType value which accepts the following options:

1. IgnoreContrast: Prevent an accessibility check from occurring in the specified region.
2. RegularText: Perform a regular text accessibility check.
3. LargeText: Perform a large text accessibility check.
4. BoldText: Perform a bold text accessibility check.
5. GraphicalObject: Perform a graphical object accessibility check.

cy.eyesCheckWindow({
    // Pass a single option
    accessibility: {selector: '.my-selector', accessibilityType: 'RegularText'} 
});

cy.eyesCheckWindow({
    // pass an array to select multiple regions
    accessibility: [
        {top: 100, left: 0, width: 1000, height: 100, accessibilityType: 'LargeText'},
        {selector: '.my-selector', accessibilityType: 'RegularText'} 
    ]
});

cy.get('.my-selector').then($el => {
    // Pass element reference
    cy.eyesCheckWindow({
        accessibility: {element: $el, accessibilityType: 'GraphicalObject'}
    });
})

Region Padding

All region types allow for optional padding to increase the size of the region that is created with a selector or element argument. By default, regions will be sized to the bounding box of the corresponding web element. The padding options shown below offer more flexibility by letting you increase the size in each direction when needed:

cy.eyesCheckWindow({
    // Pass a single option
    layout: {selector: '.my-selector', padding: {left: 20, top: 10, right: 20, bottom: 10}} 
});

Responsive Web Pages

Layout Breakpoints

This configuration offers the ability to handle Viewport Dependent Javscript by resizing the local browser to the specified widths when capturing a Visual AI checkpoint.

cy.eyesCheckWindow({
    layoutBreakpoints: [500, 1000]
});

Instead of an array of widths, you can also pass in true which will resize the browser to each of the widths specified in your Ultrafast Grid browser configuration:

cy.eyesCheckWindow({
    browser: [
        {width: 1300, height: 1050, name: 'chrome'},
        {width: 1000, height: 1000, name: 'firefox'},
        {width: 800, height: 1000, name: 'safari'}
    ],
    // Will resize to 1300, 1000 & 800 based on the browser config above
    layoutBreakpoints: true
});

You can optionally include a reload argument that will reload the page in between browser resizing events.

cy.eyesCheckWindow({
    layoutBreakpoints: {breakpoints: [500, 1000], reload: true}
});

You can also apply a waitBeforeCapture timeout that will run in between each resize event:

cy.eyesCheckWindow({
    layoutBreakpoints: {breakpoints: [500, 1000]},
    waitBeforeCapture: 1000 // wait 1 second
});

Lazy Loading

Gracefully handle lazy loaded content on web pages using the lazyLoad configuration. This configures the SDK to 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 Visual AI Checkpoint.

// Run with default settings
cy.eyesCheckWindow({
    lazyLoad:{}
})

// Run with custom settings
cy.eyesCheckWindow({
    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
    }
})

Advanced

Script Hooks

beforeCaptureScreenshot

Inject JavaScript to on the browser before capturing a Visual AI checkpoint. This will be run on the Ultrafast Grid and not on the local driver that is executing the tests. The intended purpose of this hook is to alter the page state as needed before the Visual AI checkpoint.

cy.eyesCheckWindow({
    scriptHooks: {
      beforeCaptureScreenshot: "document.body.style.backgroundColor = 'gray'"
    }
})

Visual Grid Options

Extra options that are specific to the Ultrafast Grid.

polyfillAdoptedStylesheets

If your application is using adoptedStylesheets (currently only supported in Chrome), set this configuration option to true to polyfill support for that feature in other browsers.

cy.eyesCheckWindow({
    visualGridOptions: {
        polyfillAdoptedStyleSheets: true
    }
})

Other Parameters

Name	Default	Type	Description
tag	undefined	String	A descriptive name of the visual AI checkpoint.
sendDom	true	Boolean	Send the DOM to the Eyes server for each checkpoint. Required for some features such as RCA and useDom (see below).
variationGroupId	undefined	String	For more information, see Automated test maintenance of baseline variations.
waitBeforeCapture	100	Number	Number of milliseconds to wait before capturing the snapshot. This will also apply between page resizes when using layoutBreakpoints.
useDom	false	Boolean	Only relevant when using the Layout Match Level. Enhances the Layout Match Level by using the DOM to analyze the page along with the screenshot.
enablePatterns	false	Boolean	Only relevant when using the Layout Match Level. Enhances the Layout Match Level.