0
# Capabilities Management
1

2
Browser capability specification and negotiation system for defining browser requirements and configuration options. This system enables precise control over browser behavior, feature support, and testing environment configuration in both local and remote WebDriver scenarios.
3

4
## Capabilities
5

6
### DesiredCapabilities
7

8
Mutable capabilities implementation for specifying browser requirements and configuration options.
9

10
```java { .api }
11
/**
12
 * Mutable capabilities implementation for specifying browser requirements
13
 */
14
public class DesiredCapabilities implements MutableCapabilities {
15
    
16
    // Constructors
17
    public DesiredCapabilities();
18
    public DesiredCapabilities(String browser, String version, Platform platform);
19
    public DesiredCapabilities(Map<String, ?> rawMap);
20
    public DesiredCapabilities(Capabilities other);
21
    public DesiredCapabilities(Capabilities... others);
22
    
23
    // Browser configuration
24
    public void setBrowserName(String browserName);
25
    public void setVersion(String version);
26
    public void setPlatform(Platform platform);
27
    
28
    // Security settings
29
    public boolean acceptInsecureCerts();
30
    public void setAcceptInsecureCerts(boolean acceptInsecureCerts);
31
    
32
    // Capability merging
33
    public DesiredCapabilities merge(Capabilities extraCapabilities);
34
}
35
```
36

37
**Usage Examples:**
38

39
```java
40
import org.openqa.selenium.remote.DesiredCapabilities;
41
import org.openqa.selenium.Platform;
42

43
// Basic browser specification
44
DesiredCapabilities capabilities = new DesiredCapabilities();
45
capabilities.setBrowserName("chrome");
46
capabilities.setVersion("latest");
47
capabilities.setPlatform(Platform.LINUX);
48

49
// Constructor with parameters
50
DesiredCapabilities chromeCapabilities = new DesiredCapabilities("chrome", "latest", Platform.ANY);
51

52
// Security configuration
53
capabilities.setAcceptInsecureCerts(true);
54

55
// From map
56
Map<String, Object> capMap = Map.of(
57
    "browserName", "firefox",
58
    "browserVersion", "114.0",
59
    "acceptInsecureCerts", true
60
);
61
DesiredCapabilities fromMap = new DesiredCapabilities(capMap);
62

63
// Merging capabilities
64
DesiredCapabilities baseCapabilities = new DesiredCapabilities("chrome", null, Platform.ANY);
65
DesiredCapabilities additionalCapabilities = new DesiredCapabilities();
66
additionalCapabilities.setAcceptInsecureCerts(true);
67
DesiredCapabilities merged = baseCapabilities.merge(additionalCapabilities);
68
```
69

70
### CapabilityType Constants
71

72
Standard WebDriver capability names defined by the W3C specification.
73

74
```java { .api }
75
/**
76
 * Constants for standard WebDriver capabilities
77
 */
78
public interface CapabilityType {
79
    
80
    // Core browser capabilities
81
    String BROWSER_NAME = "browserName";
82
    String PLATFORM_NAME = "platformName";  
83
    String BROWSER_VERSION = "browserVersion";
84
    
85
    // Security and behavior
86
    String ACCEPT_INSECURE_CERTS = "acceptInsecureCerts";
87
    String PAGE_LOAD_STRATEGY = "pageLoadStrategy";
88
    String UNHANDLED_PROMPT_BEHAVIOUR = "unhandledPromptBehavior";
89
    String STRICT_FILE_INTERACTABILITY = "strictFileInteractability";
90
    
91
    // Window and positioning
92
    String SET_WINDOW_RECT = "setWindowRect";
93
    
94
    // Network and proxy
95
    String PROXY = "proxy";
96
    
97
    // Timeouts
98
    String TIMEOUTS = "timeouts";
99
    
100
    // Selenium-specific extensions
101
    String ENABLE_DOWNLOADS = "se:downloadsEnabled";
102
}
103
```
104

105
**Usage Examples:**
106

107
```java
108
import org.openqa.selenium.remote.CapabilityType;
109
import org.openqa.selenium.MutableCapabilities;
110

111
// Using capability constants
112
MutableCapabilities capabilities = new MutableCapabilities();
113
capabilities.setCapability(CapabilityType.BROWSER_NAME, "chrome");
114
capabilities.setCapability(CapabilityType.BROWSER_VERSION, "latest");
115
capabilities.setCapability(CapabilityType.ACCEPT_INSECURE_CERTS, true);
116
capabilities.setCapability(CapabilityType.PAGE_LOAD_STRATEGY, "eager");
117
capabilities.setCapability(CapabilityType.ENABLE_DOWNLOADS, true);
118

119
// Timeout configuration
120
Map<String, Object> timeouts = Map.of(
121
    "implicit", 10000,
122
    "pageLoad", 30000,
123
    "script", 30000
124
);
125
capabilities.setCapability(CapabilityType.TIMEOUTS, timeouts);
126
```
127

