# Error States and Edge Cases

> **When to use**: Testing how your application handles errors, failures, boundary conditions, and unusual user behavior. These tests catch bugs that happy-path tests miss.
> **Prerequisites**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/network-mocking.md](network-mocking.md) for route interception

## Quick Reference

```typescript
// Mock a 500 server error
await page.route("**/api/data", (route) => route.fulfill({ status: 500 }))

// Simulate offline mode
await page.context().setOffline(true)

// Test empty state
await page.route("**/api/items", (route) => route.fulfill({ status: 200, json: [] }))

// Browser back/forward
await page.goBack()
await page.goForward()

// Abort a network request (simulate network failure)
await page.route("**/api/save", (route) => route.abort("connectionfailed"))
```

## Patterns

### HTTP Error Status Codes

**Use when**: Testing that your application displays appropriate error pages or messages for 4xx and 5xx responses.
**Avoid when**: The error is handled silently (no user-facing feedback). Test via API or logs instead.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("displays 404 page for missing resources", async ({ page }) => {
  // Navigate directly to a non-existent URL
  await page.goto("/this-page-does-not-exist")

  await expect(page.getByRole("heading", { name: /not found/i })).toBeVisible()
  await expect(page.getByRole("link", { name: "Go home" })).toBeVisible()
})

test("handles 500 server error gracefully", async ({ page }) => {
  // Intercept the API call and return a 500
  await page.route("**/api/dashboard", (route) =>
    route.fulfill({
      status: 500,
      contentType: "application/json",
      body: JSON.stringify({ error: "Internal server error" }),
    })
  )

  await page.goto("/dashboard")

  await expect(page.getByText("Something went wrong")).toBeVisible()
  await expect(page.getByRole("button", { name: "Try again" })).toBeVisible()
})

test("handles 403 forbidden with redirect to login", async ({ page }) => {
  await page.route("**/api/admin/**", (route) => route.fulfill({ status: 403 }))

  await page.goto("/admin/settings")

  // Should redirect to login or show access denied
  await expect(page.getByText(/access denied|not authorized/i)).toBeVisible()
})

