0
# Browser Management
1

2
Core browser lifecycle management including launching new browser instances, connecting to existing ones, and managing browser contexts for isolation.
3

4
## Capabilities
5

6
### Launch Browser
7

8
Launches a new browser instance with the specified options. For puppeteer-core, an executable path is required.
9

10
```typescript { .api }
11
/**
12
 * Launch a new browser instance
13
 * @param options - Browser launch configuration
14
 * @returns Promise resolving to Browser instance
15
 */
16
function launch(options?: LaunchOptions): Promise<Browser>;
17

18
interface LaunchOptions {
19
  /** Path to browser executable (required for puppeteer-core) */
20
  executablePath?: string;
21
  /** Run browser in headless mode */
22
  headless?: boolean | "new";
23
  /** Additional command line arguments */
24
  args?: string[];
25
  /** Ignore default arguments */
26
  ignoreDefaultArgs?: boolean | string[];
27
  /** Handle SIGINT signal */
28
  handleSIGINT?: boolean;
29
  /** Handle SIGTERM signal */
30
  handleSIGTERM?: boolean;
31
  /** Handle SIGHUP signal */
32
  handleSIGHUP?: boolean;
33
  /** Timeout for browser launch */
34
  timeout?: number;
35
  /** Dump browser output to console */
36
  dumpio?: boolean;
37
  /** User data directory path */
38
  userDataDir?: string;
39
  /** Environment variables */
40
  env?: Record<string, string | undefined>;
41
  /** Open browser devtools */
42
  devtools?: boolean;
43
  /** Use pipe transport instead of websocket */
44
  pipe?: boolean;
45
  /** Slow down operations by specified milliseconds */
46
  slowMo?: number;
47
  /** Default viewport for pages */
48
  defaultViewport?: Viewport | null;
49
  /** Ignore HTTPS errors */
50
  ignoreHTTPSErrors?: boolean;
51
  /** Target filter for connection */
52
  targetFilter?: (target: Target) => boolean;
53
  /** Default timeout settings */
54
  timeout?: number;
55
  /** Browser type (chrome or firefox) */
56
  browser?: "chrome" | "firefox";
57
  /** Browser channel */
58
  channel?: string;
59
  /** Protocol to use */
60
  protocol?: "cdp" | "webDriverBiDi";
61
  /** Browser arguments for debugging */
62
  debuggingPort?: number;
63
}
64
```
65

66
**Usage Examples:**
67

68
```typescript
69
import puppeteer from "puppeteer-core";
70

71
// Basic launch
72
const browser = await puppeteer.launch({
73
  executablePath: "/path/to/chrome",
74
  headless: true
75
});
76

77
// Launch with custom arguments
78
const browser = await puppeteer.launch({
79
  executablePath: "/usr/bin/google-chrome",
80
  headless: false,
81
  args: ["--no-sandbox", "--disable-dev-shm-usage"],
82
  defaultViewport: { width: 1920, height: 1080 }
83
});
84

85
// Launch for debugging
86
const browser = await puppeteer.launch({
87
  executablePath: "/path/to/chrome",
88
  headless: false,
89
  devtools: true,
90
  slowMo: 100
91
});
92
```
93

94
### Connect to Browser
95

96
Connect to an existing browser instance via WebSocket endpoint or URL.
97

98
```typescript { .api }
99
/**
100
 * Connect to existing browser instance
101
 * @param options - Connection configuration
102
 * @returns Promise resolving to Browser instance
103
 */
104
function connect(options: ConnectOptions): Promise<Browser>;
105

106
interface ConnectOptions {
107
  /** WebSocket endpoint of the browser */
108
  browserWSEndpoint?: string;
109
  /** HTTP URL of the browser */
110
  browserURL?: string;
111
  /** Ignore HTTPS errors */
112
  ignoreHTTPSErrors?: boolean;
113
  /** Default viewport for new pages */
114
  defaultViewport?: Viewport | null;
115
  /** Slow down operations by specified milliseconds */
116
  slowMo?: number;
117
  /** Filter targets during connection */
118
  targetFilter?: (target: Target) => boolean;
119
  /** Additional headers for connection */
120
  headers?: Record<string, string>;
121
  /** Protocol to use */
122
  protocol?: "cdp" | "webDriverBiDi";
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
// Connect via WebSocket endpoint
130
const browser = await puppeteer.connect({
131
  browserWSEndpoint: "ws://localhost:9222/devtools/browser"
132
});
133

134
// Connect via HTTP URL
135
const browser = await puppeteer.connect({
136
  browserURL: "http://localhost:9222"
137
});
138

139
// Connect with custom headers
140
const browser = await puppeteer.connect({
141
  browserWSEndpoint: "ws://remote:9222/devtools/browser",
142
  headers: { "Authorization": "Bearer token" }
143
});
144
```
145

