nextjs-testing

name	nextjs-testing
description	Generates tests for Next.js projects (App Router or Pages Router), splitting work between Vitest for Server Actions/schema validation/sync components and Playwright for async Server Components, auth flows, and checkout. Use when the user asks to test a Next.js page, Server Action, API route handler, or middleware, or mentions next.config, app/ directory, Server Components, or a project whose package.json declares "next". For a React app without "next" in package.json, use react-testing instead.
license	MIT
compatibility	Requires Node.js and the project's existing package manager. Requires a package.json declaring "next".
metadata	{"platform":"nextjs","report-source":"testing-methodologies-deep-research-report.txt Part 4 and Part 8"}
allowed-tools	Read, Write, Edit, Grep, Glob, Bash
paths	["app/**/*.tsx","app/**/*.ts","pages/**/*.tsx","pages/**/*.ts","next.config.*"]

Next.js Testing

Writes tests for Next.js projects, splitting work across a hard boundary: Vitest for anything that doesn't require rendering an async Server Component, Playwright for everything that does. Getting this boundary wrong is the single most common Next.js testing mistake — see reference/async-server-components.md before writing anything. Writing the test files is the deliverable. Running the suite and verifying it — including the fault-injection self-check — is a separate, optional step this skill offers but never runs without being asked. See Step 6.

Progress checklist

Copy this into your response and check items off as you go:

- [ ] 1. Detect stack + router (scripts/detect_stack.sh)
- [ ] 2. Audit project structure; identify Vitest vs Playwright boundary
- [ ] 3. Ask the user what to test (layer + scope) — do not assume
- [ ] 4. State the test plan explicitly
- [ ] 5. Generate tests following AAA, boundary-only mocking
- [ ] 6. Report what was written; offer to run + verify — do not run yet
- [ ] 7. Only if asked: run tests, fault-injection self-check, report results

Step 1 — Detect stack and router

Run scripts/detect_stack.sh from the project root. It confirms this is a Next.js project and reports App Router vs Pages Router — this determines the entire strategy and must be resolved before generating any component test — plus the existing Vitest/Jest, Playwright/Cypress, RTL, MSW, and Zod presence.

If a test runner is already in use, follow it even if a different tool is this skill's default. Never introduce a second, competing test runner.

Step 2 — Audit project structure

Before writing anything, classify the target and route it correctly:

• Async Server Component (contains an await in the component body) → Vitest cannot render this. Either propose extracting the async data call into a plain function (the recommended default — see reference/async-server-components.md) or route the test to Playwright. Never attempt to render it under Vitest.
• Synchronous Server Component or Client Component → Vitest + RTL, same as react-testing.
• Server Action → test as a plain async function with Vitest, not through a rendered tree.
• API route handler (route.ts) or middleware → import the exported function directly and invoke with a constructed Request; see .