128
### Browser Constants
129

130
Browser identification constants and utilities for cross-browser compatibility.
131

132
```java { .api }
133
/**
134
 * Browser identification constants and utilities
135
 */
136
public interface Browser {
137
    
138
    // Browser constants
139
    Browser CHROME = create("chrome");
140
    Browser EDGE = create("msedge");  
141
    Browser HTMLUNIT = create("htmlunit");
142
    Browser IE = create("internet explorer");
143
    Browser FIREFOX = create("firefox");
144
    Browser OPERA = create("opera");
145
    Browser SAFARI = create("safari");
146
    Browser SAFARI_TECH_PREVIEW = create("Safari Technology Preview");
147
    
148
    // Browser identification methods
149
    String browserName();
150
    boolean is(String browserName);
151
    boolean is(Capabilities caps);
152
    String toJson();
153
    
154
    // Factory method
155
    static Browser create(String browserName);
156
}
157
```
158

159
**Usage Examples:**
160

161
```java
162
import org.openqa.selenium.remote.Browser;
163
import org.openqa.selenium.Capabilities;
164

165
// Browser identification
166
String chromeName = Browser.CHROME.browserName(); // "chrome"
167
boolean isChrome = Browser.CHROME.is("chrome");   // true
168
boolean isFirefox = Browser.FIREFOX.is("chrome"); // false
169

170
// Check capabilities
171
Capabilities caps = new DesiredCapabilities("firefox", null, Platform.ANY);
172
boolean firefoxCaps = Browser.FIREFOX.is(caps); // true
173

174
// Custom browser
175
Browser customBrowser = Browser.create("my-custom-browser");
176

177
// JSON serialization
178
String chromeJson = Browser.CHROME.toJson(); // "chrome"
179
```
180

181
### Capability Validation and Negotiation
182

183
```java
184
// W3C capability validation example
185
public boolean isValidW3CCapability(String capabilityName) {
186
    // W3C standard capabilities
187
    Set<String> w3cStandard = Set.of(
188
        CapabilityType.BROWSER_NAME,
189
        CapabilityType.BROWSER_VERSION,
190
        CapabilityType.PLATFORM_NAME,
191
        CapabilityType.ACCEPT_INSECURE_CERTS,
192
        CapabilityType.PAGE_LOAD_STRATEGY,
193
        CapabilityType.PROXY,
194
        CapabilityType.SET_WINDOW_RECT,
195
        CapabilityType.TIMEOUTS,
196
        CapabilityType.STRICT_FILE_INTERACTABILITY,
197
        CapabilityType.UNHANDLED_PROMPT_BEHAVIOUR
198
    );
199
    
200
    return w3cStandard.contains(capabilityName) || 
201
           capabilityName.contains(":"); // Vendor-specific capabilities
202
}
203

204
// Capability negotiation example
205
public Capabilities negotiateCapabilities(Capabilities requested, Capabilities supported) {
206
    MutableCapabilities negotiated = new MutableCapabilities();
207
    
208
    // Browser name is required
209
    String requestedBrowser = (String) requested.getCapability(CapabilityType.BROWSER_NAME);
210
    String supportedBrowser = (String) supported.getCapability(CapabilityType.BROWSER_NAME);
211
    
212
    if (Objects.equals(requestedBrowser, supportedBrowser)) {
213
        negotiated.setCapability(CapabilityType.BROWSER_NAME, requestedBrowser);
214
    } else {
215
        throw new SessionNotCreatedException("Browser mismatch");
216
    }
217
    
218
    // Version negotiation - use supported if not specified
219
    String requestedVersion = (String) requested.getCapability(CapabilityType.BROWSER_VERSION);
220
    if (requestedVersion == null || "latest".equals(requestedVersion)) {
221
        negotiated.setCapability(CapabilityType.BROWSER_VERSION, 
222
            supported.getCapability(CapabilityType.BROWSER_VERSION));
223
    } else {
224
        negotiated.setCapability(CapabilityType.BROWSER_VERSION, requestedVersion);
225
    }
226
    
227
    return negotiated;
228
}
229
```
230

231
### Advanced Capability Patterns
232

