Cypress SDK

Last modified on May 18, 2023.

For VisualTest’s page on npm, go here.


  • Cypress v7.4.0+ (v10.10.0 recommended)


  1. Install:


    npm install @smartbear/visualtest-cypress@latest
    npx visualtest-setup

    This will:

    • Create: visualTest.config.js file

    • Add: require('@smartbear/visualtest-cypress')(module); at the bottom of cypress.config.js

    • Add: import '@smartbear/visualtest-cypress/commands' at the bottom of cypress/support/e2e.js

  2. Replace 'PROJECT_TOKEN' with your project token in your newly created visualTest.config.js file:


    module.exports = { projectToken: 'PROJECT_TOKEN' }
  3. At each point within your functional test that you want to capture an image (fullpage, viewport or element) for regression testing, call the capture method:


    // Fullpage screenshot
    cy.sbvtCapture('Home Page');

    // Viewport screenshot
    cy.sbvtCapture('Home Page Viewport', { capture: 'viewport' });

    // Element screenshot
  4. VisualTest returns a console log output, providing your team with a link to accept and review any found image differences in your GUI. See Getting Started for more information:

    Console Log Output

    Click the image to enlarge it.

Note: Manual set-up is also possible. See below.

This runs regression tests against Fullpage Home Capture in that project:

cy.sbvtCapture('Fullpage Home Capture')

You can also run tests against particular elements. This will run regression tests against the Navbar:

cy.get('.container').eq(0).sbvtCapture('Capture of the homepage Navbar')

The below runs fullpage regression tests for lazy-loaded websites. Note that the value (1000) is the number of milliseconds to wait between scrolls:


cy.sbvtCapture('lazyloaded capture', {
   lazyload: 1000, // number is milliseconds between scrolls

To pass in other arguments, the syntax would be the same as cy.screenshot:


describe('Starting Example Spec', () => {
   beforeEach('visit cypress example website', () => {
   it('should check cypress example page', () => {
      cy.sbvtCapture('Cypress Example Full');
   it('should check an element on the page', () => {
   it('should check a viewport screenshot', () => {
      cy.sbvtCapture('Cypress Example Viewport', {
         capture: 'viewport',
   it('should clip homepage viewport', () => {
      cy.sbvtCapture('Clipping the homepage viewport', {
            capture: 'viewport',
            overwrite: true,
            clip: { x: 100, y: 100, width: 1000, height: 1000 },
Note: Callback arguments are not allowed, e.g. onBeforeScreenshot and onAfterScreenshot

Running the plug-in:

  • npx cypress run is recommended
  • 'interactive mode' (npx cypress open) works, but each test can only be run once without closing and relaunching the Cypress application.

For code examples that handle dynamic, moving content, see Screenshot Consistency.

On versions 10+

  • Add: require('@smartbear/visualtest-cypress')(module); at the bottom of cypress.config.js.
  • Add: import '@smartbear/visualtest-cypress/commands' at the bottom of cypress/support/e2e.js.

On versions 10-

  • Add: require('@smartbear/visualtest-cypress')(module); at the bottom of cypress/plugins/index.js.
  • Add: import '@smartbear/visualtest-cypress/commands' at the bottom of cypress/support/index.js.

Create visualTest.config.js in the main test folder.


Keep VisualTest’s performance optimized, by periodically refreshing your version: npm install @smartbear/visualtest-cypress@latest

See Also

Technical Support
Screenshot Consistency

Highlight search results