Skip to main content
Visual Testing · Stack

Visual Testing for Next.js with Playwright

Visual testing for Next.js with Playwright compares screenshots of your rendered pages, including preview deployments, with approved baselines at the points your Playwright tests choose. The @wopee-io/wopee.pw package sends each screenshot to Wopee.io, and with the branch settings a pull request's preview deploy is compared with the baselines approved on main, so layout regressions are reviewed before they merge.

Why visual testing Next.js with Playwright is hard

Next.js gives every pull request a realistic environment, often a preview deployment with its own URL, which is ideal for visual checks and awkward for the usual tools. Playwright's toHaveScreenshot keeps baselines as files in the repository, per browser and OS, so comparing a preview against main means checking out main's images and keeping them in sync. Next.js rendering adds timing traps: next/font uses font-display: swap by default, so text can repaint after the first frame, next/image lazy-loads images below the fold, and App Router routes stream their content behind loading.tsx boundaries, so a screenshot taken at the first paint captures a loading state. Middleware, redirects, and locale routing change what a URL shows, and server components mean the same component can render differently with different data.

How Wopee.io adds visual checks to Playwright

Wopee.io fits the preview workflow. Point Playwright's baseURL at the preview URL your pipeline provides, set WOPEE_BRANCH_NAME to the pull request's branch and WOPEE_BASELINE_BRANCH_NAME to main, and every screenshot from the preview is compared with main's approved baselines until the branch has its own. In the test, wait for the content that replaces the loading.tsx fallback and make sure fonts and images have finished, then call trackFullPage or trackViewport. Use WOPEE_VIEWPORT and WOPEE_DEVICE labels when you run the same test on desktop and mobile projects, because labels are part of the baseline identity. Differences show up in Wopee Commander next to the baseline with a highlight overlay; approve an intended change, reject a regression, and merge the branch's baselines into main after the pull request lands. Nothing is written to the repository, and a difference fails the test only if you assert on the returned status. Plain React apps follow the same pattern (visual testing for React with Playwright), and agent-generated Next.js coverage is in AI testing for Next.js. Setup: Playwright guide.

How to get started

  1. 1
    Create a Wopee.io project with the test framework set to Playwright and store WOPEE_API_KEY and WOPEE_PROJECT_UUID as CI secrets.
  2. 2
    Install @wopee-io/wopee.pw, add '@wopee-io/wopee.pw/wopee-reporter' to the reporters, and read baseURL from the preview URL your pipeline provides.
  3. 3
    In CI, set WOPEE_BRANCH_NAME to the pull request branch and WOPEE_BASELINE_BRANCH_NAME to main.
  4. 4
    In each test, wait for streamed content, fonts, and lazy images before calling trackFullPage or trackViewport.
  5. 5
    Approve or reject differences in Commander, and merge the branch's baselines into main in More › Baselines after the pull request merges.

Example: a Playwright test with visual checks

tests/pricing.visual.spec.ts
import { test } from '@playwright/test';
import { Wopee } from '@wopee-io/wopee.pw';

// CI sets BASE_URL to the preview deploy, WOPEE_BRANCH_NAME to the PR branch
// and WOPEE_BASELINE_BRANCH_NAME=main.
test.use({ baseURL: process.env.BASE_URL ?? 'http://localhost:3000' });

const wopee = new Wopee();

test.beforeAll(async () => {
await wopee.startSuite(`Next.js preview ${process.env.GITHUB_RUN_NUMBER ?? 'local'}`);
});
test.beforeEach(async ({}, testInfo) => {
await wopee.startScenario(testInfo.title, testInfo);
});
test.afterEach(async () => {
await wopee.stopScenario();
});

test('Pricing page', async ({ page }) => {
await page.goto('/pricing');
// Wait for the streamed content behind loading.tsx, then fonts and images.
await page.getByRole('heading', { name: 'Pricing' }).waitFor();
await page.evaluate(async () => {
await Promise.all([
...[...document.fonts].map((font) => font.load()),
...[...document.images].map((img) => img.decode().catch(() => {})),
]);
});
await wopee.trackFullPage({ page, stepName: 'Pricing' });
});

From manual effort to AI-assisted testing

More automation. Less maintenance. Faster review.

Manual check of the preview

Preview deploys
Clicked through by a reviewer
Where baselines live
None
Fonts, images, streaming
Judged by eye
After merge
Nothing to update

Playwright toHaveScreenshot

Preview deploys
Compare against images on the branch
Where baselines live
PNG files in the repo, per browser and OS
Fonts, images, streaming
Waits written by hand
After merge
Commit updated images
Wopee.ioWopee.io
AI testing
Preview deploys
Compared with main via WOPEE_BASELINE_BRANCH_NAME
Where baselines live
Wopee.io, per branch and labels
Fonts, images, streaming
Wait, then track
After merge
Merge branch baselines 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

Yes. Wopee.io compares whatever page your Playwright test opens, so set baseURL to the preview URL. Set WOPEE_BRANCH_NAME to the branch and WOPEE_BASELINE_BRANCH_NAME to main so the preview is compared with main's baselines.

Web fonts, including those from next/font, can swap in after the first paint. Load every font face and decode images before the track call, as in the example, so the screenshot shows the final text.

No special setup, because Wopee.io compares the rendered page. Wait for the content that replaces loading.tsx fallbacks before tracking, so the baseline is the finished page and not a loading state.