0
# Browser Configuration
1

2
ChromiumOptions provides comprehensive configuration capabilities for Chromium-based browsers including binary paths, command line arguments, extensions, experimental features, and Android-specific settings.
3

4
## Basic Configuration
5

6
### Set Browser Binary
7

8
Specify the path to the Chrome/Chromium executable.
9

10
```java { .api }
11
public T setBinary(File path);
12
public T setBinary(String path);
13
```
14

15
**Parameters:**
16
- `path` (File|String): Absolute or relative path to the browser executable
17

18
**Returns:** T - ChromiumOptions instance for method chaining
19

20
**Usage Example:**
21
```java
22
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
23

24
// Set binary path using string
25
options.setBinary("/opt/google/chrome/chrome");
26

27
// Or using File object
28
options.setBinary(new File("/usr/bin/chromium-browser"));
29
```
30

31
## Command Line Arguments
32

33
### Add Arguments
34

35
Add command line arguments for browser startup.
36

37
```java { .api }
38
public T addArguments(String... arguments);
39
public T addArguments(List<String> arguments);
40
```
41

42
**Parameters:**
43
- `arguments` (String[]|List<String>): Command line arguments to add
44

45
**Returns:** T - ChromiumOptions instance for method chaining
46

47
**Usage Example:**
48
```java
49
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
50

51
// Add individual arguments
52
options.addArguments("--headless", "--no-sandbox", "--disable-dev-shm-usage");
53

54
// Add arguments from list
55
List<String> args = Arrays.asList("--window-size=1920,1080", "--disable-gpu");
56
options.addArguments(args);
57

58
// Arguments with values (use "=" delimiter)
59
options.addArguments("--user-data-dir=/tmp/chrome-profile");
60
```
61

62
**Common Arguments:**
63
- `--headless`: Run in headless mode
64
- `--no-sandbox`: Disable sandboxing (required in some Docker environments)
65
- `--disable-dev-shm-usage`: Overcome limited resource problems
66
- `--window-size=width,height`: Set initial window size
67
- `--disable-gpu`: Disable GPU acceleration
68
- `--disable-extensions`: Disable all extensions
69
- `--incognito`: Start in incognito mode
70

71
## Extensions
72

73
### Add Extension Files
74

75
Add Chrome extensions from .crx files.
76

77
```java { .api }
78
public T addExtensions(File... paths);
79
public T addExtensions(List<File> paths);
80
```
81

82
**Parameters:**
83
- `paths` (File[]|List<File>): Paths to .crx extension files
84

85
**Returns:** T - ChromiumOptions instance for method chaining
86

87
**Throws:** IllegalArgumentException if any file doesn't exist or isn't a file
88

89
**Usage Example:**
90
```java
91
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
92

93
// Add single extension
94
File extension = new File("/path/to/extension.crx");
95
options.addExtensions(extension);
96

97
// Add multiple extensions
98
options.addExtensions(
99
    new File("/path/to/extension1.crx"),
100
    new File("/path/to/extension2.crx")
101
);
102
```
103

104
### Add Encoded Extensions
105

106
Add Chrome extensions from Base64-encoded strings.
107

108
```java { .api }
109
public T addEncodedExtensions(String... encoded);
110
public T addEncodedExtensions(List<String> encoded);
111
```
112

113
**Parameters:**
114
- `encoded` (String[]|List<String>): Base64-encoded extension data
115

116
**Returns:** T - ChromiumOptions instance for method chaining
117

118
**Usage Example:**
119
```java
120
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
121

122
// Add encoded extension
123
String encodedExtension = "UEsDBBQAAAAIABtUJUDh4JfE..."; // Base64 data
124
options.addEncodedExtensions(encodedExtension);
125
```
126

127
## Advanced Features
128

129
### Enable BiDi Protocol
130

131
Enable WebDriver BiDi protocol support.
132

133
```java { .api }
134
public T enableBiDi();
135
```
136

137
**Returns:** T - ChromiumOptions instance for method chaining
138

139
**Usage Example:**
140
```java
141
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
142
options.enableBiDi();
143
```
144

145
### Set Experimental Options
146

147
Configure experimental Chrome options not yet exposed through the API.
148

149
```java { .api }
150
public T setExperimentalOption(String name, Object value);
151
```
152

153
**Parameters:**
154
- `name` (String): Name of the experimental option
155
- `value` (Object): Value for the experimental option (must be JSON-convertible)
156

157
**Returns:** T - ChromiumOptions instance for method chaining
158

159
**Usage Example:**
160
```java
161
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
162

163
// Enable logging
164
Map<String, Object> logPrefs = new HashMap<>();
165
logPrefs.put("browser", "ALL");
166
logPrefs.put("driver", "ALL");
167
options.setExperimentalOption("logPrefs", logPrefs);
168

169
// Set download directory
170
options.setExperimentalOption("prefs", Map.of(
171
    "download.default_directory", "/path/to/downloads"
172
));
173
```
174

