@assertrx/dino 1.0.0

package/skills/playwright-core/mobile-and-responsive.md

@@ -0,0 +1,1669 @@
+# 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.0060 },
+        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.0060 });
+  await page.goto('/delivery-tracker');
+
+  await expect(page.getByText('New York')).toBeVisible();
+
+  // Simulate user moving to a new location
+  await context.setGeolocation({ latitude: 40.7580, 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.0060 });
+  await page.goto('/delivery-tracker');
+
+  await expect(page.getByText('New York')).toBeVisible();
+
+  await context.setGeolocation({ latitude: 40.7580, 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.0060 },
+  // Missing: permissions: ['geolocation']
+});
+
+// Fix
+test.use({
+  geolocation: { latitude: 40.7128, longitude: -74.0060 },
+  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