0
# Browser Configuration
1

2
Comprehensive capability system for configuring browser options, proxy settings, platform preferences, and authentication using the Capabilities interface hierarchy.
3

4
## Capabilities
5

6
### Capabilities Interface
7

8
Core interface for browser capabilities providing platform, version, and feature information.
9

10
```java { .api }
11
/**
12
 * Capabilities interface for browser configuration and feature detection
13
 * Provides access to browser name, version, platform, and custom capabilities
14
 */
15
interface Capabilities {
16
    /**
17
     * Get browser name
18
     * @return Browser name (e.g., "chrome", "firefox", "safari")
19
     */
20
    String getBrowserName();
21
    
22
    /**
23
     * Get browser version
24
     * @return Browser version string
25
     */
26
    String getBrowserVersion();
27
    
28
    /**
29
     * Get platform information
30
     * @return Platform enum value
31
     */
32
    Platform getPlatform();
33
    
34
    /**
35
     * Get platform name as string
36
     * @return Platform name (e.g., "Windows", "Mac", "Linux")
37
     */
38
    String getPlatformName();
39
    
40
    /**
41
     * Get specific capability value
42
     * @param capabilityName - Name of capability to retrieve
43
     * @return Capability value or null if not set
44
     */
45
    Object getCapability(String capabilityName);
46
    
47
    /**
48
     * Get all capability names
49
     * @return Set of all capability names
50
     */
51
    Set<String> getCapabilityNames();
52
    
53
    /**
54
     * Convert capabilities to Map
55
     * @return Map representation of all capabilities
56
     */
57
    Map<String, Object> asMap();
58
}
59
```
60

61
### MutableCapabilities Class
62

63
Mutable implementation of Capabilities interface allowing runtime configuration changes.
64

65
```java { .api }
66
/**
67
 * MutableCapabilities class providing modifiable browser capabilities
68
 * Extends Capabilities with methods to set and modify capability values
69
 */
70
class MutableCapabilities implements Capabilities {
71
    /**
72
     * Create empty MutableCapabilities
73
     */
74
    MutableCapabilities();
75
    
76
    /**
77
     * Create MutableCapabilities from existing capabilities
78
     * @param other - Capabilities to copy from
79
     */
80
    MutableCapabilities(Capabilities other);
81
    
82
    /**
83
     * Create MutableCapabilities from Map
84
     * @param capabilities - Map of capability name-value pairs
85
     */
86
    MutableCapabilities(Map<String, ?> capabilities);
87
    
88
    /**
89
     * Set capability value
90
     * @param name - Capability name
91
     * @param value - Capability value
92
     * @return MutableCapabilities instance for chaining
93
     */
94
    MutableCapabilities setCapability(String name, Object value);
95
    
96
    /**
97
     * Merge capabilities from another Capabilities object
98
     * @param other - Capabilities to merge
99
     * @return MutableCapabilities instance for chaining
100
     */
101
    MutableCapabilities merge(Capabilities other);
102
}
103
```
104

105
### ImmutableCapabilities Class
106

107
Immutable implementation of Capabilities interface providing read-only capability access.
108

109
```java { .api }
110
/**
111
 * ImmutableCapabilities class providing read-only browser capabilities
112
 * Thread-safe implementation of Capabilities that cannot be modified after creation
113
 */
114
class ImmutableCapabilities implements Capabilities {
115
    /**
116
     * Create ImmutableCapabilities from Map
117
     * @param capabilities - Map of capability name-value pairs
118
     */
119
    ImmutableCapabilities(Map<String, ?> capabilities);
120
    
121
    /**
122
     * Create ImmutableCapabilities from key-value pairs
123
     * @param key - First capability name
124
     * @param value - First capability value
125
     * @param more - Additional key-value pairs (alternating keys and values)
126
     */
127
    ImmutableCapabilities(String key, Object value, Object... more);
128
}
129
```
130

131
### Proxy Configuration
132

133
Proxy server configuration for routing browser traffic through proxy servers.
134

