0
# Browser Control
1

2
Core browser automation functionality for launching browsers, managing contexts, and controlling browser lifecycle across Chromium, Firefox, and WebKit.
3

4
## Capabilities
5

6
### Browser Types
7

8
Entry points for launching different browser engines with consistent API across all browsers.
9

10
```typescript { .api }
11
/**
12
 * Chromium browser automation (Google Chrome, Microsoft Edge)
13
 */
14
const chromium: BrowserType;
15

16
/**  
17
 * Firefox browser automation
18
 */
19
const firefox: BrowserType;
20

21
/**
22
 * WebKit browser automation (Safari)  
23
 */
24
const webkit: BrowserType;
25

26
interface BrowserType {
27
  /** Launch a new browser instance */
28
  launch(options?: LaunchOptions): Promise<Browser>;
29
  /** Launch browser with persistent user data directory */
30
  launchPersistentContext(userDataDir: string, options?: BrowserContextOptions & LaunchOptions): Promise<BrowserContext>;
31
  /** Connect to existing browser via WebSocket */
32
  connect(wsEndpoint: string, options?: ConnectOptions): Promise<Browser>;
33
  /** Get executable path for this browser type */
34
  executablePath(): string;
35
  /** Get browser name identifier */
36
  name(): string;
37
}
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { chromium, firefox, webkit } from 'playwright';
44

45
// Launch different browsers
46
const chromeAuth = await chromium.launch({ headless: false });
47
const firefoxBrowser = await firefox.launch();
48
const safariNrowser = await webkit.launch();
49

50
// Launch with custom executable
51
const customChromium = await chromium.launch({
52
  executablePath: '/path/to/chrome',
53
  args: ['--disable-web-security']
54
});
55

56
// Persistent context (keeps user data)
57
const persistentContext = await chromium.launchPersistentContext('./user-data', {
58
  headless: false,
59
  viewport: { width: 1280, height: 720 }
60
});
61
```
62

63
### Browser Management
64

65
Control browser instances, manage contexts for isolation, and handle browser lifecycle.
66

67
```typescript { .api }
68
interface Browser {
69
  /** Create new isolated browser context */
70
  newContext(options?: BrowserContextOptions): Promise<BrowserContext>;
71
  /** Get all browser contexts */
72
  contexts(): BrowserContext[];
73
  /** Create new page in default context */
74
  newPage(options?: BrowserContextOptions): Promise<Page>;
75
  /** Close browser and all pages */  
76
  close(): Promise<void>;
77
  /** Check if browser is connected */
78
  isConnected(): boolean;
79
  /** Get browser version */
80
  version(): string;
81
  /** Browser type name */
82
  browserType(): BrowserType;
83
}
84

85
interface BrowserContext {
86
  /** Create new page in this context */
87
  newPage(): Promise<Page>;
88
  /** Get all pages in this context */
89
  pages(): Page[];
90
  /** Close context and all its pages */
91
  close(): Promise<void>;
92
  /** Add cookies to context */
93
  addCookies(cookies: Cookie[]): Promise<void>;
94
  /** Get all cookies */
95
  cookies(urls?: string | string[]): Promise<Cookie[]>;
96
  /** Clear cookies */
97
  clearCookies(): Promise<void>;
98
  /** Set geolocation */
99
  setGeolocation(geolocation: Geolocation | null): Promise<void>;
100
  /** Grant permissions */
101
  grantPermissions(permissions: string[], options?: BrowserContextGrantPermissionsOptions): Promise<void>;
102
}
103
```
104

105
**Usage Examples:**
106

107
```typescript  
108
// Create isolated contexts
109
const context1 = await browser.newContext({
110
  viewport: { width: 1920, height: 1080 },
111
  userAgent: 'Custom Agent',
112
  locale: 'en-US'
113
});
114

115
const context2 = await browser.newContext({
116
  geolocation: { latitude: 37.7749, longitude: -122.4194 },
117
  permissions: ['geolocation']
118
});
119

120
// Manage cookies
121
await context1.addCookies([
122
  {
123
    name: 'session',
124
    value: 'abc123',
125
    domain: '.example.com',
126
    path: '/'
127
  }
128
]);
129

130
// Create pages
131
const page1 = await context1.newPage(); 
132
const page2 = await context2.newPage();
133

134
// Cleanup
135
await context1.close();
136
await context2.close();
137
await browser.close();
138
```
139

140
### Browser Server
141

142
Remote browser server management for distributed testing and browser reuse.
143

144
```typescript { .api }
145
interface BrowserServer {
146
  /** Get WebSocket endpoint for connecting */
147
  wsEndpoint(): string;
148
  /** Close browser server */
149
  close(): Promise<void>;
150
  /** Kill browser server process */
151
  kill(): Promise<void>;
152
  /** Get process object */
153
  process(): ChildProcess;
154
}
155
```
156

157
**Usage Examples:**
158

159
```typescript
160
// Launch browser server
161
const browserServer = await chromium.launchServer({
162
  port: 9222,
163
  headless: false
164
});
165

166
// Connect from different process
167
const browser = await chromium.connect(browserServer.wsEndpoint());
168
const page = await browser.newPage();
169

170
// Cleanup
171
await browser.close();
172
await browserServer.close();
173
```
174