146
### Default Arguments
147

148
Get default command line arguments used when launching the browser.
149

150
```typescript { .api }
151
/**
152
 * Get default browser launch arguments
153
 * @param options - Launch options to consider
154
 * @returns Array of default arguments
155
 */
156
function defaultArgs(options?: LaunchOptions): string[];
157
```
158

159
**Usage Examples:**
160

161
```typescript
162
// Get default arguments
163
const args = puppeteer.defaultArgs();
164
console.log(args); // ["--disable-background-networking", "--enable-features=...", ...]
165

166
// Get arguments for headless mode
167
const headlessArgs = puppeteer.defaultArgs({ headless: true });
168

169
// Get arguments excluding specific ones
170
const customArgs = puppeteer.defaultArgs({ 
171
  ignoreDefaultArgs: ["--disable-extensions"] 
172
});
173
```
174

175
### Executable Path
176

177
Get the path to the bundled browser executable (returns empty string for puppeteer-core).
178

179
```typescript { .api }
180
/**
181
 * Get path to browser executable
182
 * @returns Path to executable or empty string for puppeteer-core
183
 */
184
function executablePath(): string;
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
// Get executable path (empty for puppeteer-core)
191
const path = puppeteer.executablePath();
192
console.log(path); // "" - must provide executablePath in launch options
193
```
194

195
### Browser Interface
196

197
Main browser instance providing access to pages, contexts, and browser-level operations.
198

199
```typescript { .api }
200
interface Browser extends EventEmitter {
201
  /** Get the browser process (Node.js only) */
202
  process(): ChildProcess | null;
203
  /** Create new isolated browser context */
204
  createBrowserContext(options?: BrowserContextOptions): Promise<BrowserContext>;
205
  /** Get all browser contexts */
206
  browserContexts(): BrowserContext[];
207
  /** Get default browser context */
208
  defaultBrowserContext(): BrowserContext;
209
  /** Get WebSocket endpoint */
210
  wsEndpoint(): string;
211
  /** Create new page in default context */
212
  newPage(): Promise<Page>;
213
  /** Get all targets (pages, workers, etc.) */
214
  targets(): Target[];
215
  /** Get browser version */
216
  version(): Promise<string>;
217
  /** Get browser user agent */
218
  userAgent(): Promise<string>;
219
  /** Close browser and all pages */
220
  close(): Promise<void>;
221
  /** Disconnect from browser without closing */
222
  disconnect(): Promise<void>;
223
  /** Check if browser is connected */
224
  connected: boolean;
225
  /** Get protocol type being used */
226
  protocol: "cdp" | "webDriverBiDi";
227
  /** Install browser extension (Chrome only) */
228
  installExtension(path: string): Promise<string>;
229
  /** Uninstall browser extension (Chrome only) */
230
  uninstallExtension(id: string): Promise<void>;
231
}
232

233
interface BrowserContextOptions {
234
  /** Proxy server settings */
235
  proxyServer?: string;
236
  /** Proxy bypass rules */
237
  proxyBypassList?: string[];
238
  /** Proxy username */
239
  proxyUsername?: string;
240
  /** Proxy password */
241
  proxyPassword?: string;
242
}
243
```
244

245
**Usage Examples:**
246

247
```typescript
248
const browser = await puppeteer.launch({ executablePath: "/path/to/chrome" });
249

250
// Create new page
251
const page = await browser.newPage();
252

253
// Create isolated context
254
const context = await browser.createBrowserContext();
255
const contextPage = await context.newPage();
256

257
// Get browser info
258
const version = await browser.version();
259
const userAgent = await browser.userAgent();
260
const wsEndpoint = browser.wsEndpoint();
261

262
// Check connection
263
if (browser.connected) {
264
  console.log("Browser is connected");
265
}
266

267
// Handle browser events
268
browser.on("disconnected", () => {
269
  console.log("Browser disconnected");
270
});
271

272
browser.on("targetcreated", (target) => {
273
  console.log("New target created:", target.type());
274
});
275

276
// Close browser
277
await browser.close();
278
```
279