175
## Android Configuration
176

177
### Set Android Package
178

179
Configure the Android package name for mobile testing.
180

181
```java { .api }
182
public T setAndroidPackage(String androidPackage);
183
```
184

185
**Parameters:**
186
- `androidPackage` (String): Android package name
187

188
**Returns:** T - ChromiumOptions instance for method chaining
189

190
### Set Android Activity
191

192
Configure the Android activity to launch.
193

194
```java { .api }
195
public T setAndroidActivity(String activity);
196
```
197

198
**Parameters:**
199
- `activity` (String): Android activity class name
200

201
**Returns:** T - ChromiumOptions instance for method chaining
202

203
### Set Android Device Serial
204

205
Specify the Android device serial number.
206

207
```java { .api }
208
public T setAndroidDeviceSerialNumber(String serial);
209
```
210

211
**Parameters:**
212
- `serial` (String): Device serial number
213

214
**Returns:** T - ChromiumOptions instance for method chaining
215

216
### Use Running Android App
217

218
Configure whether to use an already running Android app.
219

220
```java { .api }
221
public T setUseRunningAndroidApp(boolean useIt);
222
```
223

224
**Parameters:**
225
- `useIt` (boolean): Whether to use running app
226

227
**Returns:** T - ChromiumOptions instance for method chaining
228

229
### Set Android Process
230

231
Set the process name for the Android WebView.
232

233
```java { .api }
234
public T setAndroidProcess(String processName);
235
```
236

237
**Parameters:**
238
- `processName` (String): Process name hosting the WebView
239

240
**Returns:** T - ChromiumOptions instance for method chaining
241

242
**Usage Example:**
243
```java
244
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
245

246
// Configure for Android Chrome
247
options.setAndroidPackage("com.android.chrome")
248
       .setAndroidActivity("com.google.android.apps.chrome.Main")
249
       .setAndroidDeviceSerialNumber("HT7C1A03042")
250
       .setUseRunningAndroidApp(false);
251
```
252

253
## Option Merging
254

255
ChromiumOptions supports merging configurations from other sources:
256

257
### Merge Capabilities
258

259
```java { .api }
260
protected void mergeInPlace(Capabilities capabilities);
261
protected void mergeInOptionsFromCaps(String capabilityName, Capabilities capabilities);
262
```
263

264
These methods handle merging options from existing Capabilities objects, combining arguments, extensions, and other settings intelligently.
265

266
## Types and Constants
267

268
```java { .api }
269
// Constructor for creating ChromiumOptions
270
public ChromiumOptions(String capabilityType, String browserType, String capability);
271

272
// Constants for network conditions
273
public static final String OFFLINE = "offline";
274
public static final String LATENCY = "latency";
275
public static final String DOWNLOAD_THROUGHPUT = "download_throughput";
276
public static final String UPLOAD_THROUGHPUT = "upload_throughput";
277
```
278

279
## Complete Configuration Example
280

281
```java
282
import org.openqa.selenium.chromium.ChromiumOptions;
283
import java.io.File;
284
import java.util.Arrays;
285
import java.util.Map;
286

287
ChromiumOptions<?> options = new ChromiumOptions<>("goog:chromeOptions", "chrome", "chrome");
288

289
// Basic configuration
290
options.setBinary("/opt/google/chrome/chrome")
291
       .addArguments("--headless", "--no-sandbox", "--disable-dev-shm-usage")
292
       .addArguments("--window-size=1920,1080");
293

294
// Extensions
295
options.addExtensions(new File("/path/to/extension.crx"));
296

297
// Experimental options
298
options.setExperimentalOption("excludeSwitches", Arrays.asList("enable-automation"))
299
       .setExperimentalOption("useAutomationExtension", false);
300

301
// Enable advanced protocols
302
options.enableBiDi();
303

304
// Android configuration (if testing mobile Chrome)
305
options.setAndroidPackage("com.android.chrome")
306
       .setAndroidActivity("com.google.android.apps.chrome.Main");
307
```
308

309
## Error Handling
310

311
Common exceptions:
312

313
- **IllegalArgumentException**: When null parameters are provided or files don't exist
314
- **SessionNotCreatedException**: When extension files cannot be read during session creation
315

316
## Best Practices
317

318
1. **Binary Path**: Always specify browser binary path in CI/CD environments
319
2. **Headless Mode**: Use `--headless` for server environments without displays
320
3. **Resource Limits**: Use `--no-sandbox` and `--disable-dev-shm-usage` in containerized environments
321
4. **Extension Security**: Validate extension files before adding them
322
5. **Experimental Options**: Test experimental options thoroughly as they may change between Chrome versions
323
6. **Method Chaining**: Take advantage of fluent interface for clean configuration code