Catch Visual UI Bugs with SmartUI Visual Testing

Catch Layout, CSS, and Rendering Bugs across Browsers and Real Devices. Visual AI Filters Out Pixel Noise.

Try SmartUI free
Cypress TestingTutorial

Cypress Visual Regression Testing: Plugins vs SmartUI (2026)

Set up Cypress visual regression testing in 2026: compare cypress-visual-regression, the Pixsame plugin, SmartUI, Percy and Applitools, with setup code and CI steps.

Last Updated on:

This article is a part of our Content Hub. For more in-depth resources, check out our content hub on Cypress Tutorial.

Overview

Cypress does not include visual regression testing, so you add it with a plugin or a cloud service. Open-source plugins such as cypress-visual-regression compare screenshots locally in the browser Cypress runs and suit small suites. Cloud services such as TestMu AI SmartUI add cross-browser comparison, baseline management, ignore rules for dynamic content and a review workflow, using your existing Cypress tests with one snapshot call.

  • Local, Cypress 15+: cypress-visual-regression 6.x, with cy.compareSnapshot() and separate base and regression runs.
  • Local, Cypress 13+: @pixsame/cypress-plugin-visual-regression-diff, with cy.matchImage(), a See comparison view in the runner and component test setup. It replaced the deprecated FRSOURCE package in October 2026.
  • Avoid: cypress-plugin-snapshots, last released in August 2020 for Cypress 4.5.
  • Cloud, cross-browser: SmartUI (Cypress 10+), Percy and Applitools Eyes, each with its own snapshot command and review dashboard.

Does Cypress Have Built-In Visual Testing?

No. Cypress captures images with cy.screenshot(), but it has no command that compares a new screenshot with an approved one. Visual regression testing needs that comparison step: capture the page or an element, compare it with a baseline image, and flag the pixels or regions that changed.

You get the comparison step in one of two ways. A plugin runs it on your machine or CI runner and stores baselines as image files in your repository. A cloud service uploads each snapshot, renders or compares it across the browsers you configure, and gives reviewers a dashboard to approve or reject each change. The sections below cover both, starting with the plugins.

Cypress Visual Regression Plugins Compared

These are the three plugins most guides still mention. Versions, dates and Cypress requirements come from each package's npm registry entry, checked on November 6, 2026.

PluginLatest releaseCypress versionsCommandHow baselines work
cypress-visual-regression6.0.1, September 8, 202615 and latercy.compareSnapshot()A run in base mode writes baseline images; a run in regression mode compares against them and writes diff images on failure
@pixsame/cypress-plugin-visual-regression-diff (formerly @frsource)1.0.0, October 7, 202613 and latercy.matchImage()Compares with the image from a previous run; a failing test shows a See comparison button in the runner. Setup covers e2e and component tests
cypress-plugin-snapshots1.4.4, August 11, 2020Peer dependency ^4.5.0toMatchImageSnapshot()No release since 2020; not recommended for current Cypress

If you used the FRSOURCE package, the npm deprecation notice says the move is only a change of scope name, from @frsource to @pixsame, and the old package ships a migrate command that does it for you.

Set Up cypress-visual-regression

This walkthrough follows the plugin's README for version 6, which needs Cypress 15 or later. Version 6 reads its options from expose in cypress.config.js.

Step 1: Install the plugin.

npm install cypress-visual-regression

Step 2: Configure it in cypress.config.js. Set visualRegressionType to base to write baseline images, or regression to compare new screenshots with them.

const { defineConfig } = require('cypress')
const { configureVisualRegression } = require('cypress-visual-regression')

module.exports = defineConfig({
  e2e: {
    expose: {
      visualRegressionType: 'regression'
    },
    screenshotsFolder: './cypress/snapshots/actual',
    setupNodeEvents(on, config) {
      configureVisualRegression(on)
    }
  }
})

Step 3: Register the command in cypress/support/e2e.js.

const { addCompareSnapshotCommand } = require('cypress-visual-regression/dist/command')
addCompareSnapshotCommand()

Step 4: Add checkpoints to a test. The optional second argument is the error threshold: the share of pixels allowed to differ, where 0.01 means 1%.

