@assertrx/dino 1.0.0

package/skills/playwright-core/nextjs.md

@@ -0,0 +1,1013 @@
+# Testing Next.js Apps with Playwright
+
+> **When to use**: Testing Next.js applications -- App Router, Pages Router, API routes, middleware, SSR pages, dynamic routes, and server components. This guide covers E2E testing patterns specific to Next.js behavior.
+> **Prerequisites**: [core/configuration.md](configuration.md), [core/locators.md](locators.md)
+
+## Quick Reference
+
+```bash
+# Install Playwright in a Next.js project
+npm init playwright@latest
+
+# Run with Next.js dev server managed by Playwright
+npx playwright test
+
+# Run against a production build (recommended for CI)
+npx playwright test --project=chromium
+
+# Debug a single test with headed browser
+npx playwright test tests/home.spec.ts --headed --debug
+```
+
+```
+# .env.test — loaded by Next.js automatically when NODE_ENV=test
+NEXT_PUBLIC_API_URL=http://localhost:3000/api
+DATABASE_URL=postgresql://localhost:5432/test_db
+NEXTAUTH_SECRET=test-secret-do-not-use-in-production
+NEXTAUTH_URL=http://localhost:3000
+```
+
+## Setup
+
+### Playwright Config for Next.js
+
+The single most important configuration detail: use `webServer` to let Playwright start and manage your Next.js server.
+
+**TypeScript**
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.ts',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? '50%' : undefined,
+
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'mobile',
+      use: { ...devices['iPhone 14'] },
+    },
+  ],
+
+  webServer: {
+    command: process.env.CI
+      ? 'npm run build && npm run start' // production build in CI
+      : 'npm run dev',                   // dev server locally
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+    env: {
+      NODE_ENV: process.env.CI ? 'production' : 'test',
+    },
+  },
+});
+```
+
+**JavaScript**
+```javascript
+// playwright.config.js
+const { defineConfig, devices } = require('@playwright/test');
+
+module.exports = defineConfig({
+  testDir: './tests',
+  testMatch: '**/*.spec.js',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? '50%' : undefined,
+
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'mobile',
+      use: { ...devices['iPhone 14'] },
+    },
+  ],
+
+  webServer: {
+    command: process.env.CI
+      ? 'npm run build && npm run start'
+      : 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+    env: {
+      NODE_ENV: process.env.CI ? 'production' : 'test',
+    },
+  },
+});
+```
+
+### Environment Variables with `.env.test`
+
+Next.js loads `.env.test` automatically when `NODE_ENV=test`. Use this for test-specific overrides.
+
+```bash
+# .env.test (commit this -- no real secrets)
+NEXT_PUBLIC_API_URL=http://localhost:3000/api
+NEXT_PUBLIC_FEATURE_FLAG_NEW_CHECKOUT=true
+DATABASE_URL=postgresql://localhost:5432/test_db
+
+# .env.test.local (gitignored -- real test secrets)
+NEXTAUTH_SECRET=test-secret-local
+STRIPE_TEST_KEY=sk_test_xxx
+```
+
+```bash
+# .gitignore
+.env*.local
+playwright-report/
+playwright/.auth/
+test-results/
+```
+
+## Patterns
+
+### Testing App Router Pages
+
+**Use when**: Testing pages built with the Next.js App Router (`app/` directory). App Router pages are server components by default and may include streaming, suspense boundaries, and loading states.
+**Avoid when**: You need to test isolated server component logic -- use unit tests for that. E2E tests verify the rendered result.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('App Router pages', () => {
+  test('home page renders server component content', async ({ page }) => {
+    await page.goto('/');
+
+    // Server components render on the server -- by the time Playwright
+    // sees the page, SSR content is already in the HTML
+    await expect(page.getByRole('heading', { name: 'Welcome', level: 1 })).toBeVisible();
+    await expect(page.getByRole('navigation', { name: 'Main' })).toBeVisible();
+  });
+
+  test('loading state shows while data streams in', async ({ page }) => {
+    // Slow down the API to expose the loading state
+    await page.route('**/api/dashboard/stats', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      await route.continue();
+    });
+
+    await page.goto('/dashboard');
+
+    // Verify the loading skeleton appears during streaming
+    await expect(page.getByRole('progressbar')).toBeVisible();
+
+    // Then verify the real content replaces it
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await expect(page.getByRole('progressbar')).toBeHidden();
+  });
+
+  test('suspense boundary shows fallback then resolves', async ({ page }) => {
+    await page.goto('/products');
+
+    // The product list may be inside a Suspense boundary
+    // Playwright auto-waits, so just assert the final state
+    await expect(page.getByRole('listitem')).toHaveCount(12);
+  });
+
+  test('nested layouts persist across navigation', async ({ page }) => {
+    await page.goto('/dashboard/analytics');
+
+    // Verify the dashboard layout sidebar is visible
+    const sidebar = page.getByRole('navigation', { name: 'Dashboard' });
+    await expect(sidebar).toBeVisible();
+
+    // Navigate to a sibling route -- layout should persist (no full reload)
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+    await page.waitForURL('/dashboard/settings');
+
+    // Sidebar is still there -- layout was not re-mounted
+    await expect(sidebar).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('App Router pages', () => {
+  test('home page renders server component content', async ({ page }) => {
+    await page.goto('/');
+
+    await expect(page.getByRole('heading', { name: 'Welcome', level: 1 })).toBeVisible();
+    await expect(page.getByRole('navigation', { name: 'Main' })).toBeVisible();
+  });
+
+  test('loading state shows while data streams in', async ({ page }) => {
+    await page.route('**/api/dashboard/stats', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      await route.continue();
+    });
+
+    await page.goto('/dashboard');
+
+    await expect(page.getByRole('progressbar')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await expect(page.getByRole('progressbar')).toBeHidden();
+  });
+
+  test('suspense boundary shows fallback then resolves', async ({ page }) => {
+    await page.goto('/products');
+
+    await expect(page.getByRole('listitem')).toHaveCount(12);
+  });
+
+  test('nested layouts persist across navigation', async ({ page }) => {
+    await page.goto('/dashboard/analytics');
+
+    const sidebar = page.getByRole('navigation', { name: 'Dashboard' });
+    await expect(sidebar).toBeVisible();
+
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+    await page.waitForURL('/dashboard/settings');
+
+    await expect(sidebar).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
+  });
+});
+```
+
+### Testing Pages Router (getServerSideProps / getStaticProps)
+
+**Use when**: Testing pages built with the Pages Router (`pages/` directory) that use `getServerSideProps` or `getStaticProps` for data fetching.
+**Avoid when**: Testing the data fetching functions directly -- that is a unit test concern. E2E tests verify what the user sees.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Pages Router with SSR', () => {
+  test('page with getServerSideProps renders fetched data', async ({ page }) => {
+    await page.goto('/blog');
+
+    // getServerSideProps fetches posts on the server -- verify they render
+    await expect(page.getByRole('heading', { name: 'Blog', level: 1 })).toBeVisible();
+    await expect(page.getByRole('article')).toHaveCount(10);
+
+    // Verify server-fetched data appears (not a loading skeleton)
+    await expect(page.getByRole('article').first()).toContainText(/\w+/);
+  });
+
+  test('page with getStaticProps shows pre-rendered content', async ({ page }) => {
+    await page.goto('/about');
+
+    // Static pages are pre-rendered at build time -- content is immediate
+    await expect(page.getByRole('heading', { name: 'About Us' })).toBeVisible();
+    await expect(page.getByText('Founded in 2020')).toBeVisible();
+  });
+
+  test('client-side navigation with next/link preserves SPA behavior', async ({ page }) => {
+    await page.goto('/blog');
+
+    // Click a next/link -- this should be a client-side transition, not a full reload
+    const navigationPromise = page.waitForURL('/blog/my-first-post');
+    await page.getByRole('link', { name: 'My First Post' }).click();
+    await navigationPromise;
+
+    await expect(page.getByRole('heading', { name: 'My First Post', level: 1 })).toBeVisible();
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('Pages Router with SSR', () => {
+  test('page with getServerSideProps renders fetched data', async ({ page }) => {
+    await page.goto('/blog');
+
+    await expect(page.getByRole('heading', { name: 'Blog', level: 1 })).toBeVisible();
+    await expect(page.getByRole('article')).toHaveCount(10);
+    await expect(page.getByRole('article').first()).toContainText(/\w+/);
+  });
+
+  test('page with getStaticProps shows pre-rendered content', async ({ page }) => {
+    await page.goto('/about');
+
+    await expect(page.getByRole('heading', { name: 'About Us' })).toBeVisible();
+    await expect(page.getByText('Founded in 2020')).toBeVisible();
+  });
+
+  test('client-side navigation with next/link preserves SPA behavior', async ({ page }) => {
+    await page.goto('/blog');
+
+    const navigationPromise = page.waitForURL('/blog/my-first-post');
+    await page.getByRole('link', { name: 'My First Post' }).click();
+    await navigationPromise;
+
+    await expect(page.getByRole('heading', { name: 'My First Post', level: 1 })).toBeVisible();
+  });
+});
+```
+
+### Testing Dynamic Routes (`[slug]`, `[...catchAll]`)
+
+**Use when**: Testing pages with dynamic segments like `/blog/[slug]`, `/products/[id]`, or catch-all routes like `/docs/[...path]`.
+**Avoid when**: The route is static -- no dynamic segments involved.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('dynamic routes', () => {
+  test('dynamic [slug] page renders correct content', async ({ page }) => {
+    await page.goto('/blog/nextjs-testing-guide');
+
+    await expect(page.getByRole('heading', { level: 1 })).toContainText('Next.js Testing Guide');
+    // Verify the slug maps to the correct content, not a 404
+    await expect(page.getByText('Page not found')).toBeHidden();
+  });
+
+  test('non-existent slug shows 404 page', async ({ page }) => {
+    const response = await page.goto('/blog/this-post-does-not-exist');
+
+    // Next.js returns 404 for pages that call notFound() or return { notFound: true }
+    expect(response?.status()).toBe(404);
+    await expect(page.getByRole('heading', { name: '404' })).toBeVisible();
+  });
+
+  test('catch-all route handles nested paths', async ({ page }) => {
+    await page.goto('/docs/getting-started/installation');
+
+    await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
+
+    // Navigate to a different docs path
+    await page.goto('/docs/api/configuration');
+    await expect(page.getByRole('heading', { name: 'Configuration' })).toBeVisible();
+  });
+
+  test('dynamic route with query parameters', async ({ page }) => {
+    await page.goto('/products?category=electronics&sort=price-asc');
+
+    await expect(page.getByRole('heading', { name: 'Electronics' })).toBeVisible();
+    // Verify sort order is applied
+    const prices = await page.getByTestId('product-price').allTextContents();
+    const numericPrices = prices.map((p) => parseFloat(p.replace('$', '')));
+    expect(numericPrices).toEqual([...numericPrices].sort((a, b) => a - b));
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('dynamic routes', () => {
+  test('dynamic [slug] page renders correct content', async ({ page }) => {
+    await page.goto('/blog/nextjs-testing-guide');
+
+    await expect(page.getByRole('heading', { level: 1 })).toContainText('Next.js Testing Guide');
+    await expect(page.getByText('Page not found')).toBeHidden();
+  });
+
+  test('non-existent slug shows 404 page', async ({ page }) => {
+    const response = await page.goto('/blog/this-post-does-not-exist');
+
+    expect(response?.status()).toBe(404);
+    await expect(page.getByRole('heading', { name: '404' })).toBeVisible();
+  });
+
+  test('catch-all route handles nested paths', async ({ page }) => {
+    await page.goto('/docs/getting-started/installation');
+
+    await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
+
+    await page.goto('/docs/api/configuration');
+    await expect(page.getByRole('heading', { name: 'Configuration' })).toBeVisible();
+  });
+
+  test('dynamic route with query parameters', async ({ page }) => {
+    await page.goto('/products?category=electronics&sort=price-asc');
+
+    await expect(page.getByRole('heading', { name: 'Electronics' })).toBeVisible();
+    const prices = await page.getByTestId('product-price').allTextContents();
+    const numericPrices = prices.map((p) => parseFloat(p.replace('$', '')));
+    expect(numericPrices).toEqual([...numericPrices].sort((a, b) => a - b));
+  });
+});
+```
+
+### Testing API Routes
+
+**Use when**: Testing Next.js API routes (`app/api/` or `pages/api/`) directly with Playwright's `request` context, or indirectly through UI interactions that call them.
+**Avoid when**: Unit testing API handler logic in isolation -- use a unit testing framework for that.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('API routes -- direct testing', () => {
+  test('GET /api/products returns product list', async ({ request }) => {
+    const response = await request.get('/api/products');
+
+    expect(response.ok()).toBeTruthy();
+    const body = await response.json();
+    expect(body.products).toBeInstanceOf(Array);
+    expect(body.products.length).toBeGreaterThan(0);
+    expect(body.products[0]).toHaveProperty('id');
+    expect(body.products[0]).toHaveProperty('name');
+    expect(body.products[0]).toHaveProperty('price');
+  });
+
+  test('POST /api/products creates a new product', async ({ request }) => {
+    const response = await request.post('/api/products', {
+      data: {
+        name: 'Test Product',
+        price: 29.99,
+        description: 'Created by Playwright',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+    const body = await response.json();
+    expect(body.product.name).toBe('Test Product');
+  });
+
+  test('POST /api/products validates required fields', async ({ request }) => {
+    const response = await request.post('/api/products', {
+      data: { name: '' }, // missing required fields
+    });
+
+    expect(response.status()).toBe(400);
+    const body = await response.json();
+    expect(body.error).toContainEqual(
+      expect.objectContaining({ field: 'price' })
+    );
+  });
+});
+
+test.describe('API routes -- indirect through UI', () => {
+  test('form submission calls API and shows result', async ({ page }) => {
+    await page.goto('/products/new');
+
+    await page.getByLabel('Product name').fill('Widget');
+    await page.getByLabel('Price').fill('19.99');
+    await page.getByRole('button', { name: 'Create product' }).click();
+
+    // The UI calls POST /api/products internally
+    await expect(page.getByText('Product created successfully')).toBeVisible();
+    await page.waitForURL('/products/**');
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('API routes -- direct testing', () => {
+  test('GET /api/products returns product list', async ({ request }) => {
+    const response = await request.get('/api/products');
+
+    expect(response.ok()).toBeTruthy();
+    const body = await response.json();
+    expect(body.products).toBeInstanceOf(Array);
+    expect(body.products.length).toBeGreaterThan(0);
+    expect(body.products[0]).toHaveProperty('id');
+    expect(body.products[0]).toHaveProperty('name');
+    expect(body.products[0]).toHaveProperty('price');
+  });
+
+  test('POST /api/products creates a new product', async ({ request }) => {
+    const response = await request.post('/api/products', {
+      data: {
+        name: 'Test Product',
+        price: 29.99,
+        description: 'Created by Playwright',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+    const body = await response.json();
+    expect(body.product.name).toBe('Test Product');
+  });
+
+  test('POST /api/products validates required fields', async ({ request }) => {
+    const response = await request.post('/api/products', {
+      data: { name: '' },
+    });
+
+    expect(response.status()).toBe(400);
+    const body = await response.json();
+    expect(body.error).toContainEqual(
+      expect.objectContaining({ field: 'price' })
+    );
+  });
+});
+
+test.describe('API routes -- indirect through UI', () => {
+  test('form submission calls API and shows result', async ({ page }) => {
+    await page.goto('/products/new');
+
+    await page.getByLabel('Product name').fill('Widget');
+    await page.getByLabel('Price').fill('19.99');
+    await page.getByRole('button', { name: 'Create product' }).click();
+
+    await expect(page.getByText('Product created successfully')).toBeVisible();
+    await page.waitForURL('/products/**');
+  });
+});
+```
+
+### Testing Middleware
+
+**Use when**: Testing Next.js middleware that handles redirects, rewrites, authentication guards, geolocation-based routing, or header manipulation.
+**Avoid when**: The middleware logic is trivial -- a redirect from `/old` to `/new` can be verified with a simple navigation test.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('middleware', () => {
+  test('unauthenticated user is redirected to login', async ({ page }) => {
+    // Visit a protected page without auth cookies
+    const response = await page.goto('/dashboard');
+
+    // Middleware should redirect to /login
+    expect(page.url()).toContain('/login');
+    await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
+  });
+
+  test('middleware redirect preserves the return URL', async ({ page }) => {
+    await page.goto('/dashboard/settings');
+
+    // Should redirect to login with a callbackUrl or returnTo parameter
+    const url = new URL(page.url());
+    expect(url.pathname).toBe('/login');
+    expect(url.searchParams.get('callbackUrl') || url.searchParams.get('returnTo'))
+      .toContain('/dashboard/settings');
+  });
+
+  test('middleware sets security headers', async ({ page }) => {
+    const response = await page.goto('/');
+
+    const headers = response!.headers();
+    expect(headers['x-frame-options']).toBe('DENY');
+    expect(headers['x-content-type-options']).toBe('nosniff');
+    expect(headers['referrer-policy']).toBe('strict-origin-when-cross-origin');
+  });
+
+  test('middleware rewrites based on locale', async ({ page, context }) => {
+    // Set Accept-Language header to simulate a French user
+    await context.setExtraHTTPHeaders({
+      'Accept-Language': 'fr-FR,fr;q=0.9',
+    });
+
+    await page.goto('/');
+
+    // Middleware should rewrite to the French locale
+    await expect(page.getByText('Bienvenue')).toBeVisible();
+  });
+
+  test('middleware blocks unauthorized API access', async ({ request }) => {
+    // Call a protected API route without authentication
+    const response = await request.get('/api/admin/users');
+
+    expect(response.status()).toBe(401);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('middleware', () => {
+  test('unauthenticated user is redirected to login', async ({ page }) => {
+    const response = await page.goto('/dashboard');
+
+    expect(page.url()).toContain('/login');
+    await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
+  });
+
+  test('middleware redirect preserves the return URL', async ({ page }) => {
+    await page.goto('/dashboard/settings');
+
+    const url = new URL(page.url());
+    expect(url.pathname).toBe('/login');
+    expect(url.searchParams.get('callbackUrl') || url.searchParams.get('returnTo'))
+      .toContain('/dashboard/settings');
+  });
+
+  test('middleware sets security headers', async ({ page }) => {
+    const response = await page.goto('/');
+
+    const headers = response.headers();
+    expect(headers['x-frame-options']).toBe('DENY');
+    expect(headers['x-content-type-options']).toBe('nosniff');
+    expect(headers['referrer-policy']).toBe('strict-origin-when-cross-origin');
+  });
+
+  test('middleware rewrites based on locale', async ({ page, context }) => {
+    await context.setExtraHTTPHeaders({
+      'Accept-Language': 'fr-FR,fr;q=0.9',
+    });
+
+    await page.goto('/');
+
+    await expect(page.getByText('Bienvenue')).toBeVisible();
+  });
+
+  test('middleware blocks unauthorized API access', async ({ request }) => {
+    const response = await request.get('/api/admin/users');
+
+    expect(response.status()).toBe(401);
+  });
+});
+```
+
+### Testing Hydration and SSR/CSR Consistency
+
+**Use when**: Verifying that server-rendered HTML matches the client-side hydrated output. Hydration mismatches cause visual flicker, broken interactivity, or React errors in the console.
+**Avoid when**: The page has no interactive client components -- pure server components do not hydrate.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('hydration', () => {
+  test('no hydration errors in console', async ({ page }) => {
+    const consoleErrors: string[] = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        consoleErrors.push(msg.text());
+      }
+    });
+
+    await page.goto('/');
+    // Wait for hydration to complete -- interactive elements become clickable
+    await page.getByRole('button', { name: 'Get started' }).click();
+
+    // Filter for hydration-specific errors
+    const hydrationErrors = consoleErrors.filter(
+      (e) =>
+        e.includes('Hydration') ||
+        e.includes('hydration') ||
+        e.includes('server-rendered') ||
+        e.includes('did not match')
+    );
+    expect(hydrationErrors).toEqual([]);
+  });
+
+  test('interactive elements work after hydration', async ({ page }) => {
+    await page.goto('/');
+
+    // This button relies on a client component event handler
+    // If hydration fails, the click will do nothing
+    const counter = page.getByTestId('counter-value');
+    await expect(counter).toHaveText('0');
+
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await expect(counter).toHaveText('1');
+  });
+
+  test('date/time renders without hydration mismatch', async ({ page }) => {
+    // Dates are a common source of hydration mismatch because server
+    // and client may be in different timezones
+    await page.goto('/dashboard');
+
+    // Verify the date displays without flicker
+    const dateElement = page.getByTestId('current-date');
+    await expect(dateElement).toBeVisible();
+    // Verify it contains a plausible date format, not "undefined" or garbled text
+    await expect(dateElement).toHaveText(/\w+ \d{1,2}, \d{4}/);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('hydration', () => {
+  test('no hydration errors in console', async ({ page }) => {
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        consoleErrors.push(msg.text());
+      }
+    });
+
+    await page.goto('/');
+    await page.getByRole('button', { name: 'Get started' }).click();
+
+    const hydrationErrors = consoleErrors.filter(
+      (e) =>
+        e.includes('Hydration') ||
+        e.includes('hydration') ||
+        e.includes('server-rendered') ||
+        e.includes('did not match')
+    );
+    expect(hydrationErrors).toEqual([]);
+  });
+
+  test('interactive elements work after hydration', async ({ page }) => {
+    await page.goto('/');
+
+    const counter = page.getByTestId('counter-value');
+    await expect(counter).toHaveText('0');
+
+    await page.getByRole('button', { name: 'Increment' }).click();
+    await expect(counter).toHaveText('1');
+  });
+
+  test('date/time renders without hydration mismatch', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    const dateElement = page.getByTestId('current-date');
+    await expect(dateElement).toBeVisible();
+    await expect(dateElement).toHaveText(/\w+ \d{1,2}, \d{4}/);
+  });
+});
+```
+
+### Testing next/image Optimization
+
+**Use when**: Verifying that `next/image` components render correctly, lazy load offscreen images, and serve optimized formats.
+**Avoid when**: You do not use `next/image` or image optimization is not a concern for your test.
+
+**TypeScript**
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('next/image', () => {
+  test('hero image loads with correct attributes', async ({ page }) => {
+    await page.goto('/');
+
+    const heroImage = page.getByRole('img', { name: 'Hero banner' });
+    await expect(heroImage).toBeVisible();
+
+    // Verify next/image sets srcset for responsive loading
+    const srcset = await heroImage.getAttribute('srcset');
+    expect(srcset).toBeTruthy();
+    expect(srcset).toContain('w='); // next/image adds width descriptors
+
+    // Verify priority images are not lazy-loaded
+    const loading = await heroImage.getAttribute('loading');
+    expect(loading).not.toBe('lazy'); // priority images use eager loading
+  });
+
+  test('offscreen images lazy load on scroll', async ({ page }) => {
+    await page.goto('/gallery');
+
+    // Get an image that is below the fold
+    const offscreenImage = page.getByRole('img', { name: 'Gallery item 20' });
+
+    // Before scroll: image should not have loaded its src yet
+    const initialSrc = await offscreenImage.getAttribute('src');
+    // next/image uses a blur placeholder or empty src for lazy images
+
+    // Scroll the image into view
+    await offscreenImage.scrollIntoViewIfNeeded();
+    await expect(offscreenImage).toBeVisible();
+
+    // Verify the image has loaded (naturalWidth > 0 means the image loaded)
+    const naturalWidth = await offscreenImage.evaluate(
+      (img: HTMLImageElement) => img.naturalWidth
+    );
+    expect(naturalWidth).toBeGreaterThan(0);
+  });
+});
+```
+
+**JavaScript**
+```javascript
+const { test, expect } = require('@playwright/test');
+
+test.describe('next/image', () => {
+  test('hero image loads with correct attributes', async ({ page }) => {
+    await page.goto('/');
+
+    const heroImage = page.getByRole('img', { name: 'Hero banner' });
+    await expect(heroImage).toBeVisible();
+
+    const srcset = await heroImage.getAttribute('srcset');
+    expect(srcset).toBeTruthy();
+    expect(srcset).toContain('w=');
+
+    const loading = await heroImage.getAttribute('loading');
+    expect(loading).not.toBe('lazy');
+  });
+
+  test('offscreen images lazy load on scroll', async ({ page }) => {
+    await page.goto('/gallery');
+
+    const offscreenImage = page.getByRole('img', { name: 'Gallery item 20' });
+
+    await offscreenImage.scrollIntoViewIfNeeded();
+    await expect(offscreenImage).toBeVisible();
+
+    const naturalWidth = await offscreenImage.evaluate(
+      (img) => img.naturalWidth
+    );
+    expect(naturalWidth).toBeGreaterThan(0);
+  });
+});
+```
+
+### Authentication with NextAuth.js / Auth.js
+
+**Use when**: Testing login flows in Next.js apps using NextAuth.js or Auth.js. Use a setup project to authenticate once, then reuse `storageState` across tests.
+**Avoid when**: Your app does not use session-based authentication.
+
+**TypeScript**
+```typescript
+// playwright.config.ts (auth-specific excerpt)
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /auth\.setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      use: { storageState: 'playwright/.auth/user.json' },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'unauthenticated',
+      // No storageState -- tests run as logged-out user
+      testMatch: '**/*.unauth.spec.ts',
+    },
+  ],
+});
+```
+
+```typescript
+// tests/auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'playwright/.auth/user.json';
+
+setup('authenticate via credentials', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('test@example.com');
+  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  // Wait for the redirect after successful login
+  await page.waitForURL('/dashboard');
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+
+  // Save authentication state (cookies + localStorage)
+  await page.context().storageState({ path: authFile });
+});
+```
+
+```typescript
+// tests/dashboard.spec.ts
+import { test, expect } from '@playwright/test';
+
+// This test runs with the authenticated storageState from the setup project
+test('authenticated user sees dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // No login redirect -- auth cookies are already set
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+  await expect(page.getByText('test@example.com')).toBeVisible();
+});
+```
+
+**JavaScript**
+```javascript
+// tests/auth.setup.js
+const { test: setup, expect } = require('@playwright/test');
+
+const authFile = 'playwright/.auth/user.json';
+
+setup('authenticate via credentials', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('test@example.com');
+  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await page.waitForURL('/dashboard');
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+
+  await page.context().storageState({ path: authFile });
+});
+```
+
+```javascript
+// tests/dashboard.spec.js
+const { test, expect } = require('@playwright/test');
+
+test('authenticated user sees dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+  await expect(page.getByText('test@example.com')).toBeVisible();
+});
+```
+
+## Framework-Specific Tips
+
+### Dev Server vs Production Build
+
+| Scenario | Command | Trade-off |
+|---|---|---|
+| Local development | `npm run dev` | Hot reload, fast iteration, but does not test production behavior (minification, optimization, middleware edge runtime) |
+| CI pipeline | `npm run build && npm run start` | Tests the real production bundle; catches build errors, middleware edge cases |
+| Quick smoke test | `npm run dev` in CI with `reuseExistingServer: false` | Faster CI but misses production-only bugs |
+
+**Recommendation**: Use `npm run dev` locally for fast feedback. Use `npm run build && npm run start` in CI to test the real production artifact.
+
+### Server Components Cannot Be Tested in Isolation
+
+Next.js server components run on the server and produce HTML. Playwright tests the rendered output. You cannot import and render a server component in a Playwright test. Instead:
+
+1. Test the final rendered HTML through navigation (`page.goto`)
+2. Verify that server-fetched data appears on the page
+3. Use API route tests to validate the data layer separately
+
+### Handling Next.js Redirects
+
+Next.js redirects (configured in `next.config.js`, middleware, or `redirect()` in server actions) are transparent to Playwright. After `page.goto()`, check `page.url()` to verify the final destination.
+
+### Turbopack Compatibility
+
+If using Turbopack (`next dev --turbopack`), update your `webServer.command`:
+
+```typescript
+webServer: {
+  command: process.env.CI
+    ? 'npm run build && npm run start'
+    : 'npx next dev --turbopack',
+  url: 'http://localhost:3000',
+  reuseExistingServer: !process.env.CI,
+},
+```
+
+### Multiple webServer Entries (Next.js + API Backend)
+
+If your Next.js app consumes a separate backend API:
+
+```typescript
+webServer: [
+  {
+    command: 'npm run dev:api',
+    url: 'http://localhost:4000/health',
+    reuseExistingServer: !process.env.CI,
+  },
+  {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+],
+```
+
+## Anti-Patterns
+
+| Don't Do This | Problem | Do This Instead |
+|---|---|---|
+| `await page.waitForTimeout(3000)` after navigation | Next.js client-side transitions are fast; arbitrary waits are wasteful and fragile | `await page.waitForURL('/expected-path')` or `await expect(locator).toBeVisible()` |
+| Test `getServerSideProps` by importing and calling it directly | It depends on `context` (req/res) that Playwright cannot provide; it is a unit test concern | Navigate to the page and verify the rendered output |
+| Mock your own API routes with `page.route()` | You are testing a fiction; your API handler may have bugs the mock hides | Let the real API route handle requests; mock only external services |
+| Use `page.goto('http://localhost:3000/path')` with full URL | Breaks when port or host changes; ignores `baseURL` | Use `page.goto('/path')` and configure `baseURL` in config |
+| Run `npm run build && npm run start` locally for every test run | Extremely slow feedback loop during development | Use `npm run dev` locally with `reuseExistingServer: true`; reserve production builds for CI |
+| Test `next/image` by checking exact URL paths | `next/image` rewrites image URLs through `/_next/image`; paths change between dev and prod | Assert on `alt` text, visibility, `naturalWidth > 0`, and `srcset` existence |
+| Skip `.env.test` and hardcode test values in config | Values scatter across config and test files; hard to maintain | Use `.env.test` for shared test values; `.env.test.local` for secrets |
+| Test server actions by calling them as functions | Server actions are bound to the Next.js runtime; calling them outside a request context fails | Trigger server actions through their UI (form submissions, button clicks) |
+| Ignore console errors during SSR tests | Hydration mismatches and server errors appear in the console and indicate real bugs | Listen for `page.on('console')` errors and fail the test if hydration warnings appear |
+
+## Related
+
+- [core/configuration.md](configuration.md) -- base Playwright configuration patterns including `webServer`
+- [core/authentication.md](authentication.md) -- authentication setup projects and `storageState` reuse
+- [core/api-testing.md](api-testing.md) -- testing API routes directly with `request` context
+- [core/network-mocking.md](network-mocking.md) -- mocking external APIs that Next.js API routes call
+- [core/when-to-mock.md](when-to-mock.md) -- when to mock vs hit real services
+- [core/react.md](react.md) -- React-specific patterns that apply to Next.js client components
+- [ci/ci-github-actions.md](../ci/ci-github-actions.md) -- CI setup with `npm run build` caching for Next.js