0
# Browser Configuration
1

2
Chrome-specific browser configuration including binary paths, command-line arguments, extensions, experimental options, and capability settings for customizing Chrome browser behavior during automated testing.
3

4
## Capabilities
5

6
### ChromeOptions Class
7

8
Configuration options for Chrome browser instances providing extensive customization for headless operation, extension management, proxy settings, and browser arguments.
9

10
```java { .api }
11
/**
12
 * Class to manage options specific to ChromeDriver.
13
 * Extends MutableCapabilities to provide Chrome-specific configuration.
14
 */
15
public class ChromeOptions extends MutableCapabilities {
16
    
17
    /**
18
     * Key used to store a set of ChromeOptions in a Capabilities object.
19
     */
20
    public static final String CAPABILITY = "goog:chromeOptions";
21
    
22
    /**
23
     * Creates a new ChromeOptions instance with default Chrome capabilities.
24
     */
25
    public ChromeOptions();
26
    
27
    /**
28
     * Merges additional capabilities into these ChromeOptions.
29
     * @param extraCapabilities Additional capabilities to merge
30
     * @return This ChromeOptions instance for method chaining
31
     */
32
    public ChromeOptions merge(Capabilities extraCapabilities);
33
}
34
```
35

36
### Binary Path Configuration
37

38
Configure the Chrome executable location for custom Chrome installations.
39

40
```java { .api }
41
/**
42
 * Sets the path to the Chrome executable from File.
43
 * @param path Path to Chrome executable file
44
 * @return This ChromeOptions instance for method chaining
45
 */
46
public ChromeOptions setBinary(File path);
47

48
/**
49
 * Sets the path to the Chrome executable from String.
50
 * @param path Path to Chrome executable as string
51
 * @return This ChromeOptions instance for method chaining
52
 */
53
public ChromeOptions setBinary(String path);
54
```
55

56
**Usage Example:**
57

58
```java
59
ChromeOptions options = new ChromeOptions();
60
options.setBinary("/usr/bin/google-chrome-stable");
61
// or
62
options.setBinary(new File("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"));
63
```
64

65
### Command Line Arguments
66

67
Add Chrome command-line arguments for browser behavior customization.
68

69
```java { .api }
70
/**
71
 * Adds additional command line arguments (varargs).
72
 * @param arguments The arguments to use when starting Chrome
73
 * @return This ChromeOptions instance for method chaining
74
 */
75
public ChromeOptions addArguments(String... arguments);
76

77
/**
78
 * Adds additional command line arguments from list.
79
 * Each argument may contain an option "--" prefix: "--foo" or "foo".
80
 * Arguments with an associated value should be delimited with an "=": "foo=bar".
81
 * @param arguments The arguments to use when starting Chrome
82
 * @return This ChromeOptions instance for method chaining
83
 */
84
public ChromeOptions addArguments(List<String> arguments);
85
```
86

87
**Usage Examples:**
88

89
```java
90
ChromeOptions options = new ChromeOptions();
91

92
// Common arguments for headless testing
93
options.addArguments(
94
    "--headless",
95
    "--no-sandbox", 
96
    "--disable-dev-shm-usage",
97
    "--disable-gpu",
98
    "--window-size=1920,1080"
99
);
100

101
// Performance and debugging arguments
102
options.addArguments(
103
    "--disable-extensions",
104
    "--disable-plugins",
105
    "--disable-images",
106
    "--disable-javascript",
107
    "--remote-debugging-port=9222"
108
);
109

110
// User data and profile arguments
111
options.addArguments(
112
    "--user-data-dir=/tmp/chrome-test-profile",
113
    "--profile-directory=Default"
114
);
115
```
116

117
### Extension Management
118

119
Install Chrome extensions from files or encoded data.
120

121
```java { .api }
122
/**
123
 * Adds Chrome extensions from files (varargs).
124
 * @param paths Paths to the extensions (.crx files) to install
125
 * @return This ChromeOptions instance for method chaining
126
 */
127
public ChromeOptions addExtensions(File... paths);
128

129
/**
130
 * Adds Chrome extensions from file list.
131
 * Each path should specify a packed Chrome extension (CRX file).
132
 * @param paths Paths to the extensions to install
133
 * @return This ChromeOptions instance for method chaining
134
 */
135
public ChromeOptions addExtensions(List<File> paths);
136

137
/**
138
 * Adds Base64 encoded extensions (varargs).
139
 * @param encoded Base64 encoded data of the extensions to install
140
 * @return This ChromeOptions instance for method chaining
141
 */
142
public ChromeOptions addEncodedExtensions(String... encoded);
143

144
/**
145
 * Adds Base64 encoded extensions from list.
146
 * Each string should specify a Base64 encoded packed Chrome extension (CRX file).
147
 * @param encoded Base64 encoded data of the extensions to install
148
 * @return This ChromeOptions instance for method chaining
149
 */
150
public ChromeOptions addEncodedExtensions(List<String> encoded);
151
```
152

