0
# Browser Capabilities
1

2
WebDriver capabilities and browser-specific configuration options for defining browser behavior, device settings, and cloud service integrations.
3

4
## Capabilities
5

6
### W3C Capabilities Structure
7

8
Standard WebDriver capabilities format supporting modern browsers and services.
9

10
```typescript { .api }
11
/**
12
 * W3C WebDriver capabilities structure
13
 */
14
interface W3CCapabilities {
15
  /** Required capabilities that must be satisfied */
16
  alwaysMatch?: WebdriverIO.Capabilities;
17
  /** Array of alternative capability sets, at least one must be satisfied */
18
  firstMatch?: WebdriverIO.Capabilities[];
19
}
20

21
/**
22
 * Core WebDriver capabilities
23
 */
24
interface Capabilities {
25
  /** Browser name (chrome, firefox, safari, MicrosoftEdge, etc.) */
26
  browserName?: string;
27
  /** Browser version */
28
  browserVersion?: string;
29
  /** Operating system platform */
30
  platformName?: string;
31
  /** Accept insecure/self-signed certificates */
32
  acceptInsecureCerts?: boolean;
33
  /** Page load strategy: none, eager, or normal */
34
  pageLoadStrategy?: PageLoadingStrategy;
35
  /** Proxy configuration */
36
  proxy?: ProxyObject;
37
  /** Window resizing/repositioning support */
38
  setWindowRect?: boolean;
39
  /** Session timeout configuration */
40
  timeouts?: Timeouts;
41
  /** Strict file upload interactability */
42
  strictFileInteractability?: boolean;
43
  /** Unhandled prompt behavior */
44
  unhandledPromptBehavior?: string;
45
  /** WebSocket URL for bidirectional communication */
46
  webSocketUrl?: boolean;
47
}
48
```
49

50
### Browser-Specific Options
51

52
#### Chrome Options
53

54
Chrome and Chromium browser configuration including command-line arguments and preferences.
55

56
```typescript { .api }
57
interface ChromeOptions {
58
  /** Chrome binary path */
59
  binary?: string;
60
  /** Command-line arguments */
61
  args?: string[];
62
  /** Chrome extensions as base64 strings */
63
  extensions?: string[];
64
  /** Local state preferences */
65
  localState?: Record<string, any>;
66
  /** User preferences */
67
  prefs?: Record<string, any>;
68
  /** Detach browser from driver */
69
  detach?: boolean;
70
  /** Debug port */
71
  debuggerAddress?: string;
72
  /** Exclude switches */
73
  excludeSwitches?: string[];
74
  /** Minidump path */
75
  minidumpPath?: string;
76
  /** Mobile emulation */
77
  mobileEmulation?: {
78
    deviceName?: string;
79
    deviceMetrics?: {
80
      width: number;
81
      height: number;
82
      pixelRatio: number;
83
    };
84
    userAgent?: string;
85
  };
86
  /** Performance logging */
87
  perfLoggingPrefs?: {
88
    enableNetwork?: boolean;
89
    enablePage?: boolean;
90
    enableTimeline?: boolean;
91
    tracingCategories?: string;
92
    bufferUsageReportingInterval?: number;
93
  };
94
  /** Window types */
95
  windowTypes?: string[];
96
}
97
```
98

99
#### Firefox Options
100

101
Firefox browser configuration including profile settings and logging.
102

103
```typescript { .api }
104
interface FirefoxOptions {
105
  /** Firefox binary path */
106
  binary?: string;
107
  /** Command-line arguments */
108
  args?: string[];
109
  /** Firefox profile object or path */
110
  profile?: string | FirefoxProfile;
111
  /** Logging configuration */
112
  log?: FirefoxLogObject;
113
  /** User preferences */
114
  prefs?: Record<string, any>;
115
  /** Environment variables */
116
  env?: Record<string, string>;
117
}
118

119
interface FirefoxLogObject {
120
  level?: 'trace' | 'debug' | 'config' | 'info' | 'warn' | 'error' | 'fatal';
121
}
122
```
123

124
### Mobile Capabilities
125

126
#### Appium Android Capabilities
127

128
Android device automation configuration for Appium.
129

130
```typescript { .api }
131
interface AppiumAndroidCapabilities {
132
  /** Android package name */
133
  'appium:appPackage'?: string;
134
  /** Android activity name */
135
  'appium:appActivity'?: string;
136
  /** Wait for activity */
137
  'appium:appWaitActivity'?: string;
138
  /** Device name */
139
  'appium:deviceName'?: string;
140
  /** Platform version */
141
  'appium:platformVersion'?: string;
142
  /** Automation name */
143
  'appium:automationName'?: 'UiAutomator2' | 'Espresso';
144
  /** App path or URL */
145
  'appium:app'?: string;
146
  /** No reset */
147
  'appium:noReset'?: boolean;
148
  /** Full reset */
149
  'appium:fullReset'?: boolean;
150
  /** Auto-grant permissions */
151
  'appium:autoGrantPermissions'?: boolean;
152
  /** System port */
153
  'appium:systemPort'?: number;
154
  /** Chrome driver executable path */
155
  'appium:chromedriverExecutable'?: string;
156
}
157
```
158

159
#### Appium iOS Capabilities
160

161
iOS device automation configuration for Appium XCUITest.
162

