Next.js Testing
Priority: P1 (HIGH)
Test Runner
- Existing projects (Pages Router / legacy stack): Use Jest (
jest@29 + babel-jest + jest-environment-jsdom).
- New projects (App Router): Use Vitest for speed and native ESM support.
Workflow: Test New Feature
- Write unit tests — Use Jest (or Vitest for new projects) + RTL with Arrange-Act-Assert pattern.
- Mock APIs — Set up MSW handlers for all fetch boundaries.
- Test interactions — Use
userEvent (async) for clicks, typing, form submissions.
- Add E2E tests — Use Playwright for critical user flows (login, checkout).
- Verify coverage — Aim for 80%+ on core libraries via JSON coverage reports.
Component Test Example
See implementation examples
Implementation Guidelines
- Unit Testing: Use Jest (existing projects) or Vitest (new projects) with React Testing Library (RTL). Follow Arrange-Act-Assert (AAA) patterns.
- E2E Testing: Use Playwright for full user flow validation. Focus on critical flows (Login, Checkout).
- Networking: Mock all internal/external API boundaries using Mock Service Worker (MSW). Ensure
server and browser handlers correctly configured.
- Interactions: Use
userEvent (async) to simulate user actions: await user.click(button).
- Selectors: Favor
getByRole / findByRole to test accessibility. Use data-testid only as fallback.
- Environment: For Jest, use
jest-environment-jsdom. For Vitest, configure vitest.config.ts with jsdom or happy-dom.
- Reporting: Ensure tests generate JSON coverage reports for CI gates. Aim for 80%+ coverage on core libraries.
Anti-Patterns
- No real network usage in tests: Always use MSW handlers or mocks.
- No implementation testing: Test user behavior, not internal methods.
- No heavy E2E for unit logic: Use Jest/Vitest for isolated logic tests.
- No global state leakage: Reset MSW handlers and mocks after each test.
References