describe('Home page', () => {
  it('matches the approved design', () => {
    cy.visit('/')
    cy.compareSnapshot('home-page')
    cy.get('header').compareSnapshot('header', 0.01)
  })
})

Step 5: Run once in base mode to create the baselines, then in regression mode on every later run. The plugin writes base and diff images under cypress/snapshots by default.

CYPRESS_visualRegressionType=base npx cypress run
CYPRESS_visualRegressionType=regression npx cypress run

To accept an intended change, regenerate that baseline in base mode, or run regression mode with visualRegressionUpdateSnapshots set to true so mismatched baselines are replaced. Commit the updated images with the code change that caused them, so reviewers see both together.

Plugins vs Cloud Visual Testing Services

Local plugins are free and quick to add, and they suit a small suite checked in one browser. They get harder to run once several people approve changes, the same page must look right in several browsers, or dynamic content keeps failing comparisons. That is where a cloud visual testing tool earns its cost.

Local pluginsTestMu AI SmartUIPercyApplitools Eyes
Cypress packagecypress-visual-regression or @pixsame/cypress-plugin-visual-regression-diff@lambdatest/smartui-cli and @lambdatest/cypress-driver@percy/cli and @percy/cypress@applitools/eyes-cypress
Snapshot callcy.compareSnapshot() or cy.matchImage()cy.smartuiSnapshot()cy.percySnapshot()cy.eyesOpen(), cy.eyesCheckWindow(), cy.eyesClose()
Where baselines liveImage files in your repositoryA SmartUI project, with named approversA Percy projectThe Applitools Eyes dashboard
Browsers per snapshotThe browser Cypress runs inDefault config: Chrome, Firefox, Safari and Edge, three web viewports, iPhone 14 and Galaxy S24Set in Percy; see Percy docsSet in Eyes; see Applitools docs
Dynamic contentThresholds, or snapshot a stable elementignoreDOM and selectDOM by id, class, XPath or CSS selectorpercyCSS to hide or freeze elements before captureConfigured per check in Eyes
Run commandnpx cypress runnpx smartui --config .smartui.json exec -- npx cypress runpercy exec -- cypress runnpx cypress run, with APPLITOOLS_API_KEY set
PricingFree, open sourceSee current TestMu AI pricingSee current Percy pricingSee current Applitools pricing

Commands come from each vendor's own documentation, checked on November 6, 2026. For a wider list, see our roundup of visual testing tools.

Cypress Visual Regression Testing With SmartUI

The steps below follow the SmartUI Cypress SDK docs. The SDK supports Cypress 10.0.0 and later, and SmartUI CLI v4.x.x and later needs Node.js v20.3 or above.

Step 1: Create a project in SmartUI and choose CLI as the platform. Add a name, approvers and optional tags, then copy the project token it shows.

Step 2: Install the SmartUI CLI and the Cypress driver.

npm install @lambdatest/smartui-cli @lambdatest/cypress-driver cypress@v13

Step 3: Import the driver in cypress/support/e2e.js.

import '@lambdatest/cypress-driver'

Step 4: Add a log task to setupNodeEvents in cypress.config.js.

on('task', {
  log(message) {
    console.log(message);
    return null;
  },
});

Step 5: Set the project token as an environment variable (use set on Windows CMD, or $env: in PowerShell), then create the SmartUI config.

export PROJECT_TOKEN="<your project token>"
npx smartui config:create .smartui.json

The generated config lists Chrome, Firefox, Safari and Edge, web viewports of 1920, 1366 and 1028 pixels, and the iPhone 14 and Galaxy S24 as mobile devices. Remove what you don't need before the first run.

Step 6: Add a snapshot at each visual checkpoint.

describe('Home page', () => {
  beforeEach(() => {
    cy.visit('/')
  })

  it('SmartUI snapshot', () => {
    cy.smartuiSnapshot('Home page')
  })
})

Step 7: Run your tests through the SmartUI CLI.

npx smartui --config .smartui.json exec -- npx cypress run --spec cypress/e2e/smartuiSDKLocal.cy.js --browser chrome --headed