153
**Usage Examples:**
154

155
```java
156
ChromeOptions options = new ChromeOptions();
157

158
// Add extensions from files
159
options.addExtensions(
160
    new File("/path/to/extension1.crx"),
161
    new File("/path/to/extension2.crx")
162
);
163

164
// Add extensions from Base64 encoded strings
165
String encodedExtension = "UEsDBBQAAAAIAA..."; // Base64 encoded CRX
166
options.addEncodedExtensions(encodedExtension);
167

168
// Add multiple extensions from list
169
List<File> extensions = Arrays.asList(
170
    new File("/path/to/adblock.crx"),
171
    new File("/path/to/dev-tools.crx")
172
);
173
options.addExtensions(extensions);
174
```
175

176
### Experimental Options
177

178
Configure experimental Chrome features and advanced settings.
179

180
```java { .api }
181
/**
182
 * Sets an experimental option. Useful for new ChromeDriver options not yet
183
 * exposed through the ChromeOptions API.
184
 * @param name Name of the experimental option
185
 * @param value Value of the experimental option, which must be convertible to JSON
186
 * @return This ChromeOptions instance for method chaining
187
 */
188
public ChromeOptions setExperimentalOption(String name, Object value);
189

190
/**
191
 * Returns the value of an experimental option.
192
 * @param name The option name
193
 * @return The option value, or null if not set
194
 * @deprecated Getters are not needed in browser Options classes
195
 */
196
@Deprecated
197
public Object getExperimentalOption(String name);
198
```
199

200
**Usage Examples:**
201

202
```java
203
ChromeOptions options = new ChromeOptions();
204

205
// Mobile emulation
206
Map<String, Object> mobileEmulation = new HashMap<>();
207
mobileEmulation.put("deviceName", "iPhone X");
208
options.setExperimentalOption("mobileEmulation", mobileEmulation);
209

210
// Performance logging
211
Map<String, Object> perfLoggingPrefs = new HashMap<>();
212
perfLoggingPrefs.put("enableNetwork", true);
213
perfLoggingPrefs.put("enablePage", true);
214
options.setExperimentalOption("perfLoggingPrefs", perfLoggingPrefs);
215

216
// Chrome preferences
217
Map<String, Object> prefs = new HashMap<>();
218
prefs.put("download.default_directory", "/path/to/downloads");
219
prefs.put("profile.default_content_settings.popups", 0);
220
options.setExperimentalOption("prefs", prefs);
221
```
222

223
### Page Load Strategy
224

225
Configure how ChromeDriver waits for page loads to complete.
226

227
```java { .api }
228
/**
229
 * Sets the page load strategy for the browser session.
230
 * @param strategy The page load strategy to use (NORMAL, EAGER, NONE)
231
 * @return This ChromeOptions instance for method chaining
232
 */
233
public ChromeOptions setPageLoadStrategy(PageLoadStrategy strategy);
234
```
235

236
### Alert Handling
237

238
Configure how ChromeDriver handles unexpected alert dialogs.
239

240
```java { .api }
241
/**
242
 * Sets the unhandled prompt behavior for alert dialogs.
243
 * @param behaviour How to handle unexpected alert dialogs (ACCEPT, DISMISS, IGNORE)
244
 * @return This ChromeOptions instance for method chaining
245
 */
246
public ChromeOptions setUnhandledPromptBehaviour(UnexpectedAlertBehaviour behaviour);
247
```
248

249
### Security Settings
250

251
Configure certificate and security-related browser settings.
252

253
```java { .api }
254
/**
255
 * Sets whether to accept insecure certificates.
256
 * @param acceptInsecureCerts True to accept insecure certificates, false otherwise
257
 * @return This ChromeOptions instance for method chaining
258
 */
259
public ChromeOptions setAcceptInsecureCerts(boolean acceptInsecureCerts);
260
```
261

