Playwright E2E Testing in Next.js — Complete Guide
Set up Playwright for end-to-end testing in a Next.js app — auth state reuse, API mocking, visual regression, and running tests in CI.
Playwright has become the standard for Next.js end-to-end testing because it handles the two hardest parts of E2E testing well: authenticated flows and flaky network conditions. Here's a full setup.
Step 1: Install and Initialize Playwright
This scaffolds playwright.config.ts and a tests/ directory, and installs browser binaries for Chromium, Firefox, and WebKit.
Using the production build in webServer.command — not next dev — matters because dev-mode behavior (slower compilation, different error overlays) doesn't reflect what ships.
Step 2: Write a Basic Test
Step 3: Reuse Authentication Across Tests
Logging in via the UI before every test is slow and brittle. Instead, authenticate once in a setup project and save the session.
Every test in the chromium project now starts already signed in, with no login flow executed per test.
Step 4: Mock API Responses to Test Edge Cases
Route interception lets you deterministically test loading, empty, and error states that are otherwise hard to reproduce against a real backend.
Step 5: Add Visual Regression Tests
The first run generates a baseline image; subsequent runs fail if the rendered page differs beyond a configurable pixel threshold, catching visual regressions that functional assertions wouldn't notice.
Step 6: Run Playwright in CI
Uploading the HTML report as an artifact even on failure (if: always()) is what makes failing CI runs debuggable — the report includes screenshots and traces for every failed step.
Key Takeaways
Playwright's storageState mechanism removes login overhead from every test, route interception makes error and edge-case states testable without a real failing backend, and running against a production build rather than the dev server in CI is what keeps test results representative of what actually ships.