280
### Browser Events
281

282
The Browser class emits various events during its lifecycle:
283

284
```typescript { .api }
285
interface BrowserEvents {
286
  /** Emitted when browser disconnects */
287
  "disconnected": () => void;
288
  /** Emitted when new target is created */
289
  "targetcreated": (target: Target) => void;
290
  /** Emitted when target is destroyed */
291
  "targetdestroyed": (target: Target) => void;
292
  /** Emitted when target URL changes */
293
  "targetchanged": (target: Target) => void;
294
}
295
```
296

297
## Error Handling
298

299
Browser management operations can throw several types of errors:
300

301
```typescript { .api }
302
class TimeoutError extends Error {
303
  constructor(message: string);
304
}
305

306
class ProtocolError extends Error {
307
  constructor(message: string);
308
  originalMessage: string;
309
}
310
```
311

312
**Common Error Scenarios:**
313

314
```typescript
315
try {
316
  const browser = await puppeteer.launch({
317
    executablePath: "/invalid/path",
318
    timeout: 30000
319
  });
320
} catch (error) {
321
  if (error instanceof TimeoutError) {
322
    console.log("Browser launch timed out");
323
  } else if (error.message.includes("Failed to launch")) {
324
    console.log("Invalid executable path or browser failed to start");
325
  }
326
}
327
```
328

329
### Device Emulation
330

331
Built-in device emulation capabilities with predefined configurations for common mobile devices and tablets.
332

333
```typescript { .api }
334
interface Device {
335
  userAgent: string;
336
  viewport: Viewport;
337
}
338

339
const KnownDevices: Record<string, Device>;
340

341
// Example known devices (partial list):
342
// - iPhone 15 Pro, iPhone 15 Pro Max
343
// - iPhone 14, iPhone 14 Plus, iPhone 14 Pro, iPhone 14 Pro Max  
344
// - iPhone 13 Pro, iPhone 13 Pro Max, iPhone 13 Mini
345
// - iPhone 12, iPhone 12 Pro, iPhone 12 Pro Max, iPhone 12 Mini
346
// - iPhone 11, iPhone 11 Pro, iPhone 11 Pro Max
347
// - iPhone X, iPhone XR, iPhone 8, iPhone 8 Plus, iPhone 7, iPhone 6
348
// - iPad Pro, iPad Pro 11, iPad, iPad Mini
349
// - Galaxy S9+, Galaxy S8, Galaxy S5, Galaxy Note 3, Galaxy Tab S4
350
// - Pixel 5, Pixel 4, Pixel 3, Pixel 2, Pixel 2 XL
351
// - Nexus 7, Nexus 6P, Nexus 5X, Nexus 5, Nexus 4, Nexus 10
352
// - Moto G4, BlackBerry Z30, Microsoft Lumia 950
353
// - And many more...
354
```
355

356
**Usage Examples:**
357

358
```typescript
359
import puppeteer, { KnownDevices } from "puppeteer-core";
360

361
const browser = await puppeteer.launch({ executablePath: "/path/to/chrome" });
362
const page = await browser.newPage();
363

364
// Emulate iPhone 15 Pro
365
const iPhone15Pro = KnownDevices['iPhone 15 Pro'];
366
await page.emulate(iPhone15Pro);
367

368
// Emulate iPad Pro
369
const iPadPro = KnownDevices['iPad Pro'];
370
await page.emulate(iPadPro);
371

372
// Emulate Galaxy S9+
373
const galaxyS9Plus = KnownDevices['Galaxy S9+'];
374
await page.emulate(galaxyS9Plus);
375

376
// Custom device emulation
377
const customDevice = {
378
  userAgent: 'Mozilla/5.0 (Linux; Android 9; Custom Device) AppleWebKit/537.36',
379
  viewport: {
380
    width: 414,
381
    height: 896,
382
    deviceScaleFactor: 2,
383
    isMobile: true,
384
    hasTouch: true,
385
    isLandscape: false
386
  }
387
};
388
await page.emulate(customDevice);
389

390
await page.goto("https://example.com");
391
await browser.close();
392
```