Cypress Check Settings
In addition to the built-in commands provided by Cypress, such as cy.visit
and cy.get
, Eyes-Cypress defines the custom commands, which enable the visual testing with Applitools Eyes.
This section lists arguments for cy.eyesCheckWindow
which generates a screenshot of the current page and adds it to the Applitools Test.
Syntax
cy.eyesCheckWindow('Login screen')
or
cy.eyesCheckWindow({ tag: 'Login screen', target: 'your target' })
tag
A logical name for this check (optional).
target
Parameters
window (Default)
If set, the captured image will include the entire page or the viewport.
Values:
fully
- Specifies whichwindow
mode to use.
region
If set, the captured image will be the parts of the page.
Values:
fully
If the
target
iswindow
, andfully
istrue
(default) then the snapshot will be of the entire page. Iffully
isfalse
then the snapshot will be of the viewport.Example
// Capture viewport only
cy.eyesCheckWindow({
target: 'window',
fully: false,
});
region
If
target
isregion
, this should be an object describing the region's coordinates for capturing the image.
Example
cy.eyesCheckWindow({
target: 'region',
region: {top: 100, left: 0, width: 1000, height: 200}
});
selector
If
target
isregion
, this should be the actual css or xpath selector to an element, and the screenshot will be the content of that element.Example
// Using a css selector
cy.eyesCheckWindow({
target: 'region',
selector: {
type: 'css',
selector: '.my-element' // or '//button'
}
});
// Using an xpath selector
cy.eyesCheckWindow({
target: 'region',
selector: {
type: 'xpath',
selector: '//button[1]'
}
});
// The shorthand string version defaults to css selectors
cy.eyesCheckWindow({
target: 'region',
selector: '.my-element'
});
element
If
target
isregion
, this should be an instance of either an HTML element or a jQuery object.Example
// passing a jQuery object
cy.get('body > div > h1')
.then($el => {
cy.eyesCheckWindow({
target: 'region',
element: $el
})
})
// passing an HTML element
cy.document()
.then(doc => {
const el = document.querySelector('div')
cy.eyesCheckWindow({
target: 'region',
element: el
})
})
ignore
A single or an array of regions to ignore when checking for visual differences.
Example
// ignore region by coordinates
cy.eyesCheckWindow({
ignore: {top: 100, left: 0, width: 1000, height: 100},
});
// ignore regions by selector
cy.eyesCheckWindow({
ignore: {selector: '.some-div-to-ignore'} // all elements matching this selector would become ignore regions
});
// ignore regions by jQuery or DOM elements
cy.get('.some-div-to-ignore').then($el => {
cy.eyesCheckWindow({
ignore: $el
});
})
// mix multiple ignore regions with different methods
cy.eyesCheckWindow({
ignore: [
{top: 100, left: 0, width: 1000, height: 100},
{selector: '.some-div-to-ignore'}
]
});
// mix multiple ignore regions with different methods including element
cy.get('.some-div-to-ignore').then($el => {
cy.eyesCheckWindow({
ignore: [
{top: 100, left: 0, width: 1000, height: 100},
{selector: '.some-div-to-ignore'}
$el
]
});
})
floating
A single or an array of floating regions to ignore when checking for visual differences. For further information see Testing of floating UI elements.
Example
cy.eyesCheckWindow({
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}
]
});
// use jQuery or DOM elements
cy.get('.some-div-to-float').then($el => {
cy.eyesCheckWindow({
floating: [
{element: $el, maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20},
]
})
})
layout
A single or an array of regions to match as layout match level.
Example
cy.eyesCheckWindow({
layout: [
{top: 100, left: 0, width: 1000, height: 100},
{selector: '.some-div-to-test-as-layout'}
]
});
// use jQuery or DOM elements
cy.get('.some-div-to-test-as-layout').then($el => {
cy.eyesCheckWindow({
layout: $el
});
})
strict
A single or an array of regions to match as strict match level.
Example
cy.eyesCheckWindow({
strict: [
{top: 100, left: 0, width: 1000, height: 100},
{selector: '.some-div-to-test-as-strict'}
]
});
// use jQuery or DOM elements
cy.get('.some-div-to-test-as-strict').then($el => {
cy.eyesCheckWindow({
strict: $el
});
})
content
This argument has been deprecated. It has been replaced with ignoreColors
ignoreColors
A single or an array of regions to match as Ignore Colors match level.
Example
cy.eyesCheckWindow({
ignoreColors: [
{top: 100, left: 0, width: 1000, height: 100},
{selector: '.some-div-to-test-as-ignore-colors'}
]
});
// use jQuery or DOM elements
cy.get('.some-div-to-test-as-ignore-colors').then($el => {
cy.eyesCheckWindow({
ignoreColors: $el
});
})
padded coded regions
Example
cy.get('some-region').then(el => {
cy.eyesCheckWindow({
// adds padding to a region by a css selector at the left and top of the region
layout: {region: 'layout-region', padding: {left:20, top: 10}}
// adds padding of 20px to all JQuery elements at the top, button, right and left of the region
ignore: {element: el, padding: 20},
// adds padding for a DOM element on the top of the region
content: {element: el[0], padding: {top:10}},
accessibility: {
region: {
accessibilityType: 'LargeText',
selector: 'accessibilityRegion',
},
padding: {left: 5},
},
floating:{
region: {
selector: 'floatingRegion',
},
maxDownOffset: 3,
maxLeftOffset: 20,
maxRightOffset: 30,
maxUpOffset: 3,
padding: {top: 20},
},
})
})
accessibility
A single or an array of regions to perform accessibility checks.
Example
cy.eyesCheckWindow({
accessibility: [
{accessibility**Type:** 'RegularText', selector: '.some-div'},
{accessibility**Type:** 'LargeText', selector: '//*[@id="main"]/h1', type: 'xpath'},
{accessibility**Type:** 'BoldText', top: 100, left: 0, width: 1000, height: 100},
]
});
// use jQuery or DOM elements
cy.get('.some-div').then($el => {
cy.eyesCheckWindow({
accessibility: [
{accessibility**Type:** 'RegularText', element: $el},
]
});
})
Values
Possible accessibilityType
values:
IgnoreContrast
RegularText
LargeText
BoldText
GraphicalObject
region in shadow DOM
When the target region is within shadow DOM, you need to specify the path to the region by passing an array of selectors. Each entry in the array should contain a json
with the following entries:
type:css
(only)selector
nodeType
The element that contains the shadowRoot
should be specified as nodeType:'shadow-root'
and the final target region should contain nodeType:'element'
Example
cy.eyesCheckWindow({
target: 'region',
selector: [{
type: 'css',
selector: 'ContainShadowRoot' ,
node**Type:** 'shadow-root'
},{
type: 'css',
selector: 'targetRegion',
node**Type:** 'element'
}]
});
scriptHooks
A set of scripts to be run by the browser during the rendering process. It is intended to be used as a means to alter the page's state and structure at the time of rendering.
Properties
beforeCaptureScreenshot
A script that runs after the page is loaded but before taking the screenshot.
Example
cy.eyesCheckWindow({
scriptHooks: {
beforeCaptureScreenshot: "document.body.style.backgroundColor = 'gold'"
}
})
layoutBreakpoints
An array of viewport widths to use in order to take different sized DOM captures.
It can also be specified as a boolean, at which point we will take DOM captures using the width configured in the device or browser.
Responsive pages display different content depending on the viewport's width, so this option can be used to instruct eyes
to take DOM captures using those widths, and test all responsive variations of your page.
This option can also be specified in eyesOpen
or globally in applitools.config.js
.
Example
cy.eyesCheckWindow({
layoutBreakpoints: [500, 1000]
});
You can include an optional reload
argument to reload the page when the page is resized to the breakpoints.
Example
cy.eyesCheckWindow({
layoutBreakpoints: {breakpoints: [500, 1000], reload: true}
});
sendDom
Flag that specifies whether a capture of DOM and CSS should be taken when rendering the screenshot. The default value is true
. This should only be modified to troubleshoot unexpected behavior, and not for normal production use.
Example
cy.eyesCheckWindow({sendDom: false})
variationGroupId
Sets the variation group ID. For more information, see Automated test maintenance of baseline variations.
Example
cy.eyesCheckWindow({variationGroupId: 'Login screen variation #1'})
waitBeforeCapture
Number of milliseconds to wait before capturing the snapshot. This will also apply between page resizes when using layoutBreakpoints
.
Example
cy.eyesOpen({
waitBeforeCapture: 1000
// ...
})
cy.eyesCheckWindow({
waitBeforeCapture: 1000
})
useDom
Example
cy.eyesCheckWindow({useDom: true})
enablePatterns
Example
cy.eyesCheckWindow({enablePatterns: true})
matchLevel
Sets the match level.
Example
cy.eyesCheckWindow({matchLevel: 'Layout'})
visualGridOptions
An object that specifies options to configure renderings on the Ultrafast grid.
Options
polyfillAdoptedStyleSheets
Creates a polyfill when the DOM contains
adoptedStyleSheets
(reference) for browsers that don't support it (It is currently supported only in Chrome).
true
- Those browsers will successfully include the css as inline style tags.
false
- The css will not be included.undefined
- An error will be thrown with a message stating that this feature is not supported in the browser.
Example
cy.eyesCheckWindow({
visualGridOptions: {
polyfillAdoptedStyleSheets: true
}
})
regionId
The regionId can be automatically set from the region that is passed or can be explicitly sent using the regionId
property.
Example
cy.get('.region.two:nth-child(2)').then(el => {
cy.eyesCheckWindow({
fully: false,
ignore: [
{type: 'css', selector: '.region.three:nth-child(3n)'},
{type: 'xpath', selector: '//div[@class="region one"][3]'},
{element: el, regionId: 'my-region-id'},
],
});
})
lazy loading
Sets 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 check.
Default values
scrollLength
: 300 pxwaitingTime
: 2000msmaxAmountToScroll
: 15,000 px
Example
// lazy loads with default values
cy.eyesCheckWindow({lazyLoad:{}})
// lazy loads with options specified
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
}})