135
```java { .api }
136
/**
137
 * Proxy class for configuring proxy server settings
138
 * Supports HTTP, HTTPS, FTP, and SOCKS proxy configurations
139
 */
140
class Proxy {
141
    /**
142
     * Create Proxy with default settings
143
     */
144
    Proxy();
145
    
146
    /**
147
     * Set proxy type
148
     * @param proxyType - Type of proxy (DIRECT, MANUAL, PAC, AUTODETECT, SYSTEM)
149
     * @return Proxy instance for chaining
150
     */
151
    Proxy setProxyType(ProxyType proxyType);
152
    
153
    /**
154
     * Set HTTP proxy server
155
     * @param httpProxy - Proxy server in format "host:port"
156
     * @return Proxy instance for chaining
157
     */
158
    Proxy setHttpProxy(String httpProxy);
159
    
160
    /**
161
     * Set HTTPS/SSL proxy server
162
     * @param sslProxy - SSL proxy server in format "host:port"
163
     * @return Proxy instance for chaining
164
     */
165
    Proxy setSslProxy(String sslProxy);
166
    
167
    /**
168
     * Set FTP proxy server
169
     * @param ftpProxy - FTP proxy server in format "host:port"
170
     * @return Proxy instance for chaining
171
     */
172
    Proxy setFtpProxy(String ftpProxy);
173
    
174
    /**
175
     * Set SOCKS proxy server
176
     * @param socksProxy - SOCKS proxy server in format "host:port"
177
     * @return Proxy instance for chaining
178
     */
179
    Proxy setSocksProxy(String socksProxy);
180
    
181
    /**
182
     * Set hosts to bypass proxy
183
     * @param noProxy - Comma-separated list of hosts to bypass
184
     * @return Proxy instance for chaining
185
     */
186
    Proxy setNoProxy(String noProxy);
187
    
188
    /**
189
     * Set proxy authentication username
190
     * @param socksUsername - Username for SOCKS proxy authentication
191
     * @return Proxy instance for chaining
192
     */
193
    Proxy setSocksUsername(String socksUsername);
194
    
195
    /**
196
     * Set proxy authentication password
197
     * @param socksPassword - Password for SOCKS proxy authentication
198
     * @return Proxy instance for chaining
199
     */
200
    Proxy setSocksPassword(String socksPassword);
201
}
202

203
enum ProxyType {
204
    DIRECT, MANUAL, PAC, RESERVED_1, AUTODETECT, SYSTEM
205
}
206
```
207

208
## Usage Examples
209

210
### Basic Capabilities Configuration
211

212
```java
213
import org.openqa.selenium.MutableCapabilities;
214
import org.openqa.selenium.ImmutableCapabilities;
215
import org.openqa.selenium.Platform;
216

217
// Create mutable capabilities
218
MutableCapabilities capabilities = new MutableCapabilities();
219
capabilities.setCapability("browserName", "chrome");
220
capabilities.setCapability("browserVersion", "latest");
221
capabilities.setCapability("platformName", "Windows 10");
222

223
// Add custom capabilities
224
capabilities.setCapability("enableVNC", true);
225
capabilities.setCapability("enableVideo", false);
226
capabilities.setCapability("screenResolution", "1920x1080x24");
227

228
// Create immutable capabilities
229
ImmutableCapabilities immutableCaps = new ImmutableCapabilities(
230
    "browserName", "firefox",
231
    "browserVersion", "91.0",
232
    "platformName", "Linux"
233
);
234

235
// Access capability values
236
String browserName = capabilities.getBrowserName();
237
String browserVersion = capabilities.getBrowserVersion();
238
Platform platform = capabilities.getPlatform();
239
Object customValue = capabilities.getCapability("enableVNC");
240

241
// Convert to map for inspection
242
Map<String, Object> capsMap = capabilities.asMap();
243
System.out.println("All capabilities: " + capsMap);
244
```
245

246
### Proxy Configuration
247

