Skip to main content
Visual Testing · Stack

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

  1. 1
    Create 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.
  2. 2
    Install @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.
  3. 3
    Start a suite in beforeAll and a scenario per test in beforeEach, passing testInfo, and stop the scenario in afterEach.
  4. 4
    Track the full page or a component locator after real content has replaced Suspense fallbacks and skeletons.
  5. 5
    Run npx playwright test, approve the first screenshots in Commander, then review unresolved steps on each later run.

Example: a Playwright test with visual checks

tests/checkout.visual.spec.ts
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
Wopee.ioWopee.io
AI testing
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.