233
```java
234
// Browser-specific options pattern
235
ChromeOptions chromeOptions = new ChromeOptions();
236
chromeOptions.addArguments("--headless", "--no-sandbox");
237
chromeOptions.setExperimentalOption("useAutomationExtension", false);
238

239
// Merge with desired capabilities
240
DesiredCapabilities capabilities = new DesiredCapabilities();
241
capabilities.setCapability(ChromeOptions.CAPABILITY, chromeOptions);
242

243
// Platform-specific capabilities
244
if (Platform.getCurrent().is(Platform.WINDOWS)) {
245
    capabilities.setPlatform(Platform.WINDOWS);
246
    capabilities.setCapability("ms:edgeOptions", edgeOptions);
247
} else if (Platform.getCurrent().is(Platform.MAC)) {
248
    capabilities.setPlatform(Platform.MAC);
249
    capabilities.setCapability("safari:options", safariOptions);
250
}
251

252
// Grid-specific metadata
253
capabilities.setCapability("se:name", "My Test Session");
254
capabilities.setCapability("se:build", "Build 1.2.3");
255
capabilities.setCapability("se:tags", Arrays.asList("smoke", "regression"));
256

257
// Cloud provider capabilities
258
capabilities.setCapability("sauce:options", sauceOptions);
259
capabilities.setCapability("bstack:options", browserStackOptions);
260
```
261

262
### Proxy Configuration
263

264
```java
265
import org.openqa.selenium.Proxy;
266

267
// HTTP proxy configuration
268
Proxy proxy = new Proxy();
269
proxy.setHttpProxy("proxy.company.com:8080");
270
proxy.setSslProxy("proxy.company.com:8080");
271
proxy.setNoProxy("localhost,127.0.0.1");
272

273
capabilities.setCapability(CapabilityType.PROXY, proxy);
274

275
// PAC (Proxy Auto-Configuration) file
276
Proxy pacProxy = new Proxy();
277
pacProxy.setProxyAutoconfigUrl("http://company.com/proxy.pac");
278
capabilities.setCapability(CapabilityType.PROXY, pacProxy);
279

280
// SOCKS proxy
281
Proxy socksProxy = new Proxy();
282
socksProxy.setSocksProxy("socks.proxy.com:1080");
283
socksProxy.setSocksUsername("username");
284
socksProxy.setSocksPassword("password");
285
capabilities.setCapability(CapabilityType.PROXY, socksProxy);
286
```
287

288
### Timeout Configuration
289

290
```java
291
// Configure various timeout types
292
Map<String, Object> timeouts = new HashMap<>();
293
timeouts.put("implicit", 10000);        // 10 seconds for element finding
294
timeouts.put("pageLoad", 30000);        // 30 seconds for page loading
295
timeouts.put("script", 30000);          // 30 seconds for script execution
296

297
capabilities.setCapability(CapabilityType.TIMEOUTS, timeouts);
298

299
// Alternative using Duration objects
300
Map<String, Duration> durationTimeouts = Map.of(
301
    "implicit", Duration.ofSeconds(10),
302
    "pageLoad", Duration.ofSeconds(30),
303
    "script", Duration.ofSeconds(30)
304
);
305
```
306

307
### Page Load Strategy Configuration
308

309
```java
310
// Configure page load strategy
311
capabilities.setCapability(CapabilityType.PAGE_LOAD_STRATEGY, "normal");   // Wait for all resources
312
capabilities.setCapability(CapabilityType.PAGE_LOAD_STRATEGY, "eager");    // Wait for DOM ready
313
capabilities.setCapability(CapabilityType.PAGE_LOAD_STRATEGY, "none");     // Don't wait
314

315
// Unhandled prompt behavior
316
capabilities.setCapability(CapabilityType.UNHANDLED_PROMPT_BEHAVIOUR, "accept");
317
capabilities.setCapability(CapabilityType.UNHANDLED_PROMPT_BEHAVIOUR, "dismiss");
318
capabilities.setCapability(CapabilityType.UNHANDLED_PROMPT_BEHAVIOUR, "ignore");
319
```
320

321
### Capability Debugging and Inspection
322

323
```java
324
// Debug capability matching
325
public void debugCapabilities(Capabilities requested, Capabilities actual) {
326
    System.out.println("Requested capabilities:");
327
    requested.asMap().forEach((key, value) -> 
328
        System.out.println("  " + key + " = " + value));
329
    
330
    System.out.println("Actual capabilities:");
331
    actual.asMap().forEach((key, value) -> 
332
        System.out.println("  " + key + " = " + value));
333
    
334
    // Find mismatches
335
    requested.asMap().forEach((key, requestedValue) -> {
336
        Object actualValue = actual.getCapability(key);
337
        if (!Objects.equals(requestedValue, actualValue)) {
338
            System.out.println("MISMATCH: " + key + 
339
                " requested=" + requestedValue + 
340
                " actual=" + actualValue);
341
        }
342
    });
343
}
344

345
// Capability serialization for logging
346
public String serializeCapabilities(Capabilities capabilities) {
347
    return capabilities.asMap().entrySet().stream()
348
        .map(entry -> entry.getKey() + "=" + entry.getValue())
349
        .collect(Collectors.joining(", ", "{", "}"));
350
}
351
```