248
```java
249
import org.openqa.selenium.Proxy;
250
import org.openqa.selenium.chrome.ChromeOptions;
251

252
// HTTP proxy configuration
253
Proxy proxy = new Proxy();
254
proxy.setProxyType(ProxyType.MANUAL);
255
proxy.setHttpProxy("proxy.company.com:8080");
256
proxy.setSslProxy("proxy.company.com:8080");
257

258
// Exclude certain hosts from proxy
259
proxy.setNoProxy("localhost,127.0.0.1,*.local");
260

261
// SOCKS proxy with authentication
262
Proxy socksProxy = new Proxy();
263
socksProxy.setProxyType(ProxyType.MANUAL);
264
socksProxy.setSocksProxy("socks.proxy.com:1080");
265
socksProxy.setSocksUsername("proxyuser");
266
socksProxy.setSocksPassword("proxypass");
267

268
// Apply proxy to browser options
269
ChromeOptions options = new ChromeOptions();
270
options.setCapability(CapabilityType.PROXY, proxy);
271

272
WebDriver driver = new ChromeDriver(options);
273
```
274

275
### Advanced Capabilities Patterns
276

277
```java
278
// Merge capabilities from multiple sources
279
MutableCapabilities baseCapabilities = new MutableCapabilities();
280
baseCapabilities.setCapability("browserName", "chrome");
281
baseCapabilities.setCapability("browserVersion", "latest");
282

283
MutableCapabilities testCapabilities = new MutableCapabilities();
284
testCapabilities.setCapability("enableVNC", true);
285
testCapabilities.setCapability("name", "My Test");
286

287
// Merge test capabilities into base
288
baseCapabilities.merge(testCapabilities);
289

290
// Platform-specific capabilities
291
MutableCapabilities windowsCapabilities = new MutableCapabilities();
292
windowsCapabilities.setCapability("platformName", "Windows 10");
293
windowsCapabilities.setCapability("browserName", "edge");
294

295
MutableCapabilities macCapabilities = new MutableCapabilities();
296
macCapabilities.setCapability("platformName", "macOS Big Sur");
297
macCapabilities.setCapability("browserName", "safari");
298

299
MutableCapabilities linuxCapabilities = new MutableCapabilities();
300
linuxCapabilities.setCapability("platformName", "Linux");
301
linuxCapabilities.setCapability("browserName", "firefox");
302

303
// Select capabilities based on environment
304
String osName = System.getProperty("os.name").toLowerCase();
305
MutableCapabilities platformCaps;
306
if (osName.contains("windows")) {
307
    platformCaps = windowsCapabilities;
308
} else if (osName.contains("mac")) {
309
    platformCaps = macCapabilities;
310
} else {
311
    platformCaps = linuxCapabilities;
312
}
313
```
314

315
### Grid and Remote Configuration
316

317
```java
318
// Cloud provider capabilities (Sauce Labs example)
319
MutableCapabilities sauceCapabilities = new MutableCapabilities();
320
sauceCapabilities.setCapability("platformName", "Windows 10");
321
sauceCapabilities.setCapability("browserName", "chrome");
322
sauceCapabilities.setCapability("browserVersion", "latest");
323
sauceCapabilities.setCapability("sauce:options", Map.of(
324
    "username", "your-username",
325
    "accessKey", "your-access-key",
326
    "name", "My Test Name",
327
    "build", "Build 123",
328
    "tags", Arrays.asList("tag1", "tag2")
329
));
330

331
// BrowserStack capabilities
332
MutableCapabilities browserStackCaps = new MutableCapabilities();
333
browserStackCaps.setCapability("os", "Windows");
334
browserStackCaps.setCapability("os_version", "10");
335
browserStackCaps.setCapability("browser", "Chrome");
336
browserStackCaps.setCapability("browser_version", "latest");
337
browserStackCaps.setCapability("bstack:options", Map.of(
338
    "userName", "your-username",
339
    "accessKey", "your-access-key",
340
    "projectName", "My Project",
341
    "buildName", "Build 123"
342
));
343

344
// Local Selenium Grid capabilities
345
MutableCapabilities gridCapabilities = new MutableCapabilities();
346
gridCapabilities.setCapability("browserName", "chrome");
347
gridCapabilities.setCapability("se:options", Map.of(
348
    "screenResolution", "1920x1080",
349
    "enableVNC", true,
350
    "enableVideo", true
351
));
352

353
// Use with RemoteWebDriver
354
RemoteWebDriver remoteDriver = new RemoteWebDriver(
355
    new URL("https://ondemand.saucelabs.com:443/wd/hub"),
356
    sauceCapabilities
357
);
358
```
359