262
### Headless Mode
263

264
Enable or disable headless browser operation for server environments.
265

266
```java { .api }
267
/**
268
 * Enables or disables headless mode. In headless mode, Chrome runs without a GUI.
269
 * @param headless True to enable headless mode, false to disable
270
 * @return This ChromeOptions instance for method chaining
271
 */
272
public ChromeOptions setHeadless(boolean headless);
273
```
274

275
**Usage Example:**
276

277
```java
278
ChromeOptions options = new ChromeOptions();
279
options.setHeadless(true); // Enables headless mode and adds --disable-gpu
280
```
281

282
### Proxy Configuration
283

284
Configure proxy settings for network traffic routing.
285

286
```java { .api }
287
/**
288
 * Sets the proxy configuration for the browser session.
289
 * @param proxy The proxy configuration to use
290
 * @return This ChromeOptions instance for method chaining
291
 */
292
public ChromeOptions setProxy(Proxy proxy);
293
```
294

295
**Usage Example:**
296

297
```java
298
import org.openqa.selenium.Proxy;
299

300
ChromeOptions options = new ChromeOptions();
301
Proxy proxy = new Proxy();
302
proxy.setHttpProxy("proxy.company.com:8080");
303
proxy.setSslProxy("proxy.company.com:8080");
304
options.setProxy(proxy);
305
```
306

307
### Options Serialization
308

309
Convert ChromeOptions to map representation for JSON serialization.
310

311
```java { .api }
312
/**
313
 * Converts the ChromeOptions to a map representation for JSON serialization.
314
 * @return Unmodifiable map containing all option values
315
 */
316
public Map<String, Object> asMap();
317
```
318

319
## Complete Configuration Example
320

321
```java
322
import org.openqa.selenium.chrome.ChromeOptions;
323
import org.openqa.selenium.chrome.ChromeDriver;
324
import org.openqa.selenium.PageLoadStrategy;
325
import org.openqa.selenium.UnexpectedAlertBehaviour;
326
import org.openqa.selenium.Proxy;
327
import java.util.HashMap;
328
import java.util.Map;
329

330
ChromeOptions options = new ChromeOptions();
331

332
// Basic configuration
333
options.setBinary("/usr/bin/google-chrome-stable");
334
options.setHeadless(true);
335
options.setPageLoadStrategy(PageLoadStrategy.EAGER);
336
options.setAcceptInsecureCerts(true);
337
options.setUnhandledPromptBehaviour(UnexpectedAlertBehaviour.DISMISS);
338

339
// Command line arguments
340
options.addArguments(
341
    "--no-sandbox",
342
    "--disable-dev-shm-usage", 
343
    "--disable-gpu",
344
    "--window-size=1920,1080",
345
    "--disable-extensions",
346
    "--remote-debugging-port=9222"
347
);
348

349
// Extensions
350
options.addExtensions(new File("/path/to/extension.crx"));
351

352
// Experimental options
353
Map<String, Object> prefs = new HashMap<>();
354
prefs.put("download.default_directory", "/tmp/downloads");
355
prefs.put("profile.default_content_settings.popups", 0);
356
options.setExperimentalOption("prefs", prefs);
357

358
// Mobile emulation
359
Map<String, Object> mobileEmulation = new HashMap<>();
360
mobileEmulation.put("deviceName", "iPhone X");
361
options.setExperimentalOption("mobileEmulation", mobileEmulation);
362

363
// Create driver with configured options
364
ChromeDriver driver = new ChromeDriver(options);
365
```
366

367
## Types
368

369
```java { .api }
370
// Page load strategies
371
enum PageLoadStrategy {
372
    /**
373
     * Wait for the page to finish loading (default)
374
     */
375
    NORMAL,
376
    
377
    /**
378
     * Wait for initial HTML document to be loaded
379
     */
380
    EAGER,
381
    
382
    /**
383
     * Do not wait for page to load
384
     */
385
    NONE
386
}
387

388
// Alert handling behaviors  
389
enum UnexpectedAlertBehaviour {
390
    /**
391
     * Accept unexpected alert dialogs
392
     */
393
    ACCEPT,
394
    
395
    /**
396
     * Dismiss unexpected alert dialogs  
397
     */
398
    DISMISS,
399
    
400
    /**
401
     * Ignore unexpected alert dialogs
402
     */
403
    IGNORE
404
}
405
```