0
# Device Emulation
1

2
Mobile device emulation, viewport management, and browser environment simulation for responsive testing.
3

4
## Capabilities
5

6
### Viewport Management
7

8
Control browser viewport dimensions and characteristics.
9

10
```typescript { .api }
11
/**
12
 * Set viewport size and properties
13
 * @param viewport - Viewport configuration or null to disable
14
 */
15
setViewport(viewport: Viewport | null): Promise<void>;
16

17
/**
18
 * Get current viewport
19
 * @returns Current viewport or null
20
 */
21
viewport(): Viewport | null;
22

23
interface Viewport {
24
  /** Viewport width in pixels */
25
  width: number;
26
  /** Viewport height in pixels */
27
  height: number;
28
  /** Device scale factor */
29
  deviceScaleFactor?: number;
30
  /** Whether to emulate mobile device */
31
  isMobile?: boolean;
32
  /** Whether device has touch support */
33
  hasTouch?: boolean;
34
  /** Whether device is in landscape mode */
35
  isLandscape?: boolean;
36
}
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
// Set mobile viewport
43
await page.setViewport({
44
  width: 375,
45
  height: 667,
46
  deviceScaleFactor: 2,
47
  isMobile: true,
48
  hasTouch: true
49
});
50

51
// Set desktop viewport
52
await page.setViewport({
53
  width: 1920,
54
  height: 1080,
55
  deviceScaleFactor: 1
56
});
57

58
// Get current viewport
59
const viewport = page.viewport();
60
console.log(`Viewport: ${viewport?.width}x${viewport?.height}`);
61
```
62

63
### Device Emulation
64

65
Emulate specific devices with predefined configurations.
66

67
```typescript { .api }
68
/**
69
 * Emulate specific device
70
 * @param device - Device configuration
71
 */
72
emulate(device: Device): Promise<void>;
73

74
interface Device {
75
  /** Device name */
76
  name: string;
77
  /** User agent string */
78
  userAgent: string;
79
  /** Viewport configuration */
80
  viewport: Viewport;
81
}
82

83
/**
84
 * Predefined device configurations
85
 */
86
const KnownDevices: Record<string, Device>;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { KnownDevices } from "puppeteer";
93

94
// Emulate iPhone
95
await page.emulate(KnownDevices["iPhone 13"]);
96

97
// Emulate iPad
98
await page.emulate(KnownDevices["iPad Pro"]);
99

100
// Custom device
101
await page.emulate({
102
  name: "Custom Mobile",
103
  userAgent: "Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36",
104
  viewport: {
105
    width: 360,
106
    height: 640,
107
    deviceScaleFactor: 3,
108
    isMobile: true,
109
    hasTouch: true
110
  }
111
});
112
```
113

114
### Media Emulation
115

116
Emulate media types and features for CSS media queries.
117

118
```typescript { .api }
119
/**
120
 * Emulate CSS media type
121
 * @param type - Media type or null to disable
122
 */
123
emulateMediaType(type?: "screen" | "print" | null): Promise<void>;
124

125
/**
126
 * Emulate CSS media features
127
 * @param features - Array of media features or null to disable
128
 */
129
emulateMediaFeatures(features?: MediaFeature[] | null): Promise<void>;
130

131
interface MediaFeature {
132
  /** Media feature name */
133
  name: string;
134
  /** Media feature value */
135
  value: string;
136
}
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
// Emulate print media
143
await page.emulateMediaType("print");
144

145
// Emulate dark mode
146
await page.emulateMediaFeatures([
147
  { name: "prefers-color-scheme", value: "dark" }
148
]);
149

150
// Emulate reduced motion
151
await page.emulateMediaFeatures([
152
  { name: "prefers-reduced-motion", value: "reduce" }
153
]);
154

155
// Multiple features
156
await page.emulateMediaFeatures([
157
  { name: "prefers-color-scheme", value: "dark" },
158
  { name: "prefers-reduced-motion", value: "reduce" },
159
  { name: "pointer", value: "coarse" }
160
]);
161
```
162

163
### Geographic Emulation
164

165
Emulate geolocation and timezone.
166

167
```typescript { .api }
168
/**
169
 * Set geolocation
170
 * @param options - Geolocation coordinates
171
 */
172
setGeolocation(options: GeolocationOptions): Promise<void>;
173

174
/**
175
 * Emulate timezone
176
 * @param timezoneId - Timezone identifier or null for default
177
 */
178
emulateTimezone(timezoneId?: string | null): Promise<void>;
179

180
interface GeolocationOptions {
181
  /** Latitude */
182
  latitude: number;
183
  /** Longitude */
184
  longitude: number;
185
  /** Accuracy in meters */
186
  accuracy?: number;
187
}
188
```
189

190
**Usage Examples:**
191

192
```typescript
193
// Set location to New York
194
await page.setGeolocation({
195
  latitude: 40.7128,
196
  longitude: -74.0060,
197
  accuracy: 10
198
});
199

200
// Set timezone to Tokyo
201
await page.emulateTimezone("Asia/Tokyo");
202

203
// Set timezone to London
204
await page.emulateTimezone("Europe/London");
205
```
206

207
### Performance Emulation
208

209
Emulate CPU throttling and network conditions.
210

211
```typescript { .api }
212
/**
213
 * Emulate CPU throttling
214
 * @param factor - Throttling factor (1 = no throttling, 4 = 4x slower)
215
 */
216
emulateCPUThrottling(factor: number | null): Promise<void>;
217

218
/**
219
 * Emulate vision deficiency
220
 * @param type - Type of vision deficiency or null to disable
221
 */
222
emulateVisionDeficiency(
223
  type?: "achromatopsia" | "blurredVision" | "deuteranopia" | "protanopia" | "tritanopia" | null
224
): Promise<void>;
225
```
226

227
**Usage Examples:**
228

229
```typescript
230
// Throttle CPU to 4x slower
231
await page.emulateCPUThrottling(4);
232

233
// Emulate color blindness
234
await page.emulateVisionDeficiency("deuteranopia");
235

236
// Emulate blurred vision
237
await page.emulateVisionDeficiency("blurredVision");
238

239
// Disable emulation
240
await page.emulateCPUThrottling(null);
241
await page.emulateVisionDeficiency(null);
242
```