Article

April 22, 2026

How to Test Next.js Apps End-to-End in 2026: The Complete Guide

Next.js is where more and more production web apps live, and testing them end-to-end has become its own discipline. The App Router, Server Components, Server Actions, middleware, and Vercel's edge runtime each change how a test needs to be set up and where it can fail. Playwright handles most of this well if you configure it carefully — and the AI tooling around it has closed a lot of the "we don't have time to write tests" gap.

This guide walks through an end-to-end testing setup that actually works for a modern Next.js app in 2026: the Playwright config that plays nicely with the App Router, how to test Server Actions without tripping over hydration, how to handle auth and middleware, how to keep the suite fast in CI, and where Claude Code and AI-generated tests fit in. It ends with what breaks as the app grows and what to do about it.

Why Next.js E2E testing is different

Every E2E stack has to deal with the same basic problem: launch a browser, drive it against a running app, assert against what the user sees. Next.js complicates each of those steps.

Hybrid rendering. A single page can mix Server Components, Client Components, and cached fetches. The first paint is often static HTML, the next frame hydrates, and streaming responses can arrive out of order. Tests that assert too early on a Server Component's markup can pass before the client has taken over.
Server Actions. Form submissions and mutations run on the server but are triggered from the client. They return revalidated data. Asserting on the UI after a Server Action requires waiting for the revalidate pass, not just the network response.
Middleware and edge. Auth redirects, A/B splits, locale routing, and feature flags often run in middleware. Tests that hit your app in a way middleware hasn't seen before — missing cookies, unexpected headers, a geo flag — can fail for reasons that have nothing to do with the feature you're testing.
Caching. fetch calls are cached by default. Route segment config can pin a page as static, dynamic, or revalidated on an interval. A test that passes once and fails next run is often hitting a cached response that no longer matches the assertion.

Most Next.js testing failures trace back to one of those four. Your setup has to acknowledge them up front.

Setting up Playwright for a Next.js app

Install

Inside your Next.js project:

npm

npm

npm

Pick TypeScript, put tests in tests/e2e, and let it add a GitHub Actions workflow. You'll edit both.

playwright.config.ts

The single most important part of the config is the webServer block. Playwright can start your Next.js dev or production build for each test run so you don't have to keep a server running manually.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
  webServer: {
    command: 'npm run build && npm run start',
    url: 'http://localhost:3000',
    timeout: 180_000,
    reuseExistingServer: !process.env.CI,
  },
});

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
  webServer: {
    command: 'npm run build && npm run start',
    url: 'http://localhost:3000',
    timeout: 180_000,
    reuseExistingServer: !process.env.CI,
  },
});

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  reporter: [['html'], ['list']],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
  webServer: {
    command: 'npm run build && npm run start',
    url: 'http://localhost:3000',
    timeout: 180_000,
    reuseExistingServer: !process.env.CI,
  },
});

Prefer next build && next start over next dev for anything more than a smoke test. Dev mode has different caching behavior, slower compilation, and a different middleware code path. Tests that only pass against next dev are tests that might not pass in production.

A test-safe environment

Add a .env.test and load it in playwright.config.ts with dotenv/config. Point it at a dedicated test database or a seeded local one. Don't share the dev database — you will, eventually, wipe it by accident.

DATABASE_URL=postgres://test@localhost:5432/app_test
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET

DATABASE_URL=postgres://test@localhost:5432/app_test
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET

DATABASE_URL=postgres://test@localhost:5432/app_test
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET

Testing App Router pages and Server Components

Server Components render on the server and ship HTML. Client Components hydrate that HTML and attach event handlers. Tests that only check the server-rendered markup miss bugs that live in hydration; tests that only run after interaction miss bugs in the initial render. Cover both.

import { test, expect } from '@playwright/test';

test('product page renders server content and hydrates filters', async ({ page }) => {
  await page.goto('/products/abc-123');

  // Server-rendered content: available before hydration
  await expect(page.getByRole('heading', { name: /Acme Widget/i })).toBeVisible();
  await expect(page.getByText(/in stock/i)).toBeVisible();

  // Client-rendered control: only works after hydration
  await page.getByRole('button', { name: /add to cart/i }).click();
  await expect(page.getByRole('status')).toHaveText(/added to cart/i);
});

import { test, expect } from '@playwright/test';