163
```typescript { .api }
164
interface AppiumXCUITestCapabilities {
165
  /** iOS bundle identifier */
166
  'appium:bundleId'?: string;
167
  /** Device name */
168
  'appium:deviceName'?: string;
169
  /** Platform version */
170
  'appium:platformVersion'?: string;
171
  /** Automation name */
172
  'appium:automationName'?: 'XCUITest';
173
  /** App path or URL */
174
  'appium:app'?: string;
175
  /** UDID for real devices */
176
  'appium:udid'?: string;
177
  /** Xcode organization team identifier */
178
  'appium:xcodeOrgId'?: string;
179
  /** Xcode signing certificate */
180
  'appium:xcodeSigningId'?: string;
181
  /** Auto-accept alerts */
182
  'appium:autoAcceptAlerts'?: boolean;
183
  /** Auto-dismiss alerts */
184
  'appium:autoDismissAlerts'?: boolean;
185
  /** WDA local port */
186
  'appium:wdaLocalPort'?: number;
187
  /** Simulator startup timeout */
188
  'appium:launchTimeout'?: number;
189
}
190
```
191

192
### Cloud Service Capabilities
193

194
#### Sauce Labs
195

196
Sauce Labs cloud testing service configuration.
197

198
```typescript { .api }
199
interface SauceLabsCapabilities {
200
  /** Sauce Labs username */
201
  'sauce:options'?: {
202
    username?: string;
203
    accessKey?: string;
204
    /** Build identifier */
205
    build?: string;
206
    /** Test name */
207
    name?: string;
208
    /** Tags for organizing tests */
209
    tags?: string[];
210
    /** Custom data */
211
    customData?: Record<string, any>;
212
    /** Selenium version */
213
    seleniumVersion?: string;
214
    /** Screen resolution */
215
    screenResolution?: string;
216
    /** Timezone */
217
    timeZone?: string;
218
    /** Idle timeout */
219
    idleTimeout?: number;
220
    /** Command timeout */
221
    commandTimeout?: number;
222
    /** Max duration */
223
    maxDuration?: number;
224
  };
225
}
226
```
227

228
#### BrowserStack
229

230
BrowserStack cloud testing service configuration.
231

232
```typescript { .api }
233
interface BrowserStackCapabilities {
234
  /** BrowserStack options */
235
  'bstack:options'?: {
236
    /** Username */
237
    userName?: string;
238
    /** Access key */
239
    accessKey?: string;
240
    /** Project name */
241
    projectName?: string;
242
    /** Build name */
243
    buildName?: string;
244
    /** Session name */
245
    sessionName?: string;
246
    /** Debug mode */
247
    debug?: boolean;
248
    /** Network logs */
249
    networkLogs?: boolean;
250
    /** Console logs */
251
    consoleLogs?: 'errors' | 'warnings' | 'info' | 'verbose';
252
    /** Selenium version */
253
    seleniumVersion?: string;
254
    /** Mobile test */
255
    realMobile?: boolean;
256
  };
257
}
258
```
259

260
### Proxy Configuration
261

262
Network proxy settings for WebDriver sessions.
263

264
```typescript { .api }
265
/**
266
 * Proxy configuration types
267
 */
268
type ProxyTypes = 'pac' | 'noproxy' | 'autodetect' | 'system' | 'manual';
269

270
interface ProxyObject {
271
  /** Proxy type */
272
  proxyType?: ProxyTypes;
273
  /** PAC file URL */
274
  proxyAutoconfigUrl?: string;
275
  /** FTP proxy settings */
276
  ftpProxy?: string;
277
  ftpProxyPort?: number;
278
  /** HTTP proxy settings */
279
  httpProxy?: string;
280
  httpProxyPort?: number;
281
  /** SSL proxy settings */
282
  sslProxy?: string;
283
  sslProxyPort?: number;
284
  /** SOCKS proxy settings */
285
  socksProxy?: string;
286
  socksProxyPort?: number;
287
  socksVersion?: string;
288
  socksUsername?: string;
289
  socksPassword?: string;
290
  /** Proxy bypass list */
291
  noProxy?: string[];
292
}
293
```
294

295
### Timeouts and Logging
296

297
Session timeout configuration and logging preferences.
298

299
```typescript { .api }
300
/**
301
 * WebDriver timeouts
302
 */
303
type Timeouts = Record<'script' | 'pageLoad' | 'implicit', number>;
304

305
/**
306
 * Logging preference levels
307
 */
308
type LoggingPreferenceType = 'OFF' | 'SEVERE' | 'WARNING' | 'INFO' | 'CONFIG' | 'FINE' | 'FINER' | 'FINEST' | 'ALL';
309

310
interface LoggingPreferences {
311
  /** Browser logging level */
312
  browser?: LoggingPreferenceType;
313
  /** Driver logging level */
314
  driver?: LoggingPreferenceType;
315
  /** Server logging level */
316
  server?: LoggingPreferenceType;
317
  /** Client logging level */
318
  client?: LoggingPreferenceType;
319
}
320

321
/**
322
 * Page loading strategies
323
 */
324
type PageLoadingStrategy = 'none' | 'eager' | 'normal';
325
```
326

327
### Capability Type Helpers
328

329
Type aliases for different capability usage patterns.
330

331
```typescript { .api }
332
/**
333
 * Standalone capability types
334
 */
335
type RequestedStandaloneCapabilities = W3CCapabilities | WebdriverIO.Capabilities;
336

337
/**
338
 * Multi-remote capability configuration
339
 */
340
type RequestedMultiremoteCapabilities = Record<string, RequestedStandaloneCapabilities>;
341

342
/**
343
 * Test runner capability types
344
 */
345
type TestrunnerCapabilities = 
346
  | RequestedStandaloneCapabilities
347
  | RequestedStandaloneCapabilities[]
348
  | RequestedMultiremoteCapabilities;
349

350
/**
351
 * Resolved capability types for worker instances
352
 */
353
type ResolvedTestrunnerCapabilities = 
354
  | WebdriverIO.Capabilities
355
  | WebdriverIO.Capabilities[]
356
  | Record<string, WebdriverIO.Capabilities>;
357
```