175
### Chrome DevTools Protocol
176

177
Direct access to Chrome DevTools Protocol for advanced browser control.
178

179
```typescript { .api }  
180
interface CDPSession {
181
  /** Send CDP command */
182
  send(method: string, params?: any): Promise<any>;
183
  /** Detach from target */
184
  detach(): Promise<void>;
185
}
186

187
interface BrowserContext {
188
  /** Create CDP session for new targets */
189
  newCDPSession(page: Page): Promise<CDPSession>;
190
}
191
```
192

193
## Types
194

195
### Launch Configuration
196

197
```typescript { .api }
198
interface LaunchOptions {
199
  /** Run in headless mode */
200
  headless?: boolean;
201
  /** Path to browser executable */
202
  executablePath?: string;
203
  /** Additional arguments to pass to browser */
204
  args?: string[];
205
  /** Ignore default arguments */  
206
  ignoreDefaultArgs?: boolean | string[];
207
  /** Proxy settings */
208
  proxy?: ProxySettings;
209
  /** Downloads directory */
210
  downloadsPath?: string;
211
  /** Chrome sandbox mode */
212
  chromiumSandbox?: boolean;
213
  /** Firefox user preferences */
214
  firefoxUserPrefs?: { [key: string]: string | number | boolean };
215
  /** Handle SIGINT, SIGTERM, SIGHUP */
216
  handleSIGINT?: boolean;
217
  handleSIGTERM?: boolean;  
218
  handleSIGHUP?: boolean;
219
  /** Timeout for browser to launch */
220
  timeout?: number;
221
  /** Environment variables */
222
  env?: { [key: string]: string | number | boolean };
223
  /** Slow down operations by N milliseconds */
224
  slowMo?: number;
225
}
226

227
interface ConnectOptions {
228
  /** WebSocket endpoint URL */
229
  wsEndpoint?: string;
230
  /** Connection timeout */
231
  timeout?: number;
232
  /** Slow down operations */
233
  slowMo?: number;
234
  /** Headers for WebSocket connection */
235
  headers?: { [key: string]: string };
236
}
237

238
interface ConnectOverCDPOptions {
239
  /** CDP endpoint URL */  
240
  endpointURL: string;
241
  /** Connection timeout */
242
  timeout?: number;
243
  /** Slow down operations */
244
  slowMo?: number;
245
  /** Headers for connection */
246
  headers?: { [key: string]: string };
247
}
248

249
interface ProxySettings {
250
  /** Proxy server URL */
251
  server: string;
252
  /** Bypass proxy for these patterns */
253
  bypass?: string;
254
  /** Username for proxy auth */
255
  username?: string;
256
  /** Password for proxy auth */
257
  password?: string;
258
}
259
```
260

261
### Context Configuration
262

263
```typescript { .api }
264
interface BrowserContextOptions {
265
  /** Viewport size (null for no viewport) */
266
  viewport?: ViewportSize | null;
267
  /** User agent string */
268
  userAgent?: string;
269
  /** Locale identifier */
270
  locale?: string;
271
  /** Timezone identifier */
272
  timezoneId?: string;
273
  /** Geolocation */
274
  geolocation?: Geolocation;
275
  /** Granted permissions */
276
  permissions?: string[];
277
  /** HTTP credentials */  
278
  httpCredentials?: HTTPCredentials;
279
  /** Start in offline mode */
280
  offline?: boolean;
281
  /** Ignore HTTPS errors */
282
  ignoreHTTPSErrors?: boolean;
283
  /** Color scheme preference */
284
  colorScheme?: 'light' | 'dark' | 'no-preference';
285
  /** Reduced motion preference */
286
  reducedMotion?: 'reduce' | 'no-preference';
287
  /** Accept downloads */
288
  acceptDownloads?: boolean;
289
  /** Extra HTTP headers */
290
  extraHTTPHeaders?: { [key: string]: string };
291
  /** Client certificates */
292
  clientCertificates?: ClientCertificate[];
293
  /** Har recording options */
294
  recordHar?: { 
295
    omitContent?: boolean;
296
    path: string;
297
  };
298
  /** Video recording options */
299
  recordVideo?: {
300
    dir: string;
301
    size?: ViewportSize;
302
  };
303
}
304

305
interface Cookie {
306
  name: string;
307
  value: string;
308
  domain?: string;
309
  path?: string;
310
  expires?: number;
311
  httpOnly?: boolean;
312
  secure?: boolean;
313
  sameSite?: 'Strict' | 'Lax' | 'None';
314
}
315

316
interface ClientCertificate {
317
  /** Certificate origin */
318
  origin: string;
319
  /** Path to certificate file */
320
  certPath?: string;
321
  /** Path to key file */  
322
  keyPath?: string;
323
  /** Passphrase for key */
324
  passphrase?: string;
325
  /** Certificate in PFX format */
326
  pfxPath?: string;
327
}
328
```