test('product page renders server content and hydrates filters', async ({ page }) => {
  await page.goto('/products/abc-123');

  // Server-rendered content: available before hydration
  await expect(page.getByRole('heading', { name: /Acme Widget/i })).toBeVisible();
  await expect(page.getByText(/in stock/i)).toBeVisible();

  // Client-rendered control: only works after hydration
  await page.getByRole('button', { name: /add to cart/i }).click();
  await expect(page.getByRole('status')).toHaveText(/added to cart/i);
});

import { test, expect } from '@playwright/test';

test('product page renders server content and hydrates filters', async ({ page }) => {
  await page.goto('/products/abc-123');

  // Server-rendered content: available before hydration
  await expect(page.getByRole('heading', { name: /Acme Widget/i })).toBeVisible();
  await expect(page.getByText(/in stock/i)).toBeVisible();

  // Client-rendered control: only works after hydration
  await page.getByRole('button', { name: /add to cart/i }).click();
  await expect(page.getByRole('status')).toHaveText(/added to cart/i);
});

A good pattern: use getByRole and getByText for the server-rendered assertions, and only reach for click/keypress interactions after you've confirmed something that requires hydration is present. That gives you an implicit hydration checkpoint without a brittle waitFor.

Streaming and Suspense boundaries

If a route uses loading.tsx or a Suspense boundary, your first assertion may land on the skeleton, not the final content. Assert on the final state explicitly:

await page.goto('/dashboard');
await expect(page.getByTestId('dashboard-skeleton')).toBeHidden();
await expect(page.getByRole('heading', { name: /Your accounts/ })).toBeVisible();

await page.goto('/dashboard');
await expect(page.getByTestId('dashboard-skeleton')).toBeHidden();
await expect(page.getByRole('heading', { name: /Your accounts/ })).toBeVisible();

await page.goto('/dashboard');
await expect(page.getByTestId('dashboard-skeleton')).toBeHidden();
await expect(page.getByRole('heading', { name: /Your accounts/ })).toBeVisible();

Testing Server Actions

Server Actions are the most common source of flakiness in Next.js E2E suites. The client fires the action, the server mutates state, revalidatePath or revalidateTag runs, and the UI updates on the next render. A test that clicks submit and immediately asserts can beat the revalidation.

test('creating a todo appears in the list', async ({ page }) => {
  await page.goto('/todos');

  await page.getByLabel('New todo').fill('Ship the release');
  await page.getByRole('button', { name: 'Add' }).click();

  // Wait for the item specifically, not a generic timeout
  await expect(page.getByRole('listitem', { name: 'Ship the release' })).toBeVisible();
});

test('creating a todo appears in the list', async ({ page }) => {
  await page.goto('/todos');

  await page.getByLabel('New todo').fill('Ship the release');
  await page.getByRole('button', { name: 'Add' }).click();

  // Wait for the item specifically, not a generic timeout
  await expect(page.getByRole('listitem', { name: 'Ship the release' })).toBeVisible();
});

test('creating a todo appears in the list', async ({ page }) => {
  await page.goto('/todos');

  await page.getByLabel('New todo').fill('Ship the release');
  await page.getByRole('button', { name: 'Add' }).click();

  // Wait for the item specifically, not a generic timeout
  await expect(page.getByRole('listitem', { name: 'Ship the release' })).toBeVisible();
});

A few rules that will save you hours:

Assert on the outcome, not the action. Never waitForResponse on the Server Action RSC payload and call it done — the response can arrive before the revalidation renders.
Use specific locators. getByRole('listitem', { name: 'Ship the release' }) is harder to fool than getByText('Ship the release'), which can match unrelated elements.
Don't mock Server Actions in E2E. If you need to mock, you're in integration-test territory. The whole point of an E2E test is that the Action really runs.

Optimistic updates

If the UI uses useOptimistic, assert twice — once on the optimistic state, once on the confirmed state — so you catch a regression where the optimistic UI is right but the confirmed UI never arrives:

await page.getByRole('button', { name: 'Like' }).click();
await expect(page.getByTestId('like-count')).toHaveText('42'); // optimistic
await expect(page.getByTestId('like-count')).toHaveText('42', { timeout: 5000 }); // confirmed

await page.getByRole('button', { name: 'Like' }).click();
await expect(page.getByTestId('like-count')).toHaveText('42'); // optimistic
await expect(page.getByTestId('like-count')).toHaveText('42', { timeout: 5000 }); // confirmed