360
### Mobile and Device Emulation
361

362
```java
363
// Mobile capabilities for Appium
364
MutableCapabilities mobileCapabilities = new MutableCapabilities();
365
mobileCapabilities.setCapability("platformName", "iOS");
366
mobileCapabilities.setCapability("platformVersion", "14.5");
367
mobileCapabilities.setCapability("deviceName", "iPhone 12");
368
mobileCapabilities.setCapability("browserName", "Safari");
369
mobileCapabilities.setCapability("automationName", "XCUITest");
370

371
// Android mobile capabilities
372
MutableCapabilities androidCapabilities = new MutableCapabilities();
373
androidCapabilities.setCapability("platformName", "Android");
374
androidCapabilities.setCapability("platformVersion", "11.0");
375
androidCapabilities.setCapability("deviceName", "Pixel 4");
376
androidCapabilities.setCapability("browserName", "Chrome");
377
androidCapabilities.setCapability("automationName", "UiAutomator2");
378

379
// Chrome mobile emulation
380
ChromeOptions chromeOptions = new ChromeOptions();
381
chromeOptions.setExperimentalOption("mobileEmulation", Map.of(
382
    "deviceName", "iPhone X"
383
));
384

385
// Custom mobile emulation
386
Map<String, Object> deviceMetrics = Map.of(
387
    "width", 375,
388
    "height", 812,
389
    "pixelRatio", 3.0
390
);
391
chromeOptions.setExperimentalOption("mobileEmulation", Map.of(
392
    "deviceMetrics", deviceMetrics,
393
    "userAgent", "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)"
394
));
395
```
396

397
### Performance and Logging Configuration
398

399
```java
400
// Performance logging capabilities
401
MutableCapabilities perfCapabilities = new MutableCapabilities();
402
LoggingPreferences logPrefs = new LoggingPreferences();
403
logPrefs.enable(LogType.PERFORMANCE, Level.INFO);
404
logPrefs.enable(LogType.BROWSER, Level.WARNING);
405
logPrefs.enable(LogType.DRIVER, Level.INFO);
406

407
perfCapabilities.setCapability(CapabilityType.LOGGING_PREFS, logPrefs);
408

409
// Network throttling (Chrome DevTools)
410
ChromeOptions chromeOptions = new ChromeOptions();
411
chromeOptions.setExperimentalOption("useAutomationExtension", false);
412
chromeOptions.setExperimentalOption("excludeSwitches", Arrays.asList("enable-automation"));
413

414
// Custom performance flags
415
chromeOptions.addArguments("--enable-precise-memory-info");
416
chromeOptions.addArguments("--enable-benchmarking");
417
chromeOptions.addArguments("--enable-net-benchmarking");
418

419
perfCapabilities.merge(chromeOptions);
420
```
421

422
### Security and Privacy Configuration
423

424
```java
425
// Incognito/private browsing
426
ChromeOptions incognitoOptions = new ChromeOptions();
427
incognitoOptions.addArguments("--incognito");
428

429
FirefoxOptions privateOptions = new FirefoxOptions();  
430
privateOptions.addArguments("-private");
431

432
// Disable web security (for testing only)
433
ChromeOptions unsafeOptions = new ChromeOptions();
434
unsafeOptions.addArguments("--disable-web-security");
435
unsafeOptions.addArguments("--disable-features=VizDisplayCompositor");
436
unsafeOptions.addArguments("--allow-running-insecure-content");
437

438
// Certificate handling
439
MutableCapabilities certCapabilities = new MutableCapabilities();
440
certCapabilities.setCapability(CapabilityType.ACCEPT_INSECURE_CERTS, true);
441
certCapabilities.setCapability(CapabilityType.ACCEPT_SSL_CERTS, true);
442
```