Skip to main content

cy.eyesCheckWindows arguments

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 which window mode to use.

region

If set, the captured image will be the parts of the page.

Values:

fully​

If the target is window, and fully is true (default) then the snapshot will be of the entire page. If fully is false then the snapshot will be of the viewport.

Example​

// Capture viewport only
cy.eyesCheckWindow({
   target: 'window',
   fully: false,
});

region{#region}

If target is region, 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 is region, 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 is region, 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.

Example​

// lazy loads with sensible defaults
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
}})