Next.js Testing Patterns

Test App Router components, Server Actions, and Route Handlers with Jest, Vitest, and MSW

When to Use

• Writing unit tests for Server Components and Client Components in the App Router
• Testing Server Actions with mocked database calls
• Integration testing Route Handlers with simulated HTTP requests
• Setting up Mock Service Worker (MSW) for fetch interception in tests
• Configuring Jest or Vitest for Next.js with proper module resolution

Instructions

1. Use

   @testing-library/react

   for rendering Client Components — import from

   @testing-library/react

   as usual.
2. Test Server Components by calling them as plain async functions — they are just async functions that return JSX.
3. Mock

   next/navigation

   (

   useRouter

   ,

   usePathname

   ,

   useSearchParams

   ) with

   jest.mock()

   or

   vi.mock()

   — these hooks are not available in tests.
4. Mock

   next/headers

   (

   cookies

   ,

   headers

   ) for Server Components that read request headers or cookies.
5. Use MSW (

   msw

   ) to intercept

   fetch()

   calls in integration tests — set up a server with

   setupServer()

   and start/stop per test suite.
6. Test Route Handlers by constructing a

   NextRequest

   and calling the handler directly — no HTTP server needed.
7. Test Server Actions by calling them directly as async functions and asserting the return value.
8. Use

   next-router-mock

   as a drop-in

   useRouter

   mock that supports assertions on navigation calls.

// __tests__/server-component.test.tsx — testing a Server Component
import { render, screen } from '@testing-library/react';
import { PostList } from '@/components/post-list'; // Server Component

// Mock data access module
vi.mock('@/lib/posts', () => ({
  getPosts: vi.fn().mockResolvedValue([
    { id: '1', title: 'Hello World', slug: 'hello-world' },
  ]),
}));

test('renders post titles', async () => {
  const component = await PostList(); // call as async function
  render(component);
  expect(screen.getByText('Hello World')).toBeInTheDocument();
});

// __tests__/client-component.test.tsx — Client Component with router mock
import { render, screen, fireEvent } from '@testing-library/react';
import { useRouter } from 'next/navigation';
import { NavButton } from '@/components/nav-button';

vi.mock('next/navigation', () => ({ useRouter: vi.fn() }));

test('navigates on click', () => {
  const push = vi.fn();
  vi.mocked(useRouter).mockReturnValue({ push } as any);
  render(<NavButton href="/dashboard">Go to Dashboard</NavButton>);
  fireEvent.click(screen.getByText('Go to Dashboard'));
  expect(push).toHaveBeenCalledWith('/dashboard');
});

// __tests__/route-handler.test.ts — Route Handler unit test
import { GET } from '@/app/api/posts/route';
import { NextRequest } from 'next/server';

test('returns posts as JSON', async () => {
  const request = new NextRequest('http://localhost/api/posts');
  const response = await GET(request);
  expect(response.status).toBe(200);
  const data = await response.json();
  expect(Array.isArray(data)).toBe(true);
});

Details

Testing Next.js App Router applications requires different strategies for Server Components, Client Components, and server-side functions — they run in different environments.

Server Component testing: Server Components are async functions — call them directly and render the result. The key is mocking their dependencies (database calls, fetch,

next/headers

) rather than trying to render them in a browser environment.

next/navigation mocking:

useRouter

,

usePathname

,

useSearchParams

, and

redirect

are not available in the test environment. Always mock

next/navigation

. For complex navigation testing, use the

next-router-mock

package which provides a mock router with state tracking.

MSW integration: MSW intercepts

fetch()

at the network layer — no need to mock

fetch

globally. Set up

server.listen()

in

beforeAll

,

server.resetHandlers()

in

afterEach

, and

server.close()

in

afterAll

. Use

server.use()

within a test to override handlers for specific scenarios.

Vitest vs Jest: Vitest is faster and has native ESM support — preferred for new Next.js projects. Configure

vitest.config.ts

with

@vitejs/plugin-react

and alias

next/navigation

to a mock. Jest requires

next/jest

transform configuration for App Router compatibility.

next/cache

in tests:

revalidatePath

and

revalidateTag

throw errors in test environments. Mock

next/cache

module entirely:

vi.mock('next/cache', () => ({ revalidatePath: vi.fn(), revalidateTag: vi.fn() }))

.

E2E testing: For full integration tests including navigation and streaming, use Playwright with

next dev

or

next start

. Playwright can test App Router features (streaming, client navigation) that JSDOM-based unit tests cannot.

Source

https://nextjs.org/docs/app/building-your-application/testing

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.