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
- 1Create a Wopee.io project with the test framework set to Playwright and store WOPEE_API_KEY and WOPEE_PROJECT_UUID as CI secrets.
- 2Install @wopee-io/wopee.pw, add '@wopee-io/wopee.pw/wopee-reporter' to the reporters, and read baseURL from the preview URL your pipeline provides.
- 3In CI, set WOPEE_BRANCH_NAME to the pull request branch and WOPEE_BASELINE_BRANCH_NAME to main.
- 4In each test, wait for streamed content, fonts, and lazy images before calling trackFullPage or trackViewport.
- 5Approve 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
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
- 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.
Related
All AI testing guides →AI Testing for Next.js
AI testing for Next.js apps. Wopee.io generates and self-heals e2e and visual tests across the App Router, Server Components, and hydration boundaries.
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.
AI Visual Testing
AI visual testing tool from Wopee.io. AI diffing, classic comparison with ignore areas, and prompt-based image assertions to catch real UI regressions.