zebbern/claude-code-guide / skills/playwright/core
playwright-core
VerifiedBattle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, assertions, fixtures, network mocking, auth flows, debugging, and framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.
error-and-edge-cases.md
View on GitHub# 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |