Visual Testing for React with Cypress
Visual testing for React with Cypress adds screenshot comparisons to the Cypress end-to-end specs that many React teams already rely on. Cypress does not compare screenshots itself; the @wopee-io/wopee.cy plugin adds cy.wopeeTrack(), which waits for fonts and images, captures the page or a single element, and compares it with the approved baseline in Wopee.io, where every difference is approved or rejected.
Why visual testing React with Cypress is hard
React teams often have strong Cypress coverage of behaviour and almost none of appearance. A shared component change, a new design token, or a CSS refactor can break the layout of pages the specs click through every day, and Cypress reports green because the buttons are still clickable. Adding visual checks usually means choosing a community snapshot plugin, storing baseline images in the repository, and fighting noise from content that changes on every run: relative timestamps, avatars, prices, notification counts, and charts. Lazy-loaded images and late web fonts add more flakiness, and when a test fails on the first difference, an intended redesign blocks every pull request until someone updates dozens of image files.
How Wopee.io adds visual checks to Cypress
The Wopee.io plugin gives a Cypress suite a visual layer without changing how the specs work. Register addWopeePlugin in cypress.config.js and addWopeeCommands() in the support file, then start a suite and scenario in the hooks. cy.wopeeTrack({ stepName }) waits for web fonts and images before the screenshot (from plugin 4.13.4), and chaining it after cy.get() captures one component, such as a product card or a navigation bar. ignoreAreas takes CSS selectors or pixel rectangles for live regions, for example [data-test=relative-time], set once in the config for every step or per call, and a selector that matches nothing on a page is skipped instead of failing. A response callback receives each step's status if you want to log or branch on it, and enableSoftAssert: false turns an unresolved step into a failed test. Baselines and the review live in Wopee Commander per branch, so a redesign is approved once instead of rewritten in the repo. Vue teams on Cypress can follow visual testing for Vue with Cypress, and agent-generated coverage for React is in AI testing for React. All options: Cypress plugin reference.
How to get started
- 1Create a Wopee.io project with the test framework set to Cypress and copy WOPEE_PROJECT_UUID and a new WOPEE_API_KEY into .env.
- 2Install @wopee-io/wopee.cy and dotenv, call addWopeePlugin(on, config) in setupNodeEvents, and map the key and project UUID into env.wopee.
- 3Add addWopeeCommands() to cypress/support/e2e.js and set ignoreAreas in env.wopee for live regions every page shares.
- 4In each spec, start the suite and scenario in the hooks and call cy.wopeeTrack for pages, or chain it after cy.get for single components.
- 5Run npx cypress run, approve the first screenshots in Commander, and decide whether differences should fail the run with enableSoftAssert.
Example: a Cypress test with visual checks
/// <reference types="cypress" />
/// <reference types="@wopee-io/wopee.cy" />
const suiteName = `React catalog ${new Date().toISOString().slice(0, 16)}`;
describe(suiteName, () => {
before(() => cy.wopeeStartSuite(suiteName));
beforeEach(() => cy.wopeeStartScenario('Catalog: grid and product card'));
afterEach(() => cy.wopeeStopScenario());
it('catalog grid and product card', () => {
cy.visit('/catalog');
cy.get('[data-test=product-grid]').should('be.visible');
cy.wopeeTrack(
{ stepName: 'Catalog grid', ignoreAreas: ['[data-test=relative-time]'] },
(result) => cy.log(`${result.stepName}: ${result.status}`),
);
cy.get('[data-test=product-card]').first().wopeeTrack({ stepName: 'Product card' });
});
});
From manual effort to AI-assisted testing
More automation. Less maintenance. Faster review.
Manual check before release
- Visual comparison
- By eye
- Live regions (times, counts)
- Ignored by eye
- Single components
- If someone looks
- Intended redesigns
- No action needed, no protection
Community snapshot plugins
- Visual comparison
- Local image diff, baselines in repo
- Live regions (times, counts)
- Masking per plugin
- Single components
- Screenshot an element
- Intended redesigns
- Update image files in a PR
- Visual comparison
- Baselines in Wopee.io per branch
- Live regions (times, counts)
- ignoreAreas by selector or rectangle
- Single components
- Chain cy.wopeeTrack after cy.get
- Intended redesigns
- Approve in bulk in Commander
Add visual checks to your Cypress tests
Keep your tests, add a few track calls, and review every visual change in one place.
Frequently asked questions
No. The plugin reads only the wopee object in the env section of the Cypress config, so map process.env.WOPEE_API_KEY and process.env.WOPEE_PROJECT_UUID into it after loading .env.
Add their CSS selectors to ignoreAreas, either in env.wopee for every step or in a single cy.wopeeTrack call. Ignore areas drawn in the Commander comparison view apply on top.
The guides cover end-to-end specs, where cy.wopeeTrack captures the rendered app. For component-level snapshots of React components in isolation, keep a tool built for that, and use Wopee.io for the composed pages.
Related
All AI testing guides →AI Testing for React
AI-powered testing for React apps. Wopee.io generates and self-heals end-to-end and visual tests for component-driven UIs, no brittle selectors.
Visual Testing for React with Playwright
Visual testing for React with Playwright: add Wopee.io track calls to your Playwright tests and review every visual change per branch, outside your repo.
Visual Testing for Vue with Cypress
Visual testing for Vue with Cypress: add cy.wopeeTrack to the Cypress specs create-vue set up, wait out transitions, and review UI changes in Wopee.io.