# 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