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.
mobile-and-responsive.md
View on GitHub# Mobile and Responsive Testing
> **When to use**: Testing how your application behaves on phones, tablets, and across viewport sizes. Covers device emulation, touch interactions, geolocation, orientation changes, and mobile-specific UI patterns.
> **Prerequisites**: [core/configuration.md](configuration.md), [core/locators.md](locators.md)
## Quick Reference
```typescript
import { devices } from "@playwright/test"
// Predefined device profiles (viewport, userAgent, touch, deviceScaleFactor)
devices["iPhone 14"] // 390x844, touch, Safari mobile UA
devices["iPhone 14 Pro Max"] // 430x932, touch, Safari mobile UA
devices["Pixel 7"] // 412x915, touch, Chrome mobile UA
devices["iPad Pro 11"] // 834x1194, touch, Safari tablet UA
devices["Galaxy S9+"] // 320x658, touch, Chrome mobile UA
devices["Desktop Chrome"] // 1280x720, no touch, Chrome desktop UA
devices["Desktop Safari"] // 1280x720, no touch, Safari desktop UA
// Landscape variants
devices["iPhone 14 landscape"] // 844x390, touch, Safari mobile UA
devices["iPad Pro 11 landscape"] // 1194x834, touch, Safari tablet UA
```
```bash
# Run mobile project only
npx playwright test --project=mobile-chrome
npx playwright test --project=mobile-safari
# Run all projects (desktop + mobile in parallel)
npx playwright test
# List available device names
npx playwright test --list-devices 2>/dev/null || node -e "const {devices}=require('@playwright/test');console.log(Object.keys(devices).join('\n'))"
```
## Patterns
### 1. Device Emulation
**Use when**: Testing your app as it appears on a specific real-world device -- iPhone, Pixel, iPad. Applies the correct viewport, user agent, device scale factor, and touch support in one shot.
**Avoid when**: You only need to test a specific viewport width (use custom viewports instead). Device emulation is not a substitute for real device testing when pixel-perfect rendering matters.
#### TypeScript
```typescript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
projects: [
{
name: "Desktop Chrome",
use: { ...devices["Desktop Chrome"] },
},
{
name: "Mobile Chrome",
use: { ...devices["Pixel 7"] },
},
{
name: "Mobile Safari",
use: { ...devices["iPhone 14"] },
},
{
name: "Tablet",
use: { ...devices["iPad Pro 11"] },
},
],
})
```
```typescript
// tests/mobile-navigation.spec.ts
import { test, expect } from "@playwright/test"
test("mobile user can navigate via hamburger menu", async ({ page, isMobile }) => {
await page.goto("/")
if (isMobile) {
// Mobile: hamburger menu is visible, desktop nav is hidden
await expect(page.getByRole("button", { name: "Menu" })).toBeVisible()
await expect(page.getByRole("navigation", { name: "Main" })).toBeHidden()
// Open hamburger menu
await page.getByRole("button", { name: "Menu" }).click()
await expect(page.getByRole("navigation", { name: "Main" })).toBeVisible()
await page.getByRole("link", { name: "Products" }).click()
await page.waitForURL("**/products")
} else {
// Desktop: nav links are directly visible
await expect(page.getByRole("navigation", { name: "Main" })).toBeVisible()
await page.getByRole("link", { name: "Products" }).click()
await page.waitForURL("**/products")
}
await expect(page.getByRole("heading", { name: "Products", level: 1 })).toBeVisible()
})
```
#### JavaScript
```javascript
// playwright.config.js
const { defineConfig, devices } = require("@playwright/test")
module.exports = defineConfig({
testDir: "./tests",
projects: [
{
name: "Desktop Chrome",
use: { ...devices["Desktop Chrome"] },
},
{
name: "Mobile Chrome",
use: { ...devices["Pixel 7"] },
},
{
name: "Mobile Safari",
use: { ...devices["iPhone 14"] },
},
{
name: "Tablet",
use: { ...devices["iPad Pro 11"] },
},
],
})
```
```javascript
// tests/mobile-navigation.spec.js
const { test, expect } = require("@playwright/test")
test("mobile user can navigate via hamburger menu", async ({ page, isMobile }) => {
await page.goto("/")
if (isMobile) {
await expect(page.getByRole("button", { name: "Menu" })).toBeVisible()
await expect(page.getByRole("navigation", { name: "Main" })).toBeHidden()
await page.getByRole("button", { name: "Menu" }).click()
await expect(page.getByRole("navigation", { name: "Main" })).toBeVisible()
await page.getByRole("link", { name: "Products" }).click()
await page.waitForURL("**/products")
} else {
await expect(page.getByRole("navigation", { name: "Main" })).toBeVisible()
await page.getByRole("link", { name: "Products" }).click()
await page.waitForURL("**/products")
}
await expect(page.getByRole("heading", { name: "Products", level: 1 })).toBeVisible()
})
```
### 2. Custom Viewports
**Use when**: Testing responsive layouts at specific breakpoints without full device emulation. Ideal for verifying CSS media queries fire at the right widths.
**Avoid when**: You need realistic mobile behavior (touch events, mobile user agent, device scale factor). Use device emulation instead.
#### TypeScript
```typescript
// tests/responsive-layout.spec.ts
import { test, expect } from "@playwright/test"
const breakpoints = [
{ name: "mobile-small", width: 320, height: 568 },
{ name: "mobile", width: 375, height: 667 },
{ name: "tablet", width: 768, height: 1024 },
{ name: "desktop", width: 1024, height: 768 },
{ name: "desktop-large", width: 1440, height: 900 },
]
for (const bp of breakpoints) {
test(`layout adapts correctly at ${bp.name} (${bp.width}px)`, async ({ page }) => {
await page.setViewportSize({ width: bp.width, height: bp.height })
await page.goto("/")
if (bp.width < 768) {
// Mobile layout: stacked, hamburger menu visible
await expect(page.getByRole("button", { name: "Menu" })).toBeVisible()
await expect(page.getByTestId("sidebar")).toBeHidden()
} else if (bp.width < 1024) {
// Tablet layout: collapsible sidebar
await expect(page.getByRole("button", { name: "Menu" })).toBeHidden()
await expect(page.getByTestId("sidebar")).toBeVisible()
} else {
// Desktop layout: full sidebar, no hamburger
await expect(page.getByRole("button", { name: "Menu" })).toBeHidden()
await expect(page.getByTestId("sidebar")).toBeVisible()
await expect(page.getByTestId("sidebar")).toHaveCSS("width", "280px")
}
})
}
```
```typescript
// Per-file viewport override (applies to all tests in this file)
import { test, expect } from "@playwright/test"
test.use({ viewport: { width: 375, height: 667 } })
test("mobile checkout flow fits on small screen", async ({ page }) => {
await page.goto("/checkout")
// Verify no horizontal scrollbar
const hasHorizontalScroll = await page.evaluate(
() => document.documentElement.scrollWidth > document.documentElement.clientWidth
)
expect(hasHorizontalScroll).toBe(false)
// Verify all form fields are visible without horizontal scroll
await expect(page.getByLabel("Card number")).toBeVisible()
await expect(page.getByRole("button", { name: "Pay now" })).toBeVisible()
})
```
#### JavaScript
```javascript
// tests/responsive-layout.spec.js
const { test, expect } = require("@playwright/test")
const breakpoints = [
{ name: "mobile-small", width: 320, height: 568 },
{ name: "mobile", width: 375, height: 667 },
{ name: "tablet", width: 768, height: 1024 },
{ name: "desktop", width: 1024, height: 768 },
{ name: "desktop-large", width: 1440, height: 900 },
]
for (const bp of breakpoints) {
test(`layout adapts correctly at ${bp.name} (${bp.width}px)`, async ({ page }) => {
await page.setViewportSize({ width: bp.width, height: bp.height })
await page.goto("/")
if (bp.width < 768) {
await expect(page.getByRole("button", { name: "Menu" })).toBeVisible()
await expect(page.getByTestId("sidebar")).toBeHidden()
} else if (bp.width < 1024) {
await expect(page.getByRole("button", { name: "Menu" })).toBeHidden()
await expect(page.getByTestId("sidebar")).toBeVisible()
} else {
await expect(page.getByRole("button", { name: "Menu" })).toBeHidden()
await expect(page.getByTestId("sidebar")).toBeVisible()
await expect(page.getByTestId("sidebar")).toHaveCSS("width", "280px")
}
})
}
```
```javascript
// Per-file viewport override
const { test, expect } = require("@playwright/test")
test.use({ viewport: { width: 375, height: 667 } })
test("mobile checkout flow fits on small screen", async ({ page }) => {
await page.goto("/checkout")
const hasHorizontalScroll = await page.evaluate(
() => document.documentElement.scrollWidth > document.documentElement.clientWidth
)
expect(hasHorizontalScroll).toBe(false)
await expect(page.getByLabel("Card number")).toBeVisible()
await expect(page.getByRole("button", { name: "Pay now" })).toBeVisible()
})
```
### 3. Touch Events
**Use when**: Testing touch-specific interactions -- tap, swipe, pinch. Required for mobile-only gestures that have no mouse equivalent.
**Avoid when**: The feature works identically with mouse clicks. Playwright's `click()` dispatches touch events automatically on touch-enabled device profiles.
#### TypeScript
```typescript
// tests/touch-interactions.spec.ts
import { test, expect, devices } from "@playwright/test"
test.use({ ...devices["iPhone 14"] })
test("tap to select an item", async ({ page }) => {
await page.goto("/gallery")
// tap() dispatches touchstart → touchend → click
// Only available when hasTouch is true (device profiles set this)
await page.getByRole("img", { name: "Sunset photo" }).tap()
await expect(page.getByText("Selected: Sunset photo")).toBeVisible()
})
test("swipe to dismiss a card", async ({ page }) => {
await page.goto("/notifications")
const card = page.getByTestId("notification-card").first()
const box = await card.boundingBox()
if (box) {
// Simulate a left swipe: touchstart on right side, touchmove to left, touchend
await page.touchscreen.tap(box.x + box.width - 20, box.y + box.height / 2)
// Swipe gesture using mouse (touch events are synthesized from mouse on emulated devices)
await card.hover({ position: { x: box.width - 20, y: box.height / 2 } })
await page.mouse.down()
await page.mouse.move(box.x - 100, box.y + box.height / 2, { steps: 10 })
await page.mouse.up()
await expect(card).toBeHidden()
}
})
test("long press to open context menu", async ({ page }) => {
await page.goto("/files")
const file = page.getByRole("listitem").filter({ hasText: "Report.pdf" })
// Long press: dispatch pointerdown, wait, then pointerup
await file.click({ delay: 800 }) // delay in ms simulates long press
await expect(page.getByRole("menu")).toBeVisible()
await page.getByRole("menuitem", { name: "Delete" }).click()
})
test("pinch to zoom on a map", async ({ page }) => {
await page.goto("/map")
// Pinch-to-zoom requires dispatching multi-touch events via JavaScript
const mapElement = page.getByTestId("map-container")
await mapElement.evaluate((el) => {
// Simulate pinch-out (zoom in) with two touch points moving apart
const center = { x: el.clientWidth / 2, y: el.clientHeight / 2 }
const touch1 = new Touch({
identifier: 0,
target: el,
clientX: center.x - 50,
clientY: center.y,
})
const touch2 = new Touch({
identifier: 1,
target: el,
clientX: center.x + 50,
clientY: center.y,
})
el.dispatchEvent(
new TouchEvent("touchstart", {
touches: [touch1, touch2],
changedTouches: [touch1, touch2],
bubbles: true,
})
)
const touch1Moved = new Touch({
identifier: 0,
target: el,
clientX: center.x - 120,
clientY: center.y,
})
const touch2Moved = new Touch({
identifier: 1,
target: el,
clientX: center.x + 120,
clientY: center.y,
})
el.dispatchEvent(
new TouchEvent("touchmove", {
touches: [touch1Moved, touch2Moved],
changedTouches: [touch1Moved, touch2Moved],
bubbles: true,
})
)
el.dispatchEvent(
new TouchEvent("touchend", {
touches: [],
changedTouches: [touch1Moved, touch2Moved],
bubbles: true,
})
)
})
// Verify zoom level changed
await expect(page.getByTestId("zoom-level")).not.toHaveText("1x")
})
```
#### JavaScript
```javascript
// tests/touch-interactions.spec.js
const { test, expect, devices } = require("@playwright/test")
test.use({ ...devices["iPhone 14"] })
test("tap to select an item", async ({ page }) => {
await page.goto("/gallery")
await page.getByRole("img", { name: "Sunset photo" }).tap()
await expect(page.getByText("Selected: Sunset photo")).toBeVisible()
})
test("swipe to dismiss a card", async ({ page }) => {
await page.goto("/notifications")
const card = page.getByTestId("notification-card").first()
const box = await card.boundingBox()
if (box) {
await card.hover({ position: { x: box.width - 20, y: box.height / 2 } })
await page.mouse.down()
await page.mouse.move(box.x - 100, box.y + box.height / 2, { steps: 10 })
await page.mouse.up()
await expect(card).toBeHidden()
}
})
test("long press to open context menu", async ({ page }) => {
await page.goto("/files")
const file = page.getByRole("listitem").filter({ hasText: "Report.pdf" })
await file.click({ delay: 800 })
await expect(page.getByRole("menu")).toBeVisible()
await page.getByRole("menuitem", { name: "Delete" }).click()
})
```
### 4. Mobile-Specific UI
**Use when**: Testing UI components that only appear on mobile -- hamburger menus, bottom sheets, pull-to-refresh, sticky mobile headers, floating action buttons.
**Avoid when**: The component renders identically on desktop and mobile.
#### TypeScript
```typescript
// tests/mobile-ui.spec.ts
import { test, expect, devices } from "@playwright/test"
test.use({ ...devices["iPhone 14"] })
test("hamburger menu opens and closes", async ({ page }) => {
await page.goto("/")
const menuButton = page.getByRole("button", { name: "Menu" })
const nav = page.getByRole("navigation", { name: "Main" })
// Menu starts closed
await expect(nav).toBeHidden()
// Open menu
await menuButton.click()
await expect(nav).toBeVisible()
// Verify all nav items are visible
await expect(nav.getByRole("link", { name: "Home" })).toBeVisible()
await expect(nav.getByRole("link", { name: "Products" })).toBeVisible()
await expect(nav.getByRole("link", { name: "Account" })).toBeVisible()
// Close menu by tapping outside (overlay)
await page.getByTestId("menu-overlay").click()
await expect(nav).toBeHidden()
})
test("bottom sheet slides up on mobile", async ({ page }) => {
await page.goto("/products/1")
await page.getByRole("button", { name: "Add to cart" }).click()
// Bottom sheet appears with cart summary
const bottomSheet = page.getByTestId("bottom-sheet")
await expect(bottomSheet).toBeVisible()
await expect(bottomSheet).toContainText("Added to cart")
// Dismiss by swiping down
const box = await bottomSheet.boundingBox()
if (box) {
const startX = box.x + box.width / 2
const startY = box.y + 20
await page.mouse.move(startX, startY)
await page.mouse.down()
await page.mouse.move(startX, startY + 300, { steps: 10 })
await page.mouse.up()
}
await expect(bottomSheet).toBeHidden()
})
test("pull to refresh reloads content", async ({ page }) => {
await page.goto("/feed")
// Store initial first item text
const firstItem = page.getByRole("listitem").first()
const initialText = await firstItem.textContent()
// Pull-to-refresh: swipe down from top of scrollable area
const feed = page.getByTestId("feed-container")
const box = await feed.boundingBox()
if (box) {
await page.mouse.move(box.x + box.width / 2, box.y + 10)
await page.mouse.down()
await page.mouse.move(box.x + box.width / 2, box.y + 250, { steps: 15 })
await page.mouse.up()
}
// Wait for refresh indicator and then content reload
await expect(page.getByTestId("refresh-spinner")).toBeVisible()
await expect(page.getByTestId("refresh-spinner")).toBeHidden()
})
test("sticky mobile header remains visible on scroll", async ({ page }) => {
await page.goto("/products")
const header = page.getByRole("banner")
// Scroll down significantly
await page.evaluate(() => window.scrollTo(0, 2000))
// Header should remain visible (sticky positioning)
await expect(header).toBeVisible()
await expect(header).toBeInViewport()
})
```
#### JavaScript
```javascript
// tests/mobile-ui.spec.js
const { test, expect, devices } = require("@playwright/test")
test.use({ ...devices["iPhone 14"] })
test("hamburger menu opens and closes", async ({ page }) => {
await page.goto("/")
const menuButton = page.getByRole("button", { name: "Menu" })
const nav = page.getByRole("navigation", { name: "Main" })
await expect(nav).toBeHidden()
await menuButton.click()
await expect(nav).toBeVisible()
await expect(nav.getByRole("link", { name: "Home" })).toBeVisible()
await expect(nav.getByRole("link", { name: "Products" })).toBeVisible()
await expect(nav.getByRole("link", { name: "Account" })).toBeVisible()
await page.getByTestId("menu-overlay").click()
await expect(nav).toBeHidden()
})
test("bottom sheet slides up on mobile", async ({ page }) => {
await page.goto("/products/1")
await page.getByRole("button", { name: "Add to cart" }).click()
const bottomSheet = page.getByTestId("bottom-sheet")
await expect(bottomSheet).toBeVisible()
await expect(bottomSheet).toContainText("Added to cart")
const box = await bottomSheet.boundingBox()
if (box) {
const startX = box.x + box.width / 2
const startY = box.y + 20
await page.mouse.move(startX, startY)
await page.mouse.down()
await page.mouse.move(startX, startY + 300, { steps: 10 })
await page.mouse.up()
}
await expect(bottomSheet).toBeHidden()
})
test("sticky mobile header remains visible on scroll", async ({ page }) => {
await page.goto("/products")
const header = page.getByRole("banner")
await page.evaluate(() => window.scrollTo(0, 2000))
await expect(header).toBeVisible()
await expect(header).toBeInViewport()
})
```
### 5. Geolocation
**Use when**: Testing location-dependent features -- store finders, delivery zones, weather widgets, location-based pricing.
**Avoid when**: The feature does not use the Geolocation API. If it uses IP-based location, mock the API response instead.
#### TypeScript
```typescript
// playwright.config.ts -- set geolocation per project
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
projects: [
{
name: "mobile-nyc",
use: {
...devices["iPhone 14"],
geolocation: { latitude: 40.7128, longitude: -74.006 },
permissions: ["geolocation"],
},
},
{
name: "mobile-london",
use: {
...devices["iPhone 14"],
geolocation: { latitude: 51.5074, longitude: -0.1278 },
permissions: ["geolocation"],
locale: "en-GB",
timezoneId: "Europe/London",
},
},
],
})
```
```typescript
// tests/store-locator.spec.ts
import { test, expect } from "@playwright/test"
test("shows nearby stores based on geolocation", async ({ page, context }) => {
// Geolocation is already set via project config above.
// To override in a specific test:
await context.setGeolocation({ latitude: 34.0522, longitude: -118.2437 }) // Los Angeles
await page.goto("/store-locator")
await page.getByRole("button", { name: "Use my location" }).click()
// Verify the app uses the mocked location
await expect(page.getByText("Stores near Los Angeles")).toBeVisible()
await expect(page.getByRole("listitem")).toHaveCount(5) // nearest 5 stores
})
test("geolocation updates in real time", async ({ page, context }) => {
await context.setGeolocation({ latitude: 40.7128, longitude: -74.006 })
await page.goto("/delivery-tracker")
await expect(page.getByText("New York")).toBeVisible()
// Simulate user moving to a new location
await context.setGeolocation({ latitude: 40.758, longitude: -73.9855 }) // Times Square
// Trigger a location refresh (app-specific)
await page.getByRole("button", { name: "Refresh location" }).click()
await expect(page.getByText("Times Square")).toBeVisible()
})
test("handles geolocation permission denied", async ({ page, context }) => {
// Clear geolocation permissions to simulate denial
await context.clearPermissions()
await page.goto("/store-locator")
await page.getByRole("button", { name: "Use my location" }).click()
// App should show fallback UI
await expect(page.getByText("Location access denied")).toBeVisible()
await expect(page.getByLabel("Enter your zip code")).toBeVisible()
})
```
#### JavaScript
```javascript
// tests/store-locator.spec.js
const { test, expect } = require("@playwright/test")
test("shows nearby stores based on geolocation", async ({ page, context }) => {
await context.setGeolocation({ latitude: 34.0522, longitude: -118.2437 })
await page.goto("/store-locator")
await page.getByRole("button", { name: "Use my location" }).click()
await expect(page.getByText("Stores near Los Angeles")).toBeVisible()
await expect(page.getByRole("listitem")).toHaveCount(5)
})
test("geolocation updates in real time", async ({ page, context }) => {
await context.setGeolocation({ latitude: 40.7128, longitude: -74.006 })
await page.goto("/delivery-tracker")
await expect(page.getByText("New York")).toBeVisible()
await context.setGeolocation({ latitude: 40.758, longitude: -73.9855 })
await page.getByRole("button", { name: "Refresh location" }).click()
await expect(page.getByText("Times Square")).toBeVisible()
})
test("handles geolocation permission denied", async ({ page, context }) => {
await context.clearPermissions()
await page.goto("/store-locator")
await page.getByRole("button", { name: "Use my location" }).click()
await expect(page.getByText("Location access denied")).toBeVisible()
await expect(page.getByLabel("Enter your zip code")).toBeVisible()
})
```
### 6. Multi-Project Responsive Testing
**Use when**: Running the same tests across desktop and mobile browsers in parallel. The standard approach for responsive apps.
**Avoid when**: Your app is desktop-only or mobile-only.
#### TypeScript
```typescript
// playwright.config.ts
import { defineConfig, devices } from "@playwright/test"
export default defineConfig({
testDir: "./tests",
fullyParallel: true,
retries: process.env.CI ? 2 : 0,
projects: [
// ── Desktop ────────────────────────────────────────────
{
name: "desktop-chrome",
use: { ...devices["Desktop Chrome"] },
},
{
name: "desktop-firefox",
use: { ...devices["Desktop Firefox"] },
},
{
name: "desktop-safari",
use: { ...devices["Desktop Safari"] },
},
// ── Mobile ─────────────────────────────────────────────
{
name: "mobile-chrome",
use: { ...devices["Pixel 7"] },
},
{
name: "mobile-safari",
use: { ...devices["iPhone 14"] },
},
// ── Tablet ─────────────────────────────────────────────
{
name: "tablet",
use: { ...devices["iPad Pro 11"] },
},
],
})
```
```typescript
// tests/responsive-checkout.spec.ts
import { test, expect } from "@playwright/test"
test("checkout works across all viewports", async ({ page, isMobile }) => {
await page.goto("/products")
// Add item -- same action on all viewports
await page.getByRole("button", { name: "Add to cart" }).first().click()
// Navigate to cart
if (isMobile) {
// Mobile: cart link may be in hamburger or bottom nav
await page.getByRole("link", { name: "Cart" }).click()
} else {
// Desktop: cart icon in header
await page.getByRole("link", { name: /Cart \(\d+\)/ }).click()
}
await page.waitForURL("**/cart")
await expect(page.getByRole("heading", { name: "Your cart" })).toBeVisible()
// Proceed to checkout
await page.getByRole("link", { name: "Checkout" }).click()
await page.waitForURL("**/checkout")
// Fill form -- same fields on all viewports
await page.getByLabel("Email").fill("test@example.com")
await page.getByLabel("Card number").fill("4242424242424242")
await page.getByRole("button", { name: "Pay now" }).click()
await expect(page.getByText("Order confirmed")).toBeVisible()
})
```
```bash
# Run desktop projects only
npx playwright test --project=desktop-chrome --project=desktop-firefox --project=desktop-safari
# Run mobile projects only
npx playwright test --project=mobile-chrome --project=mobile-safari
# Run specific test file on all projects
npx playwright test tests/responsive-checkout.spec.ts
# CI optimization: mobile + desktop-chrome on PRs, all browsers on main
# In CI config:
# PR: npx playwright test --project=desktop-chrome --project=mobile-chrome --project=mobile-safari
# Main: npx playwright test
```
#### JavaScript
```javascript
// playwright.config.js
const { defineConfig, devices } = require("@playwright/test")
module.exports = defineConfig({
testDir: "./tests",
fullyParallel: true,
retries: process.env.CI ? 2 : 0,
projects: [
{
name: "desktop-chrome",
use: { ...devices["Desktop Chrome"] },
},
{
name: "desktop-firefox",
use: { ...devices["Desktop Firefox"] },
},
{
name: "desktop-safari",
use: { ...devices["Desktop Safari"] },
},
{
name: "mobile-chrome",
use: { ...devices["Pixel 7"] },
},
{
name: "mobile-safari",
use: { ...devices["iPhone 14"] },
},
{
name: "tablet",
use: { ...devices["iPad Pro 11"] },
},
],
})
```
```javascript
// tests/responsive-checkout.spec.js
const { test, expect } = require("@playwright/test")
test("checkout works across all viewports", async ({ page, isMobile }) => {
await page.goto("/products")
await page.getByRole("button", { name: "Add to cart" }).first().click()
if (isMobile) {
await page.getByRole("link", { name: "Cart" }).click()
} else {
await page.getByRole("link", { name: /Cart \(\d+\)/ }).click()
}
await page.waitForURL("**/cart")
await expect(page.getByRole("heading", { name: "Your cart" })).toBeVisible()
await page.getByRole("link", { name: "Checkout" }).click()
await page.waitForURL("**/checkout")
await page.getByLabel("Email").fill("test@example.com")
await page.getByLabel("Card number").fill("4242424242424242")
await page.getByRole("button", { name: "Pay now" }).click()
await expect(page.getByText("Order confirmed")).toBeVisible()
})
```
### 7. Responsive Breakpoint Testing
**Use when**: Systematically verifying layout behavior at every major CSS breakpoint. Best used alongside visual regression testing.
**Avoid when**: You only need one or two viewport sizes -- just use `test.use()` overrides instead.
#### TypeScript
```typescript
// tests/fixtures/responsive.fixture.ts
import { test as base, expect } from "@playwright/test"
type Breakpoint = {
name: string
width: number
height: number
isMobileExpected: boolean
}
const BREAKPOINTS: Breakpoint[] = [
{ name: "xs", width: 320, height: 568, isMobileExpected: true },
{ name: "sm", width: 640, height: 800, isMobileExpected: true },
{ name: "md", width: 768, height: 1024, isMobileExpected: false },
{ name: "lg", width: 1024, height: 768, isMobileExpected: false },
{ name: "xl", width: 1280, height: 800, isMobileExpected: false },
{ name: "2xl", width: 1440, height: 900, isMobileExpected: false },
]
// Custom fixture that runs a test at every breakpoint
export const test = base.extend<{ forEachBreakpoint: void }>({
forEachBreakpoint: [
async ({ page }, use, testInfo) => {
// This fixture is used as a tag -- actual breakpoint iteration is done via test.describe
await use()
},
{ auto: false },
],
})
// Helper: create a describe block that tests every breakpoint
export function describeBreakpoints(title: string, fn: (bp: Breakpoint) => void) {
for (const bp of BREAKPOINTS) {
base.describe(`${title} @ ${bp.name} (${bp.width}px)`, () => {
base.use({ viewport: { width: bp.width, height: bp.height } })
fn(bp)
})
}
}
export { expect, BREAKPOINTS }
```
```typescript
// tests/responsive-grid.spec.ts
import { test, expect, describeBreakpoints } from "./fixtures/responsive.fixture"
describeBreakpoints("product grid", (bp) => {
test("shows correct number of columns", async ({ page }) => {
await page.goto("/products")
const grid = page.getByTestId("product-grid")
const columns = await grid.evaluate((el) => {
const style = window.getComputedStyle(el)
return style.gridTemplateColumns.split(" ").length
})
if (bp.width < 640) {
expect(columns).toBe(1) // xs: single column
} else if (bp.width < 1024) {
expect(columns).toBe(2) // sm-md: two columns
} else {
expect(columns).toBe(4) // lg+: four columns
}
})
test("no content overflow", async ({ page }) => {
await page.goto("/products")
const hasOverflow = await page.evaluate(
() => document.documentElement.scrollWidth > document.documentElement.clientWidth
)
expect(hasOverflow).toBe(false)
})
})
```
#### JavaScript
```javascript
// tests/fixtures/responsive.fixture.js
const { test: base, expect } = require("@playwright/test")
const BREAKPOINTS = [
{ name: "xs", width: 320, height: 568, isMobileExpected: true },
{ name: "sm", width: 640, height: 800, isMobileExpected: true },
{ name: "md", width: 768, height: 1024, isMobileExpected: false },
{ name: "lg", width: 1024, height: 768, isMobileExpected: false },
{ name: "xl", width: 1280, height: 800, isMobileExpected: false },
{ name: "2xl", width: 1440, height: 900, isMobileExpected: false },
]
function describeBreakpoints(title, fn) {
for (const bp of BREAKPOINTS) {
base.describe(`${title} @ ${bp.name} (${bp.width}px)`, () => {
base.use({ viewport: { width: bp.width, height: bp.height } })
fn(bp)
})
}
}
module.exports = { test: base, expect, BREAKPOINTS, describeBreakpoints }
```
```javascript
// tests/responsive-grid.spec.js
const { test, expect, describeBreakpoints } = require("./fixtures/responsive.fixture")
describeBreakpoints("product grid", (bp) => {
test("shows correct number of columns", async ({ page }) => {
await page.goto("/products")
const grid = page.getByTestId("product-grid")
const columns = await grid.evaluate((el) => {
const style = window.getComputedStyle(el)
return style.gridTemplateColumns.split(" ").length
})
if (bp.width < 640) {
expect(columns).toBe(1)
} else if (bp.width < 1024) {
expect(columns).toBe(2)
} else {
expect(columns).toBe(4)
}
})
test("no content overflow", async ({ page }) => {
await page.goto("/products")
const hasOverflow = await page.evaluate(
() => document.documentElement.scrollWidth > document.documentElement.clientWidth
)
expect(hasOverflow).toBe(false)
})
})
```
### 8. Orientation Testing
**Use when**: Testing portrait vs landscape layouts. Critical for tablet apps, media players, dashboards, and any app that adapts to orientation.
**Avoid when**: Your app does not change layout based on orientation (purely responsive to width only -- test with custom viewports instead).
#### TypeScript
```typescript
// tests/orientation.spec.ts
import { test, expect, devices } from "@playwright/test"
test.describe("iPad orientation changes", () => {
test.use({ ...devices["iPad Pro 11"] })
test("dashboard adjusts layout in landscape", async ({ page }) => {
// Start in portrait (834x1194 -- default for iPad Pro 11)
await page.goto("/dashboard")
// Portrait: sidebar collapses, chart stacks vertically
await expect(page.getByTestId("sidebar")).toHaveCSS("position", "fixed")
// Switch to landscape by changing viewport
await page.setViewportSize({ width: 1194, height: 834 })
// Landscape: sidebar visible inline, charts side-by-side
await expect(page.getByTestId("sidebar")).toHaveCSS("position", "relative")
})
test("video player switches to fullscreen in landscape", async ({ page }) => {
await page.goto("/videos/1")
// Portrait: video in inline player
const player = page.getByTestId("video-player")
const portraitBox = await player.boundingBox()
// Switch to landscape
await page.setViewportSize({ width: 1194, height: 834 })
// Video should expand to fill width
const landscapeBox = await player.boundingBox()
expect(landscapeBox!.width).toBeGreaterThan(portraitBox!.width)
})
})
test.describe("iPhone orientation changes", () => {
test("portrait mode", () => {
test.use({ ...devices["iPhone 14"] }) // 390x844
})
test("landscape mode", () => {
test.use({ ...devices["iPhone 14 landscape"] }) // 844x390
})
})
// Test both orientations with a loop
const orientations = [
{ name: "portrait", device: devices["iPad Pro 11"] },
{ name: "landscape", device: devices["iPad Pro 11 landscape"] },
]
for (const { name, device } of orientations) {
test.describe(`form usability in ${name}`, () => {
test.use({ ...device })
test("all form fields are visible without scrolling", async ({ page }) => {
await page.goto("/contact")
const form = page.getByRole("form")
await expect(form).toBeVisible()
// Check form fits within viewport
const formBox = await form.boundingBox()
const viewport = page.viewportSize()!
expect(formBox!.width).toBeLessThanOrEqual(viewport.width)
})
})
}
```
#### JavaScript
```javascript
// tests/orientation.spec.js
const { test, expect, devices } = require("@playwright/test")
test.describe("iPad orientation changes", () => {
test.use({ ...devices["iPad Pro 11"] })
test("dashboard adjusts layout in landscape", async ({ page }) => {
await page.goto("/dashboard")
await expect(page.getByTestId("sidebar")).toHaveCSS("position", "fixed")
await page.setViewportSize({ width: 1194, height: 834 })
await expect(page.getByTestId("sidebar")).toHaveCSS("position", "relative")
})
test("video player switches to fullscreen in landscape", async ({ page }) => {
await page.goto("/videos/1")
const player = page.getByTestId("video-player")
const portraitBox = await player.boundingBox()
await page.setViewportSize({ width: 1194, height: 834 })
const landscapeBox = await player.boundingBox()
expect(landscapeBox.width).toBeGreaterThan(portraitBox.width)
})
})
const orientations = [
{ name: "portrait", device: devices["iPad Pro 11"] },
{ name: "landscape", device: devices["iPad Pro 11 landscape"] },
]
for (const { name, device } of orientations) {
test.describe(`form usability in ${name}`, () => {
test.use({ ...device })
test("all form fields are visible without scrolling", async ({ page }) => {
await page.goto("/contact")
const form = page.getByRole("form")
await expect(form).toBeVisible()
const formBox = await form.boundingBox()
const viewport = page.viewportSize()
expect(formBox.width).toBeLessThanOrEqual(viewport.width)
})
})
}
```
### 9. Mobile Performance
**Use when**: Simulating real-world mobile conditions -- slow 3G networks, underpowered CPUs. Critical for testing loading states, skeleton screens, and timeout handling.
**Avoid when**: Testing functional correctness only. Performance throttling slows down your test suite significantly.
#### TypeScript
```typescript
// tests/mobile-performance.spec.ts
import { test, expect, devices } from "@playwright/test"
test.describe("mobile on slow network", () => {
test.use({ ...devices["Pixel 7"] })
test("shows skeleton loader on slow 3G", async ({ page }) => {
// Get the CDP session for network throttling (Chromium only)
const cdpSession = await page.context().newCDPSession(page)
// Simulate slow 3G: 500kbps download, 500kbps upload, 400ms RTT
await cdpSession.send("Network.emulateNetworkConditions", {
offline: false,
downloadThroughput: (500 * 1024) / 8, // bytes per second
uploadThroughput: (500 * 1024) / 8,
latency: 400, // ms
})
await page.goto("/products")
// Skeleton screen should appear while content loads
await expect(page.getByTestId("product-skeleton")).toBeVisible()
// Eventually, real content replaces skeleton
await expect(page.getByRole("listitem")).toHaveCount(12, { timeout: 30_000 })
await expect(page.getByTestId("product-skeleton")).toBeHidden()
})
test("shows offline message when network drops", async ({ page }) => {
await page.goto("/dashboard")
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
// Drop network entirely
await page.context().setOffline(true)
// Try to navigate -- should show offline message
await page.getByRole("link", { name: "Settings" }).click()
await expect(page.getByText(/you.*offline|no.*connection/i)).toBeVisible()
// Restore network
await page.context().setOffline(false)
await page.reload()
await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible()
})
test("images lazy-load on slow connections", async ({ page }) => {
const cdpSession = await page.context().newCDPSession(page)
await cdpSession.send("Network.emulateNetworkConditions", {
offline: false,
downloadThroughput: (1000 * 1024) / 8,
uploadThroughput: (500 * 1024) / 8,
latency: 200,
})
await page.goto("/gallery")
// Images below the fold should have loading="lazy" and not load immediately
const belowFoldImages = page.locator('img[loading="lazy"]')
const count = await belowFoldImages.count()
expect(count).toBeGreaterThan(0)
// Scroll to trigger lazy loading
await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight))
await expect(belowFoldImages.first()).toHaveJSProperty("complete", true)
})
test("CPU throttling shows performance impact", async ({ page }) => {
const cdpSession = await page.context().newCDPSession(page)
// Simulate 4x CPU slowdown (typical mid-range mobile device)
await cdpSession.send("Emulation.setCPUThrottlingRate", { rate: 4 })
await page.goto("/")
// Measure time to interactive
const tti = await page.evaluate(() => {
const entries = performance.getEntriesByType("navigation") as PerformanceNavigationTiming[]
return entries[0]?.domInteractive ?? 0
})
// Assert TTI is within acceptable range for throttled mobile
expect(tti).toBeLessThan(5000)
// Reset throttling
await cdpSession.send("Emulation.setCPUThrottlingRate", { rate: 1 })
})
})
```
#### JavaScript
```javascript
// tests/mobile-performance.spec.js
const { test, expect, devices } = require("@playwright/test")
test.describe("mobile on slow network", () => {
test.use({ ...devices["Pixel 7"] })
test("shows skeleton loader on slow 3G", async ({ page }) => {
const cdpSession = await page.context().newCDPSession(page)
await cdpSession.send("Network.emulateNetworkConditions", {
offline: false,
downloadThroughput: (500 * 1024) / 8,
uploadThroughput: (500 * 1024) / 8,
latency: 400,
})
await page.goto("/products")
await expect(page.getByTestId("product-skeleton")).toBeVisible()
await expect(page.getByRole("listitem")).toHaveCount(12, { timeout: 30_000 })
await expect(page.getByTestId("product-skeleton")).toBeHidden()
})
test("shows offline message when network drops", async ({ page }) => {
await page.goto("/dashboard")
await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible()
await page.context().setOffline(true)
await page.getByRole("link", { name: "Settings" }).click()
await expect(page.getByText(/you.*offline|no.*connection/i)).toBeVisible()
await page.context().setOffline(false)
await page.reload()
await expect(page.getByRole("heading", { name: "Settings" })).toBeVisible()
})
test("CPU throttling shows performance impact", async ({ page }) => {
const cdpSession = await page.context().newCDPSession(page)
await cdpSession.send("Emulation.setCPUThrottlingRate", { rate: 4 })
await page.goto("/")
const tti = await page.evaluate(() => {
const entries = performance.getEntriesByType("navigation")
return entries[0]?.domInteractive ?? 0
})
expect(tti).toBeLessThan(5000)
await cdpSession.send("Emulation.setCPUThrottlingRate", { rate: 1 })
})
})
```
### 10. PWA Mobile Testing
**Use when**: Testing Progressive Web App features -- service workers, install prompts, offline mode, push notifications on mobile.
**Avoid when**: Your app is not a PWA. For general offline testing, see the network offline pattern in Pattern 9.
#### TypeScript
```typescript
// tests/pwa-mobile.spec.ts
import { test, expect, devices } from "@playwright/test"
test.use({ ...devices["Pixel 7"] })
test("service worker registers and caches resources", async ({ page }) => {
await page.goto("/")
// Wait for service worker to register
const swRegistered = await page.evaluate(async () => {
const registration = await navigator.serviceWorker.ready
return registration.active?.state === "activated"
})
expect(swRegistered).toBe(true)
// Verify critical resources are cached
const cacheContents = await page.evaluate(async () => {
const cache = await caches.open("app-shell-v1")
const keys = await cache.keys()
return keys.map((req) => new URL(req.url).pathname)
})
expect(cacheContents).toContain("/")
expect(cacheContents).toContain("/offline.html")
})
test("app works offline after initial load", async ({ page }) => {
// Load the app online first -- service worker caches resources
await page.goto("/")
await expect(page.getByRole("heading", { name: "Home" })).toBeVisible()
// Wait for service worker to finish caching
await page.evaluate(async () => {
const registration = await navigator.serviceWorker.ready
// Wait for the service worker to activate
if (registration.active?.state !== "activated") {
await new Promise<void>((resolve) => {
registration.active?.addEventListener("statechange", () => {
if (registration.active?.state === "activated") resolve()
})
})
}
})
// Go offline
await page.context().setOffline(true)
// Navigate to a cached page
await page.goto("/about")
// Cached page should render
await expect(page.getByRole("heading", { name: "About" })).toBeVisible()
})
test("offline fallback page shows when uncached route is accessed", async ({ page }) => {
await page.goto("/")
// Wait for service worker
await page.evaluate(() => navigator.serviceWorker.ready)
// Go offline and navigate to an uncached route
await page.context().setOffline(true)
await page.goto("/uncached-page")
// Should show the offline fallback page
await expect(page.getByText(/offline|no.*connection/i)).toBeVisible()
await expect(page.getByRole("button", { name: "Retry" })).toBeVisible()
})
test("app prompts to install on mobile", async ({ page, context }) => {
// Listen for the beforeinstallprompt event
await page.goto("/")
const installPromptFired = await page.evaluate(() => {
return new Promise<boolean>((resolve) => {
// Check if the event has already fired
window.addEventListener("beforeinstallprompt", (e) => {
e.preventDefault() // Prevent auto-prompt
resolve(true)
})
// If PWA criteria are met, the event fires automatically
// Timeout after 5s if it doesn't fire
setTimeout(() => resolve(false), 5000)
})
})
// Note: beforeinstallprompt only fires in Chromium and when PWA criteria are met
// This test validates the event handler, not the browser chrome UI
if (installPromptFired) {
// App should show a custom install banner
await expect(page.getByTestId("install-banner")).toBeVisible()
await page.getByRole("button", { name: "Install app" }).click()
}
})
test("push notification permission request on mobile", async ({ page, context }) => {
// Grant notification permission
await context.grantPermissions(["notifications"])
await page.goto("/settings/notifications")
await page.getByRole("button", { name: "Enable notifications" }).click()
// Verify the app registered for push
const pushSubscription = await page.evaluate(async () => {
const registration = await navigator.serviceWorker.ready
const subscription = await registration.pushManager.getSubscription()
return subscription !== null
})
expect(pushSubscription).toBe(true)
await expect(page.getByText("Notifications enabled")).toBeVisible()
})
```
#### JavaScript
```javascript
// tests/pwa-mobile.spec.js
const { test, expect, devices } = require("@playwright/test")
test.use({ ...devices["Pixel 7"] })
test("service worker registers and caches resources", async ({ page }) => {
await page.goto("/")
const swRegistered = await page.evaluate(async () => {
const registration = await navigator.serviceWorker.ready
return registration.active?.state === "activated"
})
expect(swRegistered).toBe(true)
const cacheContents = await page.evaluate(async () => {
const cache = await caches.open("app-shell-v1")
const keys = await cache.keys()
return keys.map((req) => new URL(req.url).pathname)
})
expect(cacheContents).toContain("/")
expect(cacheContents).toContain("/offline.html")
})
test("app works offline after initial load", async ({ page }) => {
await page.goto("/")
await expect(page.getByRole("heading", { name: "Home" })).toBeVisible()
await page.evaluate(async () => {
await navigator.serviceWorker.ready
})
await page.context().setOffline(true)
await page.goto("/about")
await expect(page.getByRole("heading", { name: "About" })).toBeVisible()
})
test("offline fallback page shows when uncached route is accessed", async ({ page }) => {
await page.goto("/")
await page.evaluate(() => navigator.serviceWorker.ready)
await page.context().setOffline(true)
await page.goto("/uncached-page")
await expect(page.getByText(/offline|no.*connection/i)).toBeVisible()
await expect(page.getByRole("button", { name: "Retry" })).toBeVisible()
})
test("push notification permission request on mobile", async ({ page, context }) => {
await context.grantPermissions(["notifications"])
await page.goto("/settings/notifications")
await page.getByRole("button", { name: "Enable notifications" }).click()
const pushSubscription = await page.evaluate(async () => {
const registration = await navigator.serviceWorker.ready
const subscription = await registration.pushManager.getSubscription()
return subscription !== null
})
expect(pushSubscription).toBe(true)
await expect(page.getByText("Notifications enabled")).toBeVisible()
})
```
## Decision Guide
| Question | Answer | Approach |
| ----------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------- |
| Need to test how app looks on iPhone 14? | Yes | Use `devices['iPhone 14']` -- gets viewport, UA, touch, scale factor in one shot |
| Need to test a CSS breakpoint at 768px? | Yes | Use `test.use({ viewport: { width: 768, height: 1024 } })` -- simpler, no UA change |
| Need to test both portrait and landscape? | Yes | Use named device + landscape variant: `devices['iPad Pro 11']` and `devices['iPad Pro 11 landscape']` |
| Need realistic mobile performance? | Yes | Use CDP `Network.emulateNetworkConditions` + `Emulation.setCPUThrottlingRate` (Chromium only) |
| Need to test touch gestures? | Yes | Use device profile with `hasTouch: true`, then use `tap()`, mouse gestures for swipe |
| Need to test geolocation? | Yes | Set `geolocation` and `permissions: ['geolocation']` in context options |
| Need pixel-perfect mobile testing? | No -- use real devices | Playwright emulation approximates; font rendering and native UI differ from real hardware |
| Which devices to test by default? | Start with 3 | `Desktop Chrome` + `Pixel 7` (Android) + `iPhone 14` (iOS). Add tablet if your app has a tablet layout. |
| When to add more device projects? | When bugs escape | If users report device-specific bugs, add that device profile permanently |
| Run all devices on every PR? | No | Run desktop + one mobile on PRs. Run all devices on main branch merges. |
| Device emulation vs custom viewport? | Depends on goal | Emulation: testing real-world device behavior. Custom viewport: testing CSS breakpoints. |
| Should I test every screen size? | No | Test your actual CSS breakpoints, plus smallest (320px) and largest (1440px+) supported sizes |
## Anti-Patterns
| Don't Do This | Problem | Do This Instead |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Only testing at 1280x720 desktop | Misses all mobile and tablet layout bugs; most web traffic is mobile | Add at least `Pixel 7` and `iPhone 14` projects |
| Using device emulation for pixel-perfect testing | Emulation approximates real devices -- font rendering, sub-pixel antialiasing, and native browser chrome differ | Use emulation for layout and interaction testing; use real device labs (BrowserStack, Sauce Labs) for pixel-perfect validation |
| Ignoring touch interactions | Mobile users tap, swipe, and long-press; `click()` alone may not trigger touch-specific event handlers | Use `tap()` on touch device profiles; test swipe gestures with mouse move sequences |
| Not testing orientation changes | Users rotate tablets and phones; layouts may break in landscape | Test both portrait and landscape with device variants or `page.setViewportSize()` |
| `page.setViewportSize()` without `hasTouch: true` | Viewport is small but browser reports no touch support -- `@media (hover: hover)` still matches desktop | Use device profiles or explicitly set `hasTouch: true` in `test.use()` |
| Hardcoding `isMobile` checks in every test | Duplicates logic, hard to maintain; tests become brittle | Use page objects that abstract mobile vs desktop behavior behind methods |
| Testing mobile layout with `visibility: hidden` checks only | Element may still take up space; CSS may use `display: none` or `transform: translateX(-100%)` | Use `toBeHidden()` (checks not visible) or `toHaveCSS('display', 'none')` for specific CSS behavior |
| Running 10+ device projects on every CI run | Massive CI time and cost with diminishing returns beyond 3-4 devices | Pick representative devices: one Android phone, one iPhone, one tablet, and desktop browsers |
| Network throttling in every test | Slows entire suite dramatically for minimal extra coverage | Create a separate `mobile-perf` project or tag performance tests with `@slow` and run them separately |
| `await page.waitForTimeout(2000)` after orientation change | Arbitrary delay; layout reflow may be faster or slower | `await expect(locator).toHaveCSS('property', 'value')` -- assertion auto-retries until layout settles |
| Testing geolocation without setting permissions | Browser blocks geolocation silently; test sees no location data and passes incorrectly | Always set `permissions: ['geolocation']` alongside `geolocation` coordinates |
| CDP throttling on Firefox or WebKit | CDP sessions are Chromium-only; test will throw on other browsers | Guard CDP calls with a browser check or use Chromium-only projects for performance tests |
## Troubleshooting
### `tap()` throws "Page.tap: Not supported" error
**Cause**: The browser context was created without `hasTouch: true`. Device profiles set this automatically, but custom viewport configurations do not.
```typescript
// Wrong -- custom viewport without touch support
test.use({ viewport: { width: 375, height: 667 } })
test("tap fails", async ({ page }) => {
await page.goto("/")
await page.getByRole("button").tap() // Error: Not supported
})
// Fix -- enable touch explicitly
test.use({
viewport: { width: 375, height: 667 },
hasTouch: true,
})
test("tap works", async ({ page }) => {
await page.goto("/")
await page.getByRole("button").tap() // Works
})
// Or use a device profile that includes hasTouch
test.use({ ...devices["iPhone 14"] })
```
### `isMobile` is always `false`
**Cause**: `isMobile` is set by the device profile's `isMobile` property, not by viewport size. Custom viewports do not set it.
```typescript
// isMobile is false here -- no device profile used
test.use({ viewport: { width: 375, height: 667 } })
test("isMobile is false", async ({ page, isMobile }) => {
console.log(isMobile) // false
})
// Fix: use a device profile, or set isMobile explicitly
test.use({
viewport: { width: 375, height: 667 },
isMobile: true,
hasTouch: true,
})
test("isMobile is true", async ({ page, isMobile }) => {
console.log(isMobile) // true
})
```
### Geolocation not working -- location remains default
**Cause**: Missing `permissions: ['geolocation']` in context options. The browser silently denies the Geolocation API without this permission.
```typescript
// Wrong -- geolocation set but no permission granted
test.use({
geolocation: { latitude: 40.7128, longitude: -74.006 },
// Missing: permissions: ['geolocation']
})
// Fix
test.use({
geolocation: { latitude: 40.7128, longitude: -74.006 },
permissions: ["geolocation"],
})
```
### CDP session throws on Firefox/WebKit
**Cause**: `page.context().newCDPSession(page)` is Chromium-only. Firefox and WebKit do not support CDP.
```typescript
// Wrong -- crashes on Firefox and WebKit
test("throttle network", async ({ page }) => {
const cdp = await page.context().newCDPSession(page) // Throws on non-Chromium
})
// Fix -- guard with browser name check
test("throttle network", async ({ page, browserName }) => {
test.skip(browserName !== "chromium", "CDP throttling is Chromium-only")
const cdp = await page.context().newCDPSession(page)
await cdp.send("Network.emulateNetworkConditions", {
offline: false,
downloadThroughput: (500 * 1024) / 8,
uploadThroughput: (500 * 1024) / 8,
latency: 400,
})
})
// Alternative -- use context.setOffline() which works on all browsers
test("offline mode", async ({ page }) => {
await page.context().setOffline(true) // Works everywhere
})
```
### Viewport change does not trigger CSS media queries
**Cause**: `page.setViewportSize()` changes the viewport but does not trigger `resize` or `orientationchange` events in some frameworks that rely on JavaScript-based responsive logic rather than CSS media queries.
```typescript
// If media queries don't fire after setViewportSize, dispatch manually
await page.setViewportSize({ width: 375, height: 667 })
await page.evaluate(() => window.dispatchEvent(new Event("resize")))
// Better: use the viewport in test.use() so it's set before page load
test.use({ viewport: { width: 375, height: 667 } })
```
### Service worker not registering in tests
**Cause**: Service workers require HTTPS or localhost. Playwright's default `baseURL` of `http://localhost:3000` works, but other HTTP origins do not.
```typescript
// Ensure your baseURL is localhost or HTTPS
// playwright.config.ts
export default defineConfig({
use: {
baseURL: "http://localhost:3000", // Works for service workers
// baseURL: 'http://192.168.1.100:3000', // Does NOT work -- not localhost
},
})
// If testing against a non-localhost server, use HTTPS
// or use serviceWorkers: 'allow' (default) in context options
```
## Related
- [core/configuration.md](configuration.md) -- project setup with device profiles and multi-project config
- [core/visual-regression.md](visual-regression.md) -- combine responsive testing with screenshot comparison across viewports
- [core/network-mocking.md](network-mocking.md) -- mock API responses alongside mobile testing
- [core/service-workers-and-pwa.md](service-workers-and-pwa.md) -- in-depth PWA testing beyond mobile context
- [core/performance-testing.md](performance-testing.md) -- comprehensive performance testing including mobile metrics
- [core/browser-apis.md](browser-apis.md) -- geolocation, permissions, and other browser APIs in detail
- [ci/projects-and-dependencies.md](../ci/projects-and-dependencies.md) -- advanced multi-project patterns for responsive testing matrices
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 |