await page.getByRole('button', { name: 'Like' }).click();
await expect(page.getByTestId('like-count')).toHaveText('42'); // optimistic
await expect(page.getByTestId('like-count')).toHaveText('42', { timeout: 5000 }); // confirmed

Auth, middleware, and cookies

The right pattern is to sign in once per worker using Playwright's storage state, not once per test.

// tests/e2e/auth.setup.ts
import { test as setup } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/sign-in');
  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.waitForURL('/dashboard');
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
});

// tests/e2e/auth.setup.ts
import { test as setup } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/sign-in');
  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.waitForURL('/dashboard');
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
});

// tests/e2e/auth.setup.ts
import { test as setup } from '@playwright/test';

setup('authenticate', async ({ page }) => {
  await page.goto('/sign-in');
  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();
  await page.waitForURL('/dashboard');
  await page.context().storageState({ path: 'playwright/.auth/user.json' });
});

Wire it into the project config:

projects: [
  { name: 'setup', testMatch: /auth\.setup\.ts/ },
  {
    name: 'chromium',
    dependencies: ['setup'],
    use: {
      ...devices['Desktop Chrome'],
      storageState: 'playwright/.auth/user.json',
    },
  },
],

projects: [
  { name: 'setup', testMatch: /auth\.setup\.ts/ },
  {
    name: 'chromium',
    dependencies: ['setup'],
    use: {
      ...devices['Desktop Chrome'],
      storageState: 'playwright/.auth/user.json',
    },
  },
],

projects: [
  { name: 'setup', testMatch: /auth\.setup\.ts/ },
  {
    name: 'chromium',
    dependencies: ['setup'],
    use: {
      ...devices['Desktop Chrome'],
      storageState: 'playwright/.auth/user.json',
    },
  },
],

For middleware-driven redirects (auth guards, locale routing), write a test that hits the protected route with no cookies and confirms the redirect. It takes three lines and catches a disproportionate number of regressions.

test('redirects unauthenticated users to sign-in', async ({ browser }) => {
  const context = await browser.newContext(); // no storageState
  const page = await context.newPage();
  await page.goto('/dashboard');
  await expect(page).toHaveURL(/\/sign-in\?callbackUrl=/);
});

test('redirects unauthenticated users to sign-in', async ({ browser }) => {
  const context = await browser.newContext(); // no storageState
  const page = await context.newPage();
  await page.goto('/dashboard');
  await expect(page).toHaveURL(/\/sign-in\?callbackUrl=/);
});

test('redirects unauthenticated users to sign-in', async ({ browser }) => {
  const context = await browser.newContext(); // no storageState
  const page = await context.newPage();
  await page.goto('/dashboard');
  await expect(page).toHaveURL(/\/sign-in\?callbackUrl=/);
});

Caching and revalidation

If your route segments use revalidate or tagged caches, your tests can see stale data across runs. Two patterns that help:

Force a fresh fetch in test environments. Gate fetch(..., { next: { revalidate: 0 } }) or cache: 'no-store' behind process.env.NODE_ENV === 'test'. Keep production caching intact.
Trigger revalidation explicitly. Expose a test-only route that calls revalidateTag for a known tag, guarded by a shared secret. Tests can hit it between scenarios instead of waiting out a TTL.

Running the suite in CI

A default GitHub Actions job is the right starting point. The places most teams optimize next:

Cache the build. .next/cache keyed on the lockfile and source hash cuts 1-3 minutes off every run.
Shard on CI. --shard=1/4 splits specs across four parallel jobs. Works well once the suite has more than ~10 minutes of serial runtime.
Upload traces, not screenshots. trace: 'on-first-retry' plus retries: 2 in CI gives you a complete Playwright trace for any flake. The HTML report is worth the storage.
Run against a real preview. For high-value flows, run a smoke subset against your deployed Vercel Preview URL. This catches middleware and edge behaviors that don't show up against next start.

Where AI fits in 2026

The main shift in the last year is that you no longer need to write every E2E spec by hand. Two workflows are mature enough to use day-to-day.

Claude Code + Playwright MCP

With the Playwright MCP server, Claude Code can navigate your running Next.js app, observe real selectors and state transitions, and write spec files from what it actually saw instead of what it guessed. The output uses getByRole-style locators by default, which are far more stable against a UI refactor than class-based selectors.

