Next.js visual regression testing that doesn't rot

Next.js is powerful, but that power introduces complexity for visual testing. Server rendering, client hydration, and streaming mean your page goes through multiple visual states before stabilising.

Most visual test failures in Next.js apps aren't real regressions—they're timing issues. Your tests captured different states of the same page.

The key to stable Next.js visual tests is eliminating variance. Control everything that could differ between test runs.

See reducing visual testing flakiness for detailed techniques.

React hydration is the process of attaching event handlers to server-rendered HTML. During hydration, the page may visually shift as client-side JavaScript takes over.

To capture stable screenshots after hydration:

// Wait for hydration to complete
await page.goto('/your-page');

// Wait for network idle (fetches complete)
await page.waitForLoadState('networkidle');

// Wait for a specific interactive element
await page.waitForSelector('[data-hydrated="true"]');

// Or wait for React to finish
await page.evaluate(() => {
  return new Promise((resolve) => {
    requestIdleCallback(resolve, { timeout: 5000 });
  });
});

Consider adding a data-hydrated attribute to your root component that flips to true after hydration. This gives your tests a reliable signal.

Next.js fetches data at multiple levels: Server Components, route handlers, client-side fetches. You need to mock all of them for consistent screenshots.

For Server Components and route handlers, use MSW or similar:

// In your Playwright test setup
import { test } from '@playwright/test';

test.beforeEach(async ({ page }) => {
  // Intercept API calls
  await page.route('**/api/**', async (route) => {
    const url = route.request().url();

    if (url.includes('/api/users')) {
      return route.fulfill({
        json: { users: [{ id: 1, name: 'Test User' }] },
      });
    }

    return route.continue();
  });
});

For time-dependent content, freeze the clock at a specific timestamp in your test fixtures.

You have two choices for where to capture screenshots:

• Page-level screenshots capture the full rendered page. They catch integration issues but are more prone to flakiness and produce large diffs when any component changes.
• Component-level screenshots capture individual components in isolation. They're more stable and diffs are focused, but they miss integration issues.

For Next.js, a hybrid approach works well: use Storybook or similar for component visual testing, and Playwright page screenshots for critical user flows only. See Playwright visual testing for flow-level strategies.

Next.js apps change frequently. You need an approval workflow that keeps up without becoming a rubber-stamp exercise.

• Keep PRs focused: Small, single-purpose PRs produce reviewable visual diffs. Monster PRs get approved without review.
• Link diffs to code: Make it easy to see which code change caused which visual change. PR comments with links help.
• Automate the happy path: If only baseline files changed (no functional code), consider auto-approving with notification.

See approval workflow patterns for detailed strategies.