test("handles 429 rate limiting", async ({ page }) => {
  await page.route("**/api/search*", (route) =>
    route.fulfill({
      status: 429,
      headers: { "Retry-After": "30" },
      body: JSON.stringify({ error: "Too many requests" }),
    })
  )

  await page.goto("/search")
  await page.getByLabel("Search").fill("test")
  await page.getByRole("button", { name: "Search" }).click()

  await expect(page.getByText(/too many requests|try again later/i)).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("displays 404 page for missing resources", async ({ page }) => {
  await page.goto("/this-page-does-not-exist")

  await expect(page.getByRole("heading", { name: /not found/i })).toBeVisible()
  await expect(page.getByRole("link", { name: "Go home" })).toBeVisible()
})

test("handles 500 server error gracefully", async ({ page }) => {
  await page.route("**/api/dashboard", (route) =>
    route.fulfill({
      status: 500,
      contentType: "application/json",
      body: JSON.stringify({ error: "Internal server error" }),
    })
  )

  await page.goto("/dashboard")

  await expect(page.getByText("Something went wrong")).toBeVisible()
  await expect(page.getByRole("button", { name: "Try again" })).toBeVisible()
})

test("handles 403 forbidden with redirect to login", async ({ page }) => {
  await page.route("**/api/admin/**", (route) => route.fulfill({ status: 403 }))

  await page.goto("/admin/settings")
  await expect(page.getByText(/access denied|not authorized/i)).toBeVisible()
})

test("handles 429 rate limiting", async ({ page }) => {
  await page.route("**/api/search*", (route) =>
    route.fulfill({
      status: 429,
      headers: { "Retry-After": "30" },
      body: JSON.stringify({ error: "Too many requests" }),
    })
  )

  await page.goto("/search")
  await page.getByLabel("Search").fill("test")
  await page.getByRole("button", { name: "Search" }).click()

  await expect(page.getByText(/too many requests|try again later/i)).toBeVisible()
})
```

### Network Failure and Offline Mode

**Use when**: Testing how the app behaves when the network is down, requests fail, or the connection is intermittent.
**Avoid when**: The app has no offline or error handling behavior to test.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("offline mode shows offline banner", async ({ page }) => {
  await page.goto("/dashboard")
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  // Go offline
  await page.context().setOffline(true)

  // Trigger a network-dependent action
  await page.getByRole("button", { name: "Refresh" }).click()

  await expect(page.getByText(/offline|no connection/i)).toBeVisible()

  // Go back online
  await page.context().setOffline(false)

  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByText(/offline|no connection/i)).not.toBeVisible()
})

test("network request failure shows error state", async ({ page }) => {
  // Abort specific requests to simulate network failure
  await page.route("**/api/user/profile", (route) => route.abort("connectionfailed"))

  await page.goto("/profile")

  await expect(page.getByText("Failed to load profile")).toBeVisible()
  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible()
})

test("request timeout shows timeout message", async ({ page }) => {
  // Delay the response beyond the app's timeout threshold
  await page.route("**/api/reports", async (route) => {
    await new Promise((resolve) => setTimeout(resolve, 30_000))
    await route.fulfill({ status: 200, json: { data: [] } })
  })

  await page.goto("/reports")

  // App should show timeout message before Playwright's own timeout
  await expect(page.getByText(/timed out|taking too long/i)).toBeVisible({
    timeout: 20_000,
  })
})

test("intermittent connectivity — request fails then succeeds", async ({ page }) => {
  let requestCount = 0

  await page.route("**/api/data", (route) => {
    requestCount++
    if (requestCount <= 2) {
      return route.abort("connectionfailed")
    }
    return route.fulfill({ status: 200, json: { items: ["a", "b", "c"] } })
  })

  await page.goto("/data")

  // First load fails
  await expect(page.getByText(/failed|error/i)).toBeVisible()

  // User retries — still fails
  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByText(/failed|error/i)).toBeVisible()

  // Third attempt succeeds
  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByRole("listitem")).toHaveCount(3)
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("offline mode shows offline banner", async ({ page }) => {
  await page.goto("/dashboard")
  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()

  await page.context().setOffline(true)

  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByText(/offline|no connection/i)).toBeVisible()

  await page.context().setOffline(false)

  await page.getByRole("button", { name: "Refresh" }).click()
  await expect(page.getByText(/offline|no connection/i)).not.toBeVisible()
})

test("network request failure shows error state", async ({ page }) => {
  await page.route("**/api/user/profile", (route) => route.abort("connectionfailed"))

  await page.goto("/profile")

  await expect(page.getByText("Failed to load profile")).toBeVisible()
  await expect(page.getByRole("button", { name: "Retry" })).toBeVisible()
})

test("intermittent connectivity — request fails then succeeds", async ({ page }) => {
  let requestCount = 0

  await page.route("**/api/data", (route) => {
    requestCount++
    if (requestCount <= 2) {
      return route.abort("connectionfailed")
    }
    return route.fulfill({ status: 200, json: { items: ["a", "b", "c"] } })
  })

  await page.goto("/data")

  await expect(page.getByText(/failed|error/i)).toBeVisible()

  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByText(/failed|error/i)).toBeVisible()

  await page.getByRole("button", { name: "Retry" }).click()
  await expect(page.getByRole("listitem")).toHaveCount(3)
})
```

### Empty States and Boundary Testing

**Use when**: Testing what the UI shows when there is no data, when inputs are at their minimum or maximum values, or when inputs contain special characters.
**Avoid when**: Never. Every feature should have empty state and boundary tests.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("empty state is shown when no items exist", async ({ page }) => {
  // Mock an empty response
  await page.route("**/api/tasks", (route) => route.fulfill({ status: 200, json: [] }))

  await page.goto("/tasks")

  await expect(page.getByText("No tasks yet")).toBeVisible()
  await expect(page.getByRole("link", { name: "Create your first task" })).toBeVisible()

  // List elements should not be present
  await expect(page.getByRole("listitem")).toHaveCount(0)
})

test("handles maximum length input", async ({ page }) => {
  await page.goto("/profile")

  // Fill with max-length string
  const maxLengthName = "A".repeat(255)
  await page.getByLabel("Display name").fill(maxLengthName)
  await page.getByRole("button", { name: "Save" }).click()

  // Verify the name was saved (or truncated, depending on app behavior)
  await expect(page.getByText("Profile updated")).toBeVisible()
})

test("handles special characters in input", async ({ page }) => {
  await page.goto("/search")

  const specialInputs = [
    '<script>alert("xss")</script>',
    '"; DROP TABLE users; --',
    "unicode: \u00e9\u00e0\u00fc\u00f1 \u4f60\u597d \ud83d\ude80",
    "null bytes: \x00\x01\x02",
    "path traversal: ../../etc/passwd",
  ]

  for (const input of specialInputs) {
    await page.getByLabel("Search").fill(input)
    await page.getByRole("button", { name: "Search" }).click()

    // App should not crash — either show results or "no results"
    await expect(page.getByText(/results|no results|no matches/i)).toBeVisible()
  }
})

test("handles zero, one, and many items (0-1-N pattern)", async ({ page }) => {
  // Zero items
  await page.route("**/api/notifications", (route) => route.fulfill({ status: 200, json: [] }))
  await page.goto("/notifications")
  await expect(page.getByText("No notifications")).toBeVisible()

  // One item
  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: [{ id: 1, message: "Welcome!" }],
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem")).toHaveCount(1)
  await expect(page.getByText("No notifications")).not.toBeVisible()

  // Many items — verify pagination or "load more"
  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: Array.from({ length: 50 }, (_, i) => ({
        id: i + 1,
        message: `Notification ${i + 1}`,
      })),
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem").first()).toBeVisible()
  await expect(page.getByRole("button", { name: /load more|show all/i })).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("empty state is shown when no items exist", async ({ page }) => {
  await page.route("**/api/tasks", (route) => route.fulfill({ status: 200, json: [] }))

  await page.goto("/tasks")

  await expect(page.getByText("No tasks yet")).toBeVisible()
  await expect(page.getByRole("link", { name: "Create your first task" })).toBeVisible()
  await expect(page.getByRole("listitem")).toHaveCount(0)
})

test("handles maximum length input", async ({ page }) => {
  await page.goto("/profile")

  const maxLengthName = "A".repeat(255)
  await page.getByLabel("Display name").fill(maxLengthName)
  await page.getByRole("button", { name: "Save" }).click()

  await expect(page.getByText("Profile updated")).toBeVisible()
})

test("handles special characters in input", async ({ page }) => {
  await page.goto("/search")

  const specialInputs = [
    '<script>alert("xss")</script>',
    '"; DROP TABLE users; --',
    "unicode: \u00e9\u00e0\u00fc\u00f1 \u4f60\u597d \ud83d\ude80",
    "path traversal: ../../etc/passwd",
  ]

  for (const input of specialInputs) {
    await page.getByLabel("Search").fill(input)
    await page.getByRole("button", { name: "Search" }).click()

    await expect(page.getByText(/results|no results|no matches/i)).toBeVisible()
  }
})

test("handles zero, one, and many items (0-1-N pattern)", async ({ page }) => {
  await page.route("**/api/notifications", (route) => route.fulfill({ status: 200, json: [] }))
  await page.goto("/notifications")
  await expect(page.getByText("No notifications")).toBeVisible()

  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: [{ id: 1, message: "Welcome!" }],
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem")).toHaveCount(1)

  await page.route("**/api/notifications", (route) =>
    route.fulfill({
      status: 200,
      json: Array.from({ length: 50 }, (_, i) => ({
        id: i + 1,
        message: `Notification ${i + 1}`,
      })),
    })
  )
  await page.reload()
  await expect(page.getByRole("listitem").first()).toBeVisible()
  await expect(page.getByRole("button", { name: /load more|show all/i })).toBeVisible()
})
```

### Loading States and Skeletons

**Use when**: Verifying that loading indicators, skeleton screens, or spinners appear during data fetching and disappear when data arrives.
**Avoid when**: The application renders synchronously with no loading indicators (SSR without client-side fetching).

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("loading skeleton appears and resolves", async ({ page }) => {
  // Delay the API response to observe the loading state
  let resolveResponse: () => void
  const responseReady = new Promise<void>((resolve) => {
    resolveResponse = resolve
  })

  await page.route("**/api/dashboard", async (route) => {
    await responseReady
    await route.fulfill({
      status: 200,
      json: { revenue: 12400, users: 350 },
    })
  })

  await page.goto("/dashboard")

  // Skeleton should be visible while loading
  await expect(page.getByTestId("skeleton-revenue")).toBeVisible()
  await expect(page.getByTestId("skeleton-users")).toBeVisible()

  // Real content should not be visible yet
  await expect(page.getByText("$12,400")).not.toBeVisible()

  // Release the response
  resolveResponse!()

  // Skeleton disappears, real content appears
  await expect(page.getByTestId("skeleton-revenue")).not.toBeVisible()
  await expect(page.getByText("$12,400")).toBeVisible()
  await expect(page.getByText("350")).toBeVisible()
})

test("spinner shown during form submission", async ({ page }) => {
  let resolveSubmit: () => void
  const submitReady = new Promise<void>((resolve) => {
    resolveSubmit = resolve
  })

  await page.route("**/api/contact", async (route) => {
    await submitReady
    await route.fulfill({ status: 200, json: { success: true } })
  })

  await page.goto("/contact")
  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")

  await page.getByRole("button", { name: "Send" }).click()

  // Loading spinner/state during submission
  await expect(page.getByRole("button", { name: /sending/i })).toBeVisible()
  await expect(page.getByRole("button", { name: /sending/i })).toBeDisabled()

  // Complete the submission
  resolveSubmit!()

  await expect(page.getByText("Message sent")).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("loading skeleton appears and resolves", async ({ page }) => {
  let resolveResponse
  const responseReady = new Promise((resolve) => {
    resolveResponse = resolve
  })

  await page.route("**/api/dashboard", async (route) => {
    await responseReady
    await route.fulfill({
      status: 200,
      json: { revenue: 12400, users: 350 },
    })
  })

  await page.goto("/dashboard")

  await expect(page.getByTestId("skeleton-revenue")).toBeVisible()
  await expect(page.getByTestId("skeleton-users")).toBeVisible()
  await expect(page.getByText("$12,400")).not.toBeVisible()

  resolveResponse()

  await expect(page.getByTestId("skeleton-revenue")).not.toBeVisible()
  await expect(page.getByText("$12,400")).toBeVisible()
  await expect(page.getByText("350")).toBeVisible()
})

test("spinner shown during form submission", async ({ page }) => {
  let resolveSubmit
  const submitReady = new Promise((resolve) => {
    resolveSubmit = resolve
  })

  await page.route("**/api/contact", async (route) => {
    await submitReady
    await route.fulfill({ status: 200, json: { success: true } })
  })

  await page.goto("/contact")
  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")

  await page.getByRole("button", { name: "Send" }).click()

  await expect(page.getByRole("button", { name: /sending/i })).toBeVisible()
  await expect(page.getByRole("button", { name: /sending/i })).toBeDisabled()

  resolveSubmit()

  await expect(page.getByText("Message sent")).toBeVisible()
})
```

### Retry Behavior Testing

**Use when**: Testing that the application retries failed requests automatically or via a user-triggered "retry" button.
**Avoid when**: The application has no retry mechanism.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("retry button recovers from a failed API call", async ({ page }) => {
  let callCount = 0

  await page.route("**/api/feed", (route) => {
    callCount++
    if (callCount === 1) {
      return route.fulfill({ status: 500 })
    }
    return route.fulfill({
      status: 200,
      json: { posts: [{ id: 1, title: "Hello World" }] },
    })
  })

  await page.goto("/feed")

  // First load fails
  await expect(page.getByText(/something went wrong/i)).toBeVisible()

  // Click retry — second call succeeds
  await page.getByRole("button", { name: "Try again" }).click()

  await expect(page.getByText("Hello World")).toBeVisible()
  expect(callCount).toBe(2)
})

test("automatic retry with exponential backoff", async ({ page }) => {
  const callTimestamps: number[] = []

  await page.route("**/api/status", (route) => {
    callTimestamps.push(Date.now())
    if (callTimestamps.length <= 3) {
      return route.fulfill({ status: 503 })
    }
    return route.fulfill({ status: 200, json: { status: "ok" } })
  })

  await page.goto("/status")

  // Wait for the auto-retry to eventually succeed
  await expect(page.getByText("System operational")).toBeVisible({
    timeout: 30_000,
  })

  // Verify multiple retry attempts were made
  expect(callTimestamps.length).toBeGreaterThanOrEqual(4)

  // Verify backoff: gaps between retries should increase
  if (callTimestamps.length >= 3) {
    const gap1 = callTimestamps[1] - callTimestamps[0]
    const gap2 = callTimestamps[2] - callTimestamps[1]
    expect(gap2).toBeGreaterThanOrEqual(gap1)
  }
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("retry button recovers from a failed API call", async ({ page }) => {
  let callCount = 0

  await page.route("**/api/feed", (route) => {
    callCount++
    if (callCount === 1) {
      return route.fulfill({ status: 500 })
    }
    return route.fulfill({
      status: 200,
      json: { posts: [{ id: 1, title: "Hello World" }] },
    })
  })

  await page.goto("/feed")

  await expect(page.getByText(/something went wrong/i)).toBeVisible()

  await page.getByRole("button", { name: "Try again" }).click()

  await expect(page.getByText("Hello World")).toBeVisible()
  expect(callCount).toBe(2)
})

test("automatic retry with exponential backoff", async ({ page }) => {
  const callTimestamps = []

  await page.route("**/api/status", (route) => {
    callTimestamps.push(Date.now())
    if (callTimestamps.length <= 3) {
      return route.fulfill({ status: 503 })
    }
    return route.fulfill({ status: 200, json: { status: "ok" } })
  })

  await page.goto("/status")

  await expect(page.getByText("System operational")).toBeVisible({
    timeout: 30_000,
  })

  expect(callTimestamps.length).toBeGreaterThanOrEqual(4)
})
```

### Browser Back/Forward Navigation

**Use when**: Testing that the application handles browser history navigation correctly — preserving state, URL updates, and content after going back or forward.
**Avoid when**: The app is a single-page application that does not use the browser history API. Focus on client-side routing tests instead.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("browser back preserves navigation context", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  // Go back
  await page.goBack()

  await expect(page).toHaveURL(/\/products$/)
  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
})

test("browser forward returns to previous page", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  await page.goBack()
  await page.goForward()

  await expect(page).toHaveURL(/\/products\/running-shoes/)
  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
})

test("form state after browser back", async ({ page }) => {
  await page.goto("/checkout")

  // Fill form on step 1
  await page.getByLabel("Address").fill("123 Main St")
  await page.getByRole("button", { name: "Continue" }).click()

  // Arrived at step 2
  await expect(page.getByRole("heading", { name: "Payment" })).toBeVisible()

  // Go back to step 1
  await page.goBack()

  // Data should be preserved (depends on app implementation)
  await expect(page.getByLabel("Address")).toHaveValue("123 Main St")
})

test("back button after form submission does not re-submit", async ({ page }) => {
  await page.goto("/contact")

  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")
  await page.getByRole("button", { name: "Send" }).click()

  await expect(page.getByText("Message sent")).toBeVisible()

  // Going back should show the form, not re-submit
  await page.goBack()
  await expect(page.getByLabel("Name")).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("browser back preserves navigation context", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  await page.goBack()

  await expect(page).toHaveURL(/\/products$/)
  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
})

test("browser forward returns to previous page", async ({ page }) => {
  await page.goto("/products")
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await page.waitForURL("**/products/running-shoes")

  await page.goBack()
  await page.goForward()

  await expect(page).toHaveURL(/\/products\/running-shoes/)
  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
})

test("form state after browser back", async ({ page }) => {
  await page.goto("/checkout")

  await page.getByLabel("Address").fill("123 Main St")
  await page.getByRole("button", { name: "Continue" }).click()

  await expect(page.getByRole("heading", { name: "Payment" })).toBeVisible()

  await page.goBack()
  await expect(page.getByLabel("Address")).toHaveValue("123 Main St")
})

test("back button after form submission does not re-submit", async ({ page }) => {
  await page.goto("/contact")

  await page.getByLabel("Name").fill("Jane")
  await page.getByLabel("Email").fill("jane@example.com")
  await page.getByLabel("Message").fill("Test")
  await page.getByRole("button", { name: "Send" }).click()

  await expect(page.getByText("Message sent")).toBeVisible()

  await page.goBack()
  await expect(page.getByLabel("Name")).toBeVisible()
})
```

### Concurrent User Actions

**Use when**: Testing that rapid user interactions do not cause race conditions — double-clicking submit, typing while data is loading, navigating during an async operation.
**Avoid when**: The UI has no async operations that could conflict with user actions.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("double-click submit does not create duplicate entries", async ({ page }) => {
  const requests: string[] = []

  await page.route("**/api/orders", (route) => {
    requests.push(route.request().method())
    return route.fulfill({
      status: 201,
      json: { id: 1, status: "created" },
    })
  })

  await page.goto("/checkout")
  await page.getByLabel("Item").fill("Widget")

  const submitButton = page.getByRole("button", { name: "Place order" })

  // Rapid double-click
  await submitButton.dblclick()

  // Wait for the result
  await expect(page.getByText("Order confirmed")).toBeVisible()

  // The app should prevent duplicate submissions
  // (button disabled after first click, or server deduplication)
  expect(requests.filter((m) => m === "POST").length).toBeLessThanOrEqual(1)
})

test("typing during navigation does not crash", async ({ page }) => {
  await page.goto("/search")

  // Start typing and immediately navigate
  await page.getByLabel("Search").pressSequentially("test query", { delay: 30 })
  await page.getByRole("link", { name: "Home" }).click()

  // Should arrive at home page without errors
  await page.waitForURL("**/")
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
})

test("rapid filter changes use latest value", async ({ page }) => {
  const requestUrls: string[] = []

  await page.route("**/api/products*", (route) => {
    requestUrls.push(route.request().url())
    return route.fulfill({
      status: 200,
      json: { products: [{ name: "Latest result" }] },
    })
  })

  await page.goto("/products")

  // Rapidly change the filter
  await page.getByLabel("Category").selectOption("electronics")
  await page.getByLabel("Category").selectOption("clothing")
  await page.getByLabel("Category").selectOption("books")

  // Wait for the final result
  await expect(page.getByText("Latest result")).toBeVisible()

  // The UI should show results for "books", not an earlier selection
  // Some apps debounce; some cancel in-flight requests
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("double-click submit does not create duplicate entries", async ({ page }) => {
  const requests = []

  await page.route("**/api/orders", (route) => {
    requests.push(route.request().method())
    return route.fulfill({
      status: 201,
      json: { id: 1, status: "created" },
    })
  })

  await page.goto("/checkout")
  await page.getByLabel("Item").fill("Widget")

  const submitButton = page.getByRole("button", { name: "Place order" })
  await submitButton.dblclick()

  await expect(page.getByText("Order confirmed")).toBeVisible()

  expect(requests.filter((m) => m === "POST").length).toBeLessThanOrEqual(1)
})

test("typing during navigation does not crash", async ({ page }) => {
  await page.goto("/search")

  await page.getByLabel("Search").pressSequentially("test query", { delay: 30 })
  await page.getByRole("link", { name: "Home" }).click()

  await page.waitForURL("**/")
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
})

test("rapid filter changes use latest value", async ({ page }) => {
  const requestUrls = []

  await page.route("**/api/products*", (route) => {
    requestUrls.push(route.request().url())
    return route.fulfill({
      status: 200,
      json: { products: [{ name: "Latest result" }] },
    })
  })

  await page.goto("/products")

  await page.getByLabel("Category").selectOption("electronics")
  await page.getByLabel("Category").selectOption("clothing")
  await page.getByLabel("Category").selectOption("books")

  await expect(page.getByText("Latest result")).toBeVisible()
})
```

### Graceful Degradation

**Use when**: Testing that the app continues to function when non-critical services fail (analytics, chat widget, recommendations).
**Avoid when**: The failing service is critical to the core workflow.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("page works when analytics service fails", async ({ page }) => {
  // Block analytics and tracking scripts
  await page.route("**/analytics/**", (route) => route.abort())
  await page.route("**/tracking/**", (route) => route.abort())

  await page.goto("/products")

  // Core functionality still works
  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()
})

test("page works when recommendation engine fails", async ({ page }) => {
  await page.route("**/api/recommendations", (route) => route.fulfill({ status: 500 }))

  await page.goto("/products/running-shoes")

  // Main product content loads
  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()

  // Recommendations section shows fallback
  await expect(page.getByText(/recommendations unavailable|you may also like/i)).toBeVisible()
})

test("page works when third-party chat widget fails to load", async ({ page }) => {
  // Block the chat widget script
  await page.route("**/chat-widget.js", (route) => route.abort())

  await page.goto("/support")

  // Core support page loads
  await expect(page.getByRole("heading", { name: "Help Center" })).toBeVisible()

  // No console errors from the blocked widget should crash the page
  const errors: string[] = []
  page.on("pageerror", (error) => errors.push(error.message))

  // Navigate around to ensure no cascade failures
  await page.getByRole("link", { name: "FAQ" }).click()
  await expect(page.getByRole("heading", { name: "FAQ" })).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("page works when analytics service fails", async ({ page }) => {
  await page.route("**/analytics/**", (route) => route.abort())
  await page.route("**/tracking/**", (route) => route.abort())

  await page.goto("/products")

  await expect(page.getByRole("heading", { name: "Products" })).toBeVisible()
  await page.getByRole("link", { name: "Running Shoes" }).click()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()
})

test("page works when recommendation engine fails", async ({ page }) => {
  await page.route("**/api/recommendations", (route) => route.fulfill({ status: 500 }))

  await page.goto("/products/running-shoes")

  await expect(page.getByRole("heading", { name: "Running Shoes" })).toBeVisible()
  await expect(page.getByRole("button", { name: "Add to cart" })).toBeEnabled()
})

test("page works when third-party chat widget fails to load", async ({ page }) => {
  await page.route("**/chat-widget.js", (route) => route.abort())

  await page.goto("/support")

  await expect(page.getByRole("heading", { name: "Help Center" })).toBeVisible()

  await page.getByRole("link", { name: "FAQ" }).click()
  await expect(page.getByRole("heading", { name: "FAQ" })).toBeVisible()
})
```

## Decision Guide

| Scenario                 | Approach                                                      | Key API                                                         |
| ------------------------ | ------------------------------------------------------------- | --------------------------------------------------------------- |
| 404 page                 | Navigate to non-existent URL, assert error page               | `page.goto('/nonexistent')`                                     |
| 500 server error         | Mock route with `status: 500`                                 | `page.route(url, route => route.fulfill({ status: 500 }))`      |
| Network failure          | Abort the route                                               | `route.abort('connectionfailed')`                               |
| Offline mode             | Toggle offline on the browser context                         | `page.context().setOffline(true)`                               |
| Slow response            | Delay route fulfillment with a Promise                        | `await new Promise(r => setTimeout(r, delay))` in route handler |
| Empty state              | Mock API to return empty array                                | `route.fulfill({ json: [] })`                                   |
| Boundary values          | Fill inputs with min/max/special values                       | `locator.fill('A'.repeat(255))`                                 |
| Loading skeleton         | Delay route, assert skeleton visible, release, assert content | Promise-based route handler                                     |
| Retry behavior           | Track route call count, fail first N, succeed after           | Counter in route handler                                        |
| Browser history          | Use `page.goBack()` and `page.goForward()`                    | Assert URL and content after navigation                         |
| Double submit            | `dblclick()` on submit, verify single POST                    | Track requests in route handler                                 |
| Third-party failure      | Abort non-critical routes, verify core works                  | `route.abort()` on optional services                            |
| Console error monitoring | Listen for `pageerror` event                                  | `page.on('pageerror', handler)`                                 |

## Anti-Patterns

| Don't Do This                                          | Problem                                                                        | Do This Instead                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| Only testing the happy path                            | Real users hit errors. Errors in production are more expensive than test time. | Add error/edge case tests for every feature                               |
| `page.route('**/*', route => route.abort())`           | Blocks ALL requests including the page itself                                  | Target specific URLs: `page.route('**/api/specific', ...)`                |
| Using `page.waitForTimeout()` to simulate slow loading | Arbitrary, flaky, slows tests                                                  | Use promise-based route handlers to control timing precisely              |
| Hardcoding error messages in assertions                | Messages change. Tests break on copy edits.                                    | Use regex or partial matches: `getByText(/error/i)`                       |
| Testing every error code in one mega-test              | Hard to debug, slow, first failure hides the rest                              | One test per error scenario, or use `test.describe` groups                |
| Skipping empty state tests                             | Empty states are the first thing new users see; often broken                   | Always test 0-item state alongside 1-item and N-item                      |
| Testing offline by disconnecting real network          | Flaky, affects parallel tests, CI may not support it                           | Use `context.setOffline(true)` — deterministic and scoped                 |
| Not cleaning up route mocks between tests              | Routes persist on the page. Test B inherits test A's mocks.                    | Each test sets its own routes; Playwright resets between tests by default |
| Asserting on exact error strings from the server       | Couples tests to backend implementation details                                | Assert the UI message, not the raw API response body                      |
| Using `try/catch` to "handle" expected errors          | Swallows real bugs; test passes when it shouldn't                              | Let errors propagate; use route mocking to control the response           |

## Troubleshooting

### Route handler is not intercepting requests

**Cause**: The URL pattern does not match, or the route was registered after the navigation that triggers the request.

```typescript
// Always register routes BEFORE navigating
await page.route("**/api/data", (route) => route.fulfill({ status: 500 }))
await page.goto("/dashboard") // route is active before the page loads

// Debug: log all requests to find the actual URL pattern
page.on("request", (req) => console.log(req.url()))
```

### `context.setOffline(true)` does not affect Service Worker

**Cause**: Service Workers have their own network handling. `setOffline` simulates offline at the browser level, but a Service Worker may serve cached responses.

```typescript
// Unregister service workers first
await page.evaluate(async () => {
  const registrations = await navigator.serviceWorker.getRegistrations()
  for (const registration of registrations) {
    await registration.unregister()
  }
})
await page.context().setOffline(true)
```

### Delayed route handler causes test timeout

**Cause**: The promise in the route handler never resolves, or the delay exceeds the test timeout.

```typescript
// Always ensure the delay is less than the assertion timeout
await page.route("**/api/slow", async (route) => {
  await new Promise((resolve) => setTimeout(resolve, 5_000)) // 5s delay
  await route.fulfill({ status: 200, json: {} })
})

// Increase assertion timeout to account for the artificial delay
await expect(page.getByText("Data loaded")).toBeVisible({ timeout: 10_000 })
```

### `goBack()` does not navigate

**Cause**: There is no history entry to go back to. `goBack()` requires at least one previous navigation.

```typescript
// Ensure there is history before calling goBack
await page.goto("/page-a")
await page.goto("/page-b")
await page.goBack() // goes to /page-a

// If using SPA client-side routing, goBack may not work if the router
// does not push to browser history. Use the app's own back button instead.
await page.getByRole("button", { name: "Back" }).click()
```

## Related

- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- assertion strategies for error states
- [core/network-mocking.md](network-mocking.md) -- detailed network interception and mocking patterns
- [core/forms-and-validation.md](forms-and-validation.md) -- form validation error testing
- [core/flaky-tests.md](flaky-tests.md) -- fixing timing issues in error/edge case tests
- [core/service-workers-and-pwa.md](service-workers-and-pwa.md) -- offline-first and PWA testing patterns
- [core/multi-context-and-popups.md](multi-context-and-popups.md) -- testing concurrent browser contexts