Visual Testing for React with Playwright
Visual testing for React with Playwright compares screenshots of your rendered React app with approved baselines at the points your Playwright tests choose, so a broken component library update, a CSS-in-JS change, or a misaligned grid is caught even when the test still passes. The @wopee-io/wopee.pw package sends each screenshot to Wopee.io, which compares it with the baseline for your branch and lists every difference in Wopee Commander for approval.
Why visual testing React with Playwright is hard
React apps change appearance more often than behaviour. A component library upgrade, a theme token, or a refactor of a styled component can shift spacing across every screen without breaking a single functional assertion. Storybook-based visual testing covers components in isolation, but not the composed page with real data, routing, and layout. Page screenshots bring their own instability: React.lazy and Suspense show skeletons and spinners until data arrives, images load late, and CSS-in-JS libraries generate hashed class names such as css-1a2b3c that make element selectors brittle. Playwright's built-in toHaveScreenshot handles the comparison, but its baselines are PNG files in the repository, one per browser and operating system, so a design refresh turns into a pull request of binary images that nobody reviews properly.
How Wopee.io adds visual checks to Playwright
With Wopee.io, the React tests stay in Playwright and the visual review moves to a place built for it. You add the Wopee.io reporter to playwright.config.ts, start a suite and scenario in the hooks, and call trackFullPage, trackViewport, or trackElement after the content you care about has rendered, for example after getByRole('table') is visible, so Suspense fallbacks never become baselines. trackElement takes any Playwright locator, so role-based locators such as getByRole('navigation') capture a component without depending on hashed class names. Baselines are kept per branch and per environment label (browser, OS, viewport, device), and the review happens in Wopee Commander: approve an intended redesign in bulk, reject a regression, and draw ignore areas over regions that change on purpose. A difference leaves the test green unless you assert on the returned status. If you would rather not write the tests at all, the Wopee.io agent generates Playwright tests from your running React app, covered in AI testing for React; Next.js teams can follow visual testing for Next.js with Playwright. Full setup is in the Playwright guide.
How to get started
- 1Create a Wopee.io project with the test framework set to Playwright and put WOPEE_API_URL, WOPEE_PROJECT_UUID, and WOPEE_API_KEY in a .env file next to playwright.config.ts.
- 2Install @wopee-io/wopee.pw and add '@wopee-io/wopee.pw/wopee-reporter' to the reporters, with baseURL pointing at your dev server (for Vite, http://localhost:5173) or a preview deploy.
- 3Start a suite in beforeAll and a scenario per test in beforeEach, passing testInfo, and stop the scenario in afterEach.
- 4Track the full page or a component locator after real content has replaced Suspense fallbacks and skeletons.
- 5Run npx playwright test, approve the first screenshots in Commander, then review unresolved steps on each later run.
Example: a Playwright test with visual checks
import { test, expect } from '@playwright/test';
import { Wopee } from '@wopee-io/wopee.pw';
const wopee = new Wopee();
test.beforeAll(async () => {
await wopee.startSuite(`React visual ${new Date().toISOString().slice(0, 16)}`);
});
test.beforeEach(async ({}, testInfo) => {
await wopee.startScenario(testInfo.title, testInfo);
});
test.afterEach(async () => {
await wopee.stopScenario();
});
test('Cart and checkout', async ({ page }) => {
await page.goto('/cart');
// Wait for real data, not the Suspense skeleton.
await page.getByRole('table', { name: 'Cart items' }).waitFor();
await wopee.trackFullPage({ page, stepName: 'Cart' });
await page.getByRole('button', { name: 'Checkout' }).click();
const form = page.getByRole('form', { name: 'Shipping address' });
await form.waitFor();
const result = await wopee.trackElement({ locator: form, stepName: 'Shipping form' });
expect(result?.status).not.toBe('unresolved');
});
From manual effort to AI-assisted testing
More automation. Less maintenance. Faster review.
Storybook visual snapshots
- Scope
- Isolated components
- Where baselines live
- Snapshot service or repo
- Hashed CSS-in-JS classes
- Not relevant, component level
- Review
- Per story
Playwright toHaveScreenshot
- Scope
- Composed pages
- Where baselines live
- PNG files in the repo, per browser and OS
- Hashed CSS-in-JS classes
- Use role locators yourself
- Review
- HTML report per run
- Scope
- Composed pages and elements
- Where baselines live
- Wopee.io, per branch and labels
- Hashed CSS-in-JS classes
- trackElement takes any locator, e.g. getByRole
- Review
- Approve or reject per step in Commander
Add visual checks to your Playwright tests
Keep your tests, add a few track calls, and review every visual change in one place.
Frequently asked questions
They cover different layers. Storybook snapshots check components in isolation; Wopee.io checks the composed pages your Playwright tests reach, with real routing, data, and layout. Many teams keep both.
Wait for the content that replaces the Suspense fallback before the track call, for example await page.getByRole('table').waitFor(). The same applies to late images and web fonts.
Yes. Each track call returns a status; assert that it is not unresolved, as in the example. Without that check the test passes and the step waits for review in Wopee Commander.
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 Next.js with Playwright
Visual testing for Next.js with Playwright: check preview deploys against main's baselines with Wopee.io and review every visual change before it merges.
Visual Testing for React with Cypress
Visual testing for React with Cypress: add cy.wopeeTrack to your specs, ignore live regions by selector, and review every React UI change in Wopee.io.