1# Next.js Testing Patterns
2 
3## Table of Contents
4 
51. [Setup](#setup)
62. [App Router Patterns](#app-router-patterns)
73. [Pages Router Patterns](#pages-router-patterns)
84. [Dynamic Routes](#dynamic-routes)
95. [API Routes](#api-routes)
106. [Middleware Testing](#middleware-testing)
117. [Hydration Testing](#hydration-testing)
128. [next/image Testing](#nextimage-testing)
139. [NextAuth.js Authentication](#nextauthjs-authentication)
1410. [Tips](#tips)
1511. [Anti-Patterns](#anti-patterns)
1612. [Related](#related)
17 
18> **When to use**: Testing Next.js applications with App Router, Pages Router, API routes, middleware, SSR, dynamic routes, and server components.
19> **Prerequisites**: [configuration.md](../core/configuration.md), [locators.md](../core/locators.md)
20 
21## Setup
22 
23### Configuration with webServer
24 
25```typescript
26// playwright.config.ts
27import { defineConfig, devices } from '@playwright/test';
28 
29export default defineConfig({
30  testDir: './tests',
31  fullyParallel: true,
32  forbidOnly: !!process.env.CI,
33  retries: process.env.CI ? 2 : 0,
34  workers: process.env.CI ? '50%' : undefined,
35 
36  use: {
37    baseURL: 'http://localhost:3000',
38    trace: 'on-first-retry',
39    screenshot: 'only-on-failure',
40  },
41 
42  projects: [
43    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
44    { name: 'mobile', use: { ...devices['iPhone 14'] } },
45  ],
46 
47  webServer: {
48    command: process.env.CI
49      ? 'npm run build && npm run start'
50      : 'npm run dev',
51    url: 'http://localhost:3000',
52    reuseExistingServer: !process.env.CI,
53    timeout: 120_000,
54    env: {
55      NODE_ENV: process.env.CI ? 'production' : 'test',
56    },
57  },
58});
59```
60 
61### Environment Variables
62 
63Next.js loads `.env.test` when `NODE_ENV=test`:
64 
65```bash
66# .env.test (commit this)
67NEXT_PUBLIC_API_URL=http://localhost:3000/api
68DATABASE_URL=postgresql://localhost:5432/test_db
69 
70# .env.test.local (gitignored)
71NEXTAUTH_SECRET=test-secret-local
72```
73 
74## App Router Patterns
75 
76### Server Component Content
77 
78```typescript
79test('renders server component content', async ({ page }) => {
80  await page.goto('/');
81 
82  await expect(page.getByRole('heading', { name: 'Welcome', level: 1 })).toBeVisible();
83  await expect(page.getByRole('navigation', { name: 'Main' })).toBeVisible();
84});
85```
86 
87### Loading States with Streaming
88 
89```typescript
90test('loading state during data streaming', async ({ page }) => {
91  await page.route('**/api/stats', async (route) => {
92    await new Promise((r) => setTimeout(r, 2000));
93    await route.continue();
94  });
95 
96  await page.goto('/dashboard');
97 
98  await expect(page.getByRole('progressbar')).toBeVisible();
99  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
100  await expect(page.getByRole('progressbar')).toBeHidden();
101});
102```
103 
104### Nested Layouts
105 
106```typescript
107test('layouts persist across navigation', async ({ page }) => {
108  await page.goto('/dashboard/analytics');
109 
110  const sidebar = page.getByRole('navigation', { name: 'Dashboard' });
111  await expect(sidebar).toBeVisible();
112 
113  await sidebar.getByRole('link', { name: 'Settings' }).click();
114  await page.waitForURL('/dashboard/settings');
115 
116  await expect(sidebar).toBeVisible();
117  await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
118});
119```
120 
121## Pages Router Patterns
122 
123### SSR with getServerSideProps
124 
125```typescript
126test('page with getServerSideProps renders data', async ({ page }) => {
127  await page.goto('/blog');
128 
129  await expect(page.getByRole('heading', { name: 'Blog', level: 1 })).toBeVisible();
130  await expect(page.getByRole('article')).toHaveCount(10);
131  await expect(page.getByRole('article').first()).toContainText(/\w+/);
132});
133```
134 
135### Static Generation with getStaticProps
136 
137```typescript
138test('static page shows pre-rendered content', async ({ page }) => {
139  await page.goto('/about');
140 
141  await expect(page.getByRole('heading', { name: 'About Us' })).toBeVisible();
142  await expect(page.getByText('Founded in 2020')).toBeVisible();
143});
144```
145 
146## Dynamic Routes
147 
148### Slug Parameters
149 
150```typescript
151test('dynamic [slug] renders correct content', async ({ page }) => {
152  await page.goto('/blog/testing-guide');
153 
154  await expect(page.getByRole('heading', { level: 1 })).toContainText('Testing Guide');
155  await expect(page.getByText('Page not found')).toBeHidden();
156});
157 
158test('non-existent slug shows 404', async ({ page }) => {
159  const response = await page.goto('/blog/nonexistent-post');
160 
161  expect(response?.status()).toBe(404);
162  await expect(page.getByRole('heading', { name: '404' })).toBeVisible();
163});
164```
165 
166### Catch-All Routes
167 
168```typescript
169test('catch-all handles nested paths', async ({ page }) => {
170  await page.goto('/docs/getting-started/installation');
171  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
172 
173  await page.goto('/docs/api/configuration');
174  await expect(page.getByRole('heading', { name: 'Configuration' })).toBeVisible();
175});
176```
177 
178### Query Parameters
179 
180```typescript
181test('query parameters filter content', async ({ page }) => {
182  await page.goto('/products?category=electronics&sort=price-asc');
183 
184  await expect(page.getByRole('heading', { name: 'Electronics' })).toBeVisible();
185 
186  const prices = await page.getByTestId('product-price').allTextContents();
187  const numericPrices = prices.map((p) => parseFloat(p.replace('$', '')));
188  expect(numericPrices).toEqual([...numericPrices].sort((a, b) => a - b));
189});
190```
191 
192## API Routes
193 
194### Direct API Testing
195 
196```typescript
197test('GET /api/products returns list', async ({ request }) => {
198  const response = await request.get('/api/products');
199 
200  expect(response.ok()).toBeTruthy();
201  const body = await response.json();
202  expect(body.products).toBeInstanceOf(Array);
203  expect(body.products[0]).toHaveProperty('id');
204  expect(body.products[0]).toHaveProperty('name');
205});
206 
207test('POST /api/products creates item', async ({ request }) => {
208  const response = await request.post('/api/products', {
209    data: { name: 'Test Product', price: 29.99 },
210  });
211 
212  expect(response.status()).toBe(201);
213  const body = await response.json();
214  expect(body.product.name).toBe('Test Product');
215});
216 
217test('POST /api/products validates fields', async ({ request }) => {
218  const response = await request.post('/api/products', {
219    data: { name: '' },
220  });
221 
222  expect(response.status()).toBe(400);
223  const body = await response.json();
224  expect(body.error).toContainEqual(expect.objectContaining({ field: 'price' }));
225});
226```
227 
228### API Through UI
229 
230```typescript
231test('form submission calls API', async ({ page }) => {
232  await page.goto('/products/new');
233 
234  await page.getByLabel('Product name').fill('Widget');
235  await page.getByLabel('Price').fill('19.99');
236  await page.getByRole('button', { name: 'Create product' }).click();
237 
238  await expect(page.getByText('Product created successfully')).toBeVisible();
239  await page.waitForURL('/products/**');
240});
241```
242 
243## Middleware Testing
244 
245### Auth Redirects
246 
247```typescript
248test('unauthenticated user redirected to login', async ({ page }) => {
249  await page.goto('/dashboard');
250 
251  expect(page.url()).toContain('/login');
252  await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
253});
254 
255test('redirect preserves return URL', async ({ page }) => {
256  await page.goto('/dashboard/settings');
257 
258  const url = new URL(page.url());
259  expect(url.pathname).toBe('/login');
260  expect(url.searchParams.get('callbackUrl') || url.searchParams.get('returnTo'))
261    .toContain('/dashboard/settings');
262});
263```
264 
265### Security Headers
266 
267```typescript
268test('middleware sets security headers', async ({ page }) => {
269  const response = await page.goto('/');
270 
271  const headers = response!.headers();
272  expect(headers['x-frame-options']).toBe('DENY');
273  expect(headers['x-content-type-options']).toBe('nosniff');
274});
275```
276 
277### Locale Rewrites
278 
279```typescript
280test('middleware rewrites based on locale', async ({ page, context }) => {
281  await context.setExtraHTTPHeaders({
282    'Accept-Language': 'fr-FR,fr;q=0.9',
283  });
284 
285  await page.goto('/');
286 
287  await expect(page.getByText('Bienvenue')).toBeVisible();
288});
289```
290 
291## Hydration Testing
292 
293### Console Error Detection
294 
295```typescript
296test('no hydration errors in console', async ({ page }) => {
297  const consoleErrors: string[] = [];
298  page.on('console', (msg) => {
299    if (msg.type() === 'error') {
300      consoleErrors.push(msg.text());
301    }
302  });
303 
304  await page.goto('/');
305  await page.getByRole('button', { name: 'Get started' }).click();
306 
307  const hydrationErrors = consoleErrors.filter(
308    (e) =>
309      e.includes('Hydration') ||
310      e.includes('hydration') ||
311      e.includes('did not match')
312  );
313  expect(hydrationErrors).toEqual([]);
314});
315```
316 
317### Interactive Elements After Hydration
318 
319```typescript
320test('interactive elements work after hydration', async ({ page }) => {
321  await page.goto('/');
322 
323  const counter = page.getByTestId('counter-value');
324  await expect(counter).toHaveText('0');
325 
326  await page.getByRole('button', { name: 'Increment' }).click();
327  await expect(counter).toHaveText('1');
328});
329```
330 
331## next/image Testing
332 
333```typescript
334test('hero image loads with srcset', async ({ page }) => {
335  await page.goto('/');
336 
337  const heroImage = page.getByRole('img', { name: 'Hero banner' });
338  await expect(heroImage).toBeVisible();
339 
340  const srcset = await heroImage.getAttribute('srcset');
341  expect(srcset).toBeTruthy();
342  expect(srcset).toContain('w=');
343 
344  const loading = await heroImage.getAttribute('loading');
345  expect(loading).not.toBe('lazy');
346});
347 
348test('offscreen images lazy load', async ({ page }) => {
349  await page.goto('/gallery');
350 
351  const offscreenImage = page.getByRole('img', { name: 'Gallery item 20' });
352 
353  await offscreenImage.scrollIntoViewIfNeeded();
354  await expect(offscreenImage).toBeVisible();
355 
356  const naturalWidth = await offscreenImage.evaluate(
357    (img: HTMLImageElement) => img.naturalWidth
358  );
359  expect(naturalWidth).toBeGreaterThan(0);
360});
361```
362 
363## NextAuth.js Authentication
364 
365### Setup Project
366 
367```typescript
368// playwright.config.ts
369export default defineConfig({
370  projects: [
371    { name: 'setup', testMatch: /auth\.setup\.ts/ },
372    {
373      name: 'authenticated',
374      use: { storageState: 'playwright/.auth/user.json' },
375      dependencies: ['setup'],
376    },
377    { name: 'unauthenticated', testMatch: '**/*.unauth.spec.ts' },
378  ],
379});
380```
381 
382### Auth Setup
383 
384```typescript
385// tests/auth.setup.ts
386import { test as setup, expect } from '@playwright/test';
387 
388const authFile = 'playwright/.auth/user.json';
389 
390setup('authenticate via credentials', async ({ page }) => {
391  await page.goto('/login');
392  await page.getByLabel('Email').fill('[email protected]');
393  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
394  await page.getByRole('button', { name: 'Sign in' }).click();
395 
396  await page.waitForURL('/dashboard');
397  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
398 
399  await page.context().storageState({ path: authFile });
400});
401```
402 
403### Authenticated Tests
404 
405```typescript
406test('authenticated user sees dashboard', async ({ page }) => {
407  await page.goto('/dashboard');
408 
409  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
410  await expect(page.getByText('[email protected]')).toBeVisible();
411});
412```
413 
414## Tips
415 
416### Dev Server vs Production Build
417 
418| Scenario | Command | Trade-off |
419|---|---|---|
420| Local development | `npm run dev` | Fast iteration, no production behavior |
421| CI pipeline | `npm run build && npm run start` | Tests real production bundle |
422 
423### Turbopack
424 
425```typescript
426webServer: {
427  command: process.env.CI
428    ? 'npm run build && npm run start'
429    : 'npx next dev --turbopack',
430  url: 'http://localhost:3000',
431  reuseExistingServer: !process.env.CI,
432},
433```
434 
435### Multiple webServer Entries
436 
437```typescript
438webServer: [
439  {
440    command: 'npm run dev:api',
441    url: 'http://localhost:4000/health',
442    reuseExistingServer: !process.env.CI,
443  },
444  {
445    command: 'npm run dev',
446    url: 'http://localhost:3000',
447    reuseExistingServer: !process.env.CI,
448  },
449],
450```
451 
452## Anti-Patterns
453 
454| Don't Do This | Problem | Do This Instead |
455|---|---|---|
456| `await page.waitForTimeout(3000)` | Arbitrary waits are fragile | `await page.waitForURL('/path')` or `await expect(locator).toBeVisible()` |
457| Test `getServerSideProps` directly | Depends on req/res context | Navigate to page and verify rendered output |
458| Mock your own API routes | Hides real API bugs | Let real API handle requests; mock only external services |
459| `page.goto('http://localhost:3000/path')` | Breaks when port changes | Use `page.goto('/path')` with `baseURL` |
460| Run `npm run build` locally for every test | Extremely slow | Use `npm run dev` locally with `reuseExistingServer: true` |
461| Test `next/image` by checking exact URLs | Paths change between dev/prod | Assert on `alt`, visibility, `naturalWidth > 0`, `srcset` |
462| Test server actions by calling as functions | Server actions need Next.js runtime | Trigger through UI (forms, buttons) |
463 
464## Related
465 
466- [configuration.md](../core/configuration.md) -- Playwright configuration including `webServer`
467- [authentication.md](../advanced/authentication.md) -- authentication setup and `storageState`
468- [api-testing.md](../testing-patterns/api-testing.md) -- testing API routes with `request` context
469- [react.md](react.md) -- React patterns for Next.js client components
470