Where this shines for Next.js:

Onboarding flows that span several pages — Claude can walk the flow once and turn it into a spec.
Forms backed by Server Actions — the generated spec picks up on the post-submit state, not just the submit click.
Auth flows with middleware redirects — observing real redirects beats guessing at them.

Playwright Agents

Playwright 1.56+ ships a Planner, Generator, and Healer agent trio that runs under Claude Code. The Planner explores the app and writes a Markdown plan; the Generator turns it into specs; the Healer attempts to fix failing tests. It works well on shallow flows and visual regressions. It does not replace human review on anything that requires domain knowledge — the Planner documents UI behavior, not business rules.

What AI doesn't fix

Generated tests still need the Next.js-specific setup in this guide. An agent will not, on its own:

Configure your webServer block correctly.
Create a dedicated test database or seed it.
Know which routes use revalidateTag and should be invalidated between scenarios.
Own the suite after a product redesign.

Use AI for the mechanical 80%; keep the domain-specific 20% under human control.

Common failure modes

"It passes locally, fails in CI"

Almost always one of three things:

A missing env var that your local .env has and CI doesn't.
A data race — the test assumes a record exists because a previous run created it. A fresh CI environment doesn't have it.
Timing — a Server Action revalidation that's fast enough locally to beat your assertion but slow enough in CI to lose. Use role-based locators with built-in auto-waiting instead of raw timeouts.

"Tests pass, production breaks"

Your suite is asserting on surface markup, not behavior. A classic: await expect(page.getByText('Order confirmed')).toBeVisible() passes as long as that string renders, regardless of whether the order actually persisted. Strengthen assertions by hitting the API or reading a value out of the DB in the same spec, or by checking the next page's rendered data.

"The suite keeps growing and we can't keep it green"

This is the hard one. The Healer fixes selector drift; it doesn't fix flow changes. A redesigned checkout, a new onboarding step, a combined settings page — each of those is a manual rewrite. If that rewrite work is consistently deprioritized, the suite rots. The failure mode is predictable: everyone stops trusting CI red, and real bugs slip.

Where Decipher fits

Playwright + AI covers the authoring side of E2E testing well. What it doesn't cover is ongoing maintenance, managed infrastructure, and production observability — the three things that actually determine whether a test suite stays useful 6 and 12 months in.

Decipher generates E2E tests from your live Next.js app, maintains them as flows change (not just selector patches — full flow-level rewrites), runs them on managed cloud infrastructure, and watches real production sessions so regressions that escape the suite still get caught. When a test fails, you get an explanation — real regression, environment issue, or intentional product change — with the session video and impact data attached.

If you want raw Playwright specs you fully own, the setup in this guide is the right path. If you want tests that survive contact with a fast-moving product, pair it with something that owns the maintenance cycle.

FAQ

Q: Should I test against next dev or next start? A: next start for anything beyond a smoke test. Dev mode has different caching, different compilation, and different middleware behavior. You want the production code path under test.

Q: How do I test a page that uses cookies() or headers()? A: Treat the cookies/headers as inputs to the test. Use Playwright's browser.newContext({ extraHTTPHeaders, storageState }) to seed the request, then navigate. Don't try to mock next/headers — that's unit-test territory.

Q: What's the best way to handle flaky Server Action tests? A: Almost always an assertion problem, not a timing problem. Assert on the specific DOM outcome (a new list item with a specific name, a status message with specific text) rather than a generic "page looks right" check. Playwright's auto-waiting handles the rest.

Q: Can I test ISR / revalidate behavior in E2E? A: Partially. You can trigger revalidatePath or revalidateTag via a test-only route and then assert on the updated page. You can't meaningfully test time-based revalidation in CI without mocking the clock, which defeats the point.

Q: Do I need separate tests for the App Router and the Pages Router during a migration? A: Yes. Treat them as two apps sharing a URL space. Middleware behavior, data-fetching semantics, and error boundaries all differ. Tag each spec by router so you can run them independently as the migration progresses.

Q: How many E2E tests should a typical Next.js app have? A: Fewer than you think. Aim to cover the top five to ten user journeys end-to-end — sign in, main task, settings, upgrade, cancel — and let unit and integration tests handle everything else. A 30-spec suite that runs in 4 minutes is more valuable than a 300-spec suite that takes 40.

Written by:

Michael Rosenfield

Co-founder

Share with friends:

Share on X