1# Mobile & Responsive Testing
2 
3## Table of Contents
4 
51. [Device Emulation](#device-emulation)
62. [Touch Gestures](#touch-gestures)
73. [Viewport Testing](#viewport-testing)
84. [Mobile-Specific UI](#mobile-specific-ui)
95. [Responsive Breakpoints](#responsive-breakpoints)
10 
11## Device Emulation
12 
13### Use Built-in Devices
14 
15```typescript
16import { test, devices } from "@playwright/test";
17 
18// Configure in playwright.config.ts
19export default defineConfig({
20  projects: [
21    { name: "Desktop Chrome", use: { ...devices["Desktop Chrome"] } },
22    { name: "Mobile Safari", use: { ...devices["iPhone 14"] } },
23    { name: "Mobile Chrome", use: { ...devices["Pixel 7"] } },
24    { name: "Tablet", use: { ...devices["iPad Pro 11"] } },
25  ],
26});
27```
28 
29### Custom Device Configuration
30 
31```typescript
32test.use({
33  viewport: { width: 390, height: 844 },
34  deviceScaleFactor: 3,
35  isMobile: true,
36  hasTouch: true,
37  userAgent:
38    "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15",
39});
40 
41test("custom mobile device", async ({ page }) => {
42  await page.goto("/");
43  // Test runs with custom device settings
44});
45```
46 
47### Test Across Multiple Devices
48 
49```typescript
50const mobileDevices = ["iPhone 14", "Pixel 7", "Galaxy S21"];
51 
52for (const deviceName of mobileDevices) {
53  test(`checkout on ${deviceName}`, async ({ browser }) => {
54    const device = devices[deviceName];
55    const context = await browser.newContext({ ...device });
56    const page = await context.newPage();
57 
58    await page.goto("/checkout");
59    await expect(page.getByRole("button", { name: "Pay" })).toBeVisible();
60 
61    await context.close();
62  });
63}
64```
65 
66## Touch Gestures
67 
68### Tap
69 
70```typescript
71test.use({ hasTouch: true });
72 
73test("tap to interact", async ({ page }) => {
74  await page.goto("/gallery");
75 
76  // Tap is like click but for touch devices
77  await page.getByRole("img", { name: "Photo 1" }).tap();
78 
79  await expect(page.getByRole("dialog")).toBeVisible();
80});
81```
82 
83### Swipe
84 
85```typescript
86test("swipe carousel", async ({ page }) => {
87  await page.goto("/carousel");
88 
89  const carousel = page.getByTestId("carousel");
90  const box = await carousel.boundingBox();
91 
92  if (box) {
93    // Swipe left
94    await page.touchscreen.tap(box.x + box.width - 50, box.y + box.height / 2);
95    await page.mouse.move(box.x + 50, box.y + box.height / 2);
96 
97    // Or use drag
98    await carousel.dragTo(carousel, {
99      sourcePosition: { x: box.width - 50, y: box.height / 2 },
100      targetPosition: { x: 50, y: box.height / 2 },
101    });
102  }
103 
104  await expect(page.getByText("Slide 2")).toBeVisible();
105});
106```
107 
108### Swipe Fixture
109 
110```typescript
111// fixtures/touch.fixture.ts
112import { test as base, Page } from "@playwright/test";
113 
114type TouchFixtures = {
115  swipe: (
116    element: Locator,
117    direction: "left" | "right" | "up" | "down",
118  ) => Promise<void>;
119};
120 
121export const test = base.extend<TouchFixtures>({
122  swipe: async ({ page }, use) => {
123    await use(async (element, direction) => {
124      const box = await element.boundingBox();
125      if (!box) throw new Error("Element not visible");
126 
127      const centerX = box.x + box.width / 2;
128      const centerY = box.y + box.height / 2;
129      const distance = 100;
130 
131      const moves = {
132        left: {
133          startX: centerX + distance,
134          endX: centerX - distance,
135          y: centerY,
136        },
137        right: {
138          startX: centerX - distance,
139          endX: centerX + distance,
140          y: centerY,
141        },
142        up: {
143          startX: centerX,
144          endX: centerX,
145          startY: centerY + distance,
146          endY: centerY - distance,
147        },
148        down: {
149          startX: centerX,
150          endX: centerX,
151          startY: centerY - distance,
152          endY: centerY + distance,
153        },
154      };
155 
156      const move = moves[direction];
157      await page.touchscreen.tap(move.startX, move.startY ?? move.y);
158      await page.mouse.move(move.endX, move.endY ?? move.y, { steps: 10 });
159      await page.mouse.up();
160    });
161  },
162});
163 
164// Usage
165test("swipe to delete", async ({ page, swipe }) => {
166  await page.goto("/inbox");
167 
168  const message = page.getByTestId("message-1");
169  await swipe(message, "left");
170 
171  await expect(page.getByRole("button", { name: "Delete" })).toBeVisible();
172});
173```
174 
175### Long Press
176 
177```typescript
178test("long press for context menu", async ({ page }) => {
179  await page.goto("/files");
180 
181  const file = page.getByText("document.pdf");
182  const box = await file.boundingBox();
183 
184  if (box) {
185    // Touch down
186    await page.touchscreen.tap(box.x + box.width / 2, box.y + box.height / 2);
187 
188    // Hold for 500ms
189    await page.waitForTimeout(500);
190 
191    // Context menu should appear
192    await expect(page.getByRole("menu")).toBeVisible();
193  }
194});
195```
196 
197### Pinch Zoom
198 
199```typescript
200test("pinch to zoom image", async ({ page }) => {
201  await page.goto("/map");
202 
203  // Pinch zoom requires two touch points
204  // Playwright doesn't have native pinch support, so we simulate via evaluate
205  await page.evaluate(() => {
206    const element = document.querySelector("#map");
207    if (element) {
208      // Simulate wheel event as fallback for zoom
209      element.dispatchEvent(
210        new WheelEvent("wheel", {
211          deltaY: -100, // Negative = zoom in
212          ctrlKey: true, // Ctrl+wheel = pinch on many apps
213        }),
214      );
215    }
216  });
217 
218  // Or trigger the app's zoom function directly
219  await page.evaluate(() => {
220    (window as any).mapInstance?.setZoom(15);
221  });
222});
223```
224 
225## Viewport Testing
226 
227### Test Different Sizes
228 
229```typescript
230const viewports = [
231  { name: "mobile", width: 375, height: 667 },
232  { name: "tablet", width: 768, height: 1024 },
233  { name: "desktop", width: 1920, height: 1080 },
234];
235 
236for (const { name, width, height } of viewports) {
237  test(`navigation on ${name}`, async ({ page }) => {
238    await page.setViewportSize({ width, height });
239    await page.goto("/");
240 
241    if (width < 768) {
242      // Mobile: should have hamburger menu
243      await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
244    } else {
245      // Desktop: should have visible nav links
246      await expect(page.getByRole("link", { name: "Products" })).toBeVisible();
247    }
248  });
249}
250```
251 
252### Dynamic Viewport Changes
253 
254```typescript
255test("responsive layout change", async ({ page }) => {
256  await page.setViewportSize({ width: 1200, height: 800 });
257  await page.goto("/dashboard");
258 
259  // Desktop: sidebar visible
260  await expect(page.getByRole("complementary")).toBeVisible();
261 
262  // Resize to mobile
263  await page.setViewportSize({ width: 375, height: 667 });
264 
265  // Mobile: sidebar hidden, hamburger visible
266  await expect(page.getByRole("complementary")).toBeHidden();
267  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
268});
269```
270 
271## Mobile-Specific UI
272 
273### Hamburger Menu
274 
275```typescript
276test("mobile navigation", async ({ page }) => {
277  await page.setViewportSize({ width: 375, height: 667 });
278  await page.goto("/");
279 
280  // Open hamburger menu
281  await page.getByRole("button", { name: "Menu" }).click();
282 
283  // Navigation drawer should appear
284  const nav = page.getByRole("navigation");
285  await expect(nav).toBeVisible();
286 
287  // Navigate via mobile menu
288  await nav.getByRole("link", { name: "Products" }).click();
289 
290  await expect(page).toHaveURL("/products");
291  // Menu should close after navigation
292  await expect(nav).toBeHidden();
293});
294```
295 
296### Bottom Sheet
297 
298```typescript
299test("bottom sheet interaction", async ({ page }) => {
300  await page.setViewportSize({ width: 375, height: 667 });
301  await page.goto("/product/123");
302 
303  await page.getByRole("button", { name: "Add to Cart" }).click();
304 
305  // Bottom sheet appears
306  const sheet = page.getByRole("dialog");
307  await expect(sheet).toBeVisible();
308 
309  // Select options
310  await sheet.getByRole("combobox", { name: "Size" }).selectOption("Large");
311  await sheet.getByRole("button", { name: "Confirm" }).click();
312 
313  await expect(page.getByText("Added to cart")).toBeVisible();
314});
315```
316 
317### Pull to Refresh
318 
319```typescript
320test("pull to refresh", async ({ page }) => {
321  await page.goto("/feed");
322 
323  const feed = page.getByTestId("feed");
324  const initialFirstItem = await feed.locator("> *").first().textContent();
325 
326  // Simulate pull down
327  const box = await feed.boundingBox();
328  if (box) {
329    await page.touchscreen.tap(box.x + box.width / 2, box.y + 50);
330    await page.mouse.move(box.x + box.width / 2, box.y + 200, { steps: 20 });
331    await page.mouse.up();
332  }
333 
334  // Wait for refresh
335  await expect(page.getByTestId("loading")).toBeVisible();
336  await expect(page.getByTestId("loading")).toBeHidden();
337 
338  // Content should be updated (in a real app)
339});
340```
341 
342## Responsive Breakpoints
343 
344### Test All Breakpoints
345 
346```typescript
347const breakpoints = {
348  xs: 320,
349  sm: 640,
350  md: 768,
351  lg: 1024,
352  xl: 1280,
353  "2xl": 1536,
354};
355 
356test.describe("responsive header", () => {
357  for (const [name, width] of Object.entries(breakpoints)) {
358    test(`header at ${name} (${width}px)`, async ({ page }) => {
359      await page.setViewportSize({ width, height: 800 });
360      await page.goto("/");
361 
362      if (width < 768) {
363        await expect(page.getByTestId("mobile-menu-button")).toBeVisible();
364        await expect(page.getByTestId("desktop-nav")).toBeHidden();
365      } else {
366        await expect(page.getByTestId("mobile-menu-button")).toBeHidden();
367        await expect(page.getByTestId("desktop-nav")).toBeVisible();
368      }
369    });
370  }
371});
372```
373 
374### Visual Regression at Breakpoints
375 
376```typescript
377test.describe("visual regression", () => {
378  const sizes = [
379    { width: 375, height: 667, name: "mobile" },
380    { width: 768, height: 1024, name: "tablet" },
381    { width: 1440, height: 900, name: "desktop" },
382  ];
383 
384  for (const { width, height, name } of sizes) {
385    test(`homepage at ${name}`, async ({ page }) => {
386      await page.setViewportSize({ width, height });
387      await page.goto("/");
388 
389      await expect(page).toHaveScreenshot(`homepage-${name}.png`);
390    });
391  }
392});
393```
394 
395## Anti-Patterns to Avoid
396 
397| Anti-Pattern                | Problem                   | Solution                         |
398| --------------------------- | ------------------------- | -------------------------------- |
399| Only testing one viewport   | Misses responsive bugs    | Test multiple breakpoints        |
400| Ignoring touch events       | Features broken on mobile | Test tap, swipe, long press      |
401| Hardcoded viewport in tests | Can't test multiple sizes | Use `page.setViewportSize()`     |
402| Not testing orientation     | Landscape bugs missed     | Test both portrait and landscape |
403 
404## Related References
405 
406- **Visual Testing**: See [test-suite-structure.md](../core/test-suite-structure.md) for screenshot testing
407- **Locators**: See [locators.md](../core/locators.md) for mobile-friendly selectors
408- **Browser APIs**: See [browser-apis.md](../browser-apis/browser-apis.md) for permissions (camera, geolocation, notifications)
409- **Canvas/Touch**: See [canvas-webgl.md](../testing-patterns/canvas-webgl.md) for touch gestures on canvas elements
410