7 min read

Pick Playwright for Next.js App Router CI; Keep Cypress When the Team Lives in the Runner

Mehdi Rezaei
Mehdi
Author
Engineering
Software
Technology

For Next.js App Router products in 2026, choose Playwright Test for E2E in CI when authentication crosses origins (Clerk, Auth0, NextAuth OAuth), when you need free suite sharding across GitHub Actions jobs, or when Safari/WebKit coverage matters. Keep Cypress when the app stays on one origin, developers already ship green Cypress specs, and the interactive time-travel runner is how the team finds failures. Both frameworks are first-class in the Next.js testing guides; the useful vote is CI cost and auth shape, not which logo is louder this quarter.

Kickoffs still frame this as “which tool is better.” The real question is whether your PR pipeline waits on a serial Cypress Cloud plan, or whether OAuth redirects blow up Cypress’s older single-origin assumptions while Playwright’s out-of-process browser control treats multi-tab login as normal.

What each runner owns in an App Router repo

Playwright drives Chromium, Firefox, and WebKit from outside the page. Official Next.js docs ship a `with-playwright` example and recommend exercising the production build (`next build` + `next start`) so Server Components, Route Handlers, and middleware behave like Vercel. The `webServer` block in `playwright.config.ts` can start that production server in CI and wait on `http://localhost:3000`. Parallel workers and `--shard=N/M` are part of the open-source CLI; you scale with machines you already pay for.

Cypress runs inside the browser for E2E and also offers Component Testing with a Next.js + webpack `devServer` config. Next.js documents `create-next-app --example with-cypress`, `cypress open` / `cypress run`, and `start-server-and-test` for CI. Cypress remains strong for interactive debugging and for mounting Client Components without booting the full app. Official Cypress notes still say Component Testing does not cover `async` Server Components. Use E2E for those paths.

They are not substitutes for Vitest or Jest unit tests. Unit and component layers still own pure logic and isolated Client Components. E2E owns navigation, cookies, middleware redirects, and “does the production bundle actually render this route.”

Choose Playwright when CI and auth are the constraints

Use Playwright (at least for App Router E2E) when most of these are true:

  • Login flows leave your domain (OAuth, SSO, payment providers). Multi-origin and multi-tab are first-class.

  • The suite is growing past roughly thirty specs and wall-clock CI time is a budget line. Built-in sharding avoids a paid parallelization product.

  • You need WebKit/Safari in the same config as Chromium without experimental browser plugins.

  • You seed data or hit Route Handlers from tests via Playwright’s `request` fixture alongside UI steps.

  • GitHub Actions (or similar) should run headless with `npx playwright install --with-deps` and upload the HTML report as an artifact.

On App Router, the low-risk CI pattern is mechanical: `webServer.command` runs `npm run build && npm run start` when `CI` is set, `reuseExistingServer` stays false in CI, retries are 2 on CI and 0 locally, and traces capture on first retry. Locally keep `next dev` for fast loops. Official Playwright CI guidance also suggests conservative workers on small shared runners, then sharding when the suite outgrows one job.

The cost is honest. Browser downloads and OS deps add minutes on cold CI agents unless you use the Microsoft Playwright Docker image. Teams new to locator-first APIs miss Cypress’s interactive runner until they learn the Trace Viewer.

Choose Cypress when the team’s feedback loop is the runner

Stay Cypress-first when most of these are true:

  • The product is effectively single-origin; auth is session cookies or a simple in-app login without third-party redirects.

  • Frontend engineers already live in `cypress open`, and rewriting a healthy green suite would burn a quarter for the same coverage.

  • Component Testing for Client Components is a daily habit and you accept E2E for Server Component routes.

  • You already pay for Cypress Cloud (or accept manual spec splitting) and CI minutes are not the bottleneck.

  • The team writes tests in JavaScript/TypeScript only and does not need Python/Java clients.

Cypress still wins the “watch the test fail live” slot for product teams that debug in the runner daily. Next.js’s own guide wires headless CI with `start-server-and-test` and `cypress run`. That path is fine. The failure mode is insisting Cypress can cheaply parallelize a 400-spec suite without Cloud, or forcing `cy.origin` gymnastics for every OAuth vendor when Playwright would have been the shorter path from day one.

App Router patterns that change the vote

Run a production build in CI instead of only `next dev`. Both Next.js guides say E2E should resemble production. Playwright’s `webServer` makes that default easy; Cypress needs an explicit start helper. If your failures only appear after `next build`, a dev-server-only pipeline is lying to you.

Auth is architecture. Clerk/Auth0/NextAuth redirect chains are the common App Router reality. Playwright’s process model matches that. Cypress can do cross-origin work, but you will feel the tax in flaky setup.

Server Components are not component-test targets today. Cypress documents the gap for `async` Server Components; Playwright’s E2E focus matches what Next.js recommends for async UI. Do not invent a unit-test harness that pretends to render RSC trees if E2E already covers the route.

Parallelism is a product decision. Playwright shards with `--shard` on machines you control. Cypress’s smart orchestration is tied to Cypress Cloud unless you maintain your own split. If finance asks why E2E doubled the bill, that line item is often the runner choice, not “tests are slow.”

A practical split that survives a real team

  • Greenfield Next.js App Router with OAuth: Playwright E2E + Vitest/Jest for units; skip a dual E2E stack.

  • Existing healthy Cypress suite, single-origin SaaS: keep Cypress; add Playwright only if WebKit or multi-origin becomes a release gate.

  • Large suite, GitHub Actions minutes matter: Playwright with 2–4 shards and the official Docker image.

  • Design-system Client Components: Cypress Component Testing can stay; put critical App Router journeys in one E2E tool, not two.

  • Never run both full E2E suites on every PR. Pick one gate; treat the other as nightly if you must migrate.

PR checklist before you lock the choice

  1. Name the auth model: same-origin session vs external OAuth/SSO.

  2. Time a representative CI run on one machine for each runner with a production build.

  3. List browsers you actually promise customers (Chromium-only vs WebKit required).

  4. Decide sharding strategy and whether a paid cloud dashboard is in budget.

  5. Confirm Server Component routes are covered by E2E, not by unsupported component mounts.

  6. Refuse dual E2E frameworks in one repo without a written sunset date.

Where teams usually get this wrong

One mistake is picking Cypress because the demo looks nicer, then discovering OAuth redirects need a week of `cy.origin` patches. Another is enabling five Playwright browser projects on every PR before sharding, so Actions minutes explode. Teams also keep E2E on `next dev` in CI so RSC and middleware bugs only show in production.

What I tell teams in kickoff

If your App Router product uses hosted auth and ships on Vercel, start E2E with Playwright, production `webServer`, Chromium on every PR, and WebKit on main or nightly. If you already have a stable Cypress suite and single-origin auth, keep shipping; migrate only when CI cost or multi-origin coverage forces the issue.

Playwright and Cypress both ship real Next.js work in 2026. The failure mode is choosing the interactive runner when auth leaves the origin every login, or paying for parallelization you could get from `--shard` on machines you already rent. Make that call on measured CI wall-clock for your suite, not on last week’s conference talk.

Share this article