Step 8: Open the SmartUI project to compare the build with its baseline, then approve intended changes and reject regressions.

For dynamic content, pass an options object as the second argument. ignoreDOM leaves the matching elements out of the comparison, selectDOM compares only the matching elements, and element captures a single element. Each accepts ids, classes, XPaths or CSS selectors.

cy.smartuiSnapshot('Home page', {
  ignoreDOM: { id: ['live-clock'], class: ['ad-slot'] }
})

A working project is in the smartui-cypress-sdk-sample repository. To run the same snapshots in parallel on the cloud, see SmartUI with Cypress on HyperExecute, and for the product overview, SmartUI for Cypress.

Austin Siewert

Austin Siewert

Co-Founder, Steadfast Systems

Discovered @TestMu AI yesterday. Best browser testing tool I've found for my use case. Great pricing model for the limited testing I do 👏

3M+ Devs and QAs rely on TestMu AI

Deliver immersive digital experiences with Next-Generation Mobile Apps and Cross Browser Testing Cloud

Run Visual Tests in CI

With a local plugin, generate baselines and run comparisons in the same Docker image, such as an official Cypress image pinned to one tag. Fonts and anti-aliasing differ between macOS, Windows and Linux, so a baseline made on a laptop will fail on a Linux runner even when nothing changed.

With SmartUI, rendering and comparison happen in SmartUI, so the runner only needs Node.js and your token. Store PROJECT_TOKEN as a repository secret and wrap the Cypress run with the SmartUI CLI:

name: visual-tests
on: [pull_request]

jobs:
  smartui:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx smartui --config .smartui.json exec -- npx cypress run
        env:
          PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}

Keep baseline updates deliberate in either setup. Approve or regenerate a baseline in the same pull request as the change that caused it, so a reviewer sees the code and the new screenshot together.

Common Pitfalls and How to Avoid Them

  • Snapshots before the page settles: assert on a loaded state first, for example cy.get('body').should('have.class', 'loaded'), then take the snapshot.
  • Animations and transitions: disable them in a test-only stylesheet, or use percyCSS in Percy, so each capture shows the final frame.
  • Dynamic content: timestamps, ads, avatars and live counters change on every run. Exclude them with ignoreDOM in SmartUI, or snapshot a stable element with a local plugin.
  • Viewport drift: set cy.viewport() explicitly in each visual test, so a change in the default size does not invalidate every baseline.
  • Different machines, different pixels: generate and compare local-plugin baselines on the same OS and image, as in the CI section above.
  • A zero threshold on full pages: an error threshold of 0 fails on a single anti-aliased pixel. Allow a small share, such as 0.01 (1% of pixels), and tighten it for elements that must match exactly.

Final Thoughts

Start with a plugin if your suite is small and runs in one browser: cypress-visual-regression on Cypress 15 or later, or the Pixsame plugin on Cypress 13 or later. Move to a cloud service when baselines need more than one reviewer, pages must match across browsers and devices, or dynamic content keeps breaking comparisons. SmartUI keeps your existing Cypress tests and adds one snapshot call per checkpoint.

For more Cypress practice, see the top Cypress interview questions.

Did your last release break the UI? TestMu AI's SmartUI catches visual regressions by comparing every screen to its baseline.

To run your first test, start free, or
for a full walkthrough of the product.

Author

...

Enrique

Blogs: 11

  • Twitter
  • Linkedin

Enrique DeCoss, Senior Quality Assurance Manager at FICO is an industry leader in quality strategy with 16+ of experience implementing automation tools. Enrique has a strong background in Testing Tools, API testing strategies, performance testing, Linux OS and testing techniques. Enrique loves to share his in-depth knowledge in competencies including, Selenium, JavaScript, Python, ML testing tools, cloud computing, agile methodologies, and people Management.

Frequently asked questions

Did you find this page helpful?

More Related Blogs

TestMu AI forEnterprise

Get access to solutions built on Enterprise
grade security, privacy, & compliance

  • Advanced access controls
  • Advanced data retention rules
  • Advanced Local Testing
  • Premium Support options
  • Early access to beta features
  • Private Slack Channel
  • Unlimited Manual Accessibility DevTools Tests