0
# Browser Configuration
1

2
Comprehensive configuration system for Firefox browser settings, preferences, command-line arguments, and capabilities. The FirefoxOptions class provides a fluent API for configuring all aspects of Firefox behavior.
3

4
## Capabilities  
5

6
### FirefoxOptions Class
7

8
Manages Firefox-specific settings and capabilities in a way that GeckoDriver can understand.
9

10
```java { .api }
11
/**
12
 * Manage Firefox specific settings in a way that geckodriver can understand.
13
 * Extends AbstractDriverOptions to provide Firefox-specific configuration.
14
 */
15
public class FirefoxOptions extends AbstractDriverOptions<FirefoxOptions> {
16
    
17
    /**
18
     * Capability key for Firefox options in WebDriver capabilities map.
19
     */
20
    public static final String FIREFOX_OPTIONS = "moz:firefoxOptions";
21
    
22
    /**
23
     * Creates a new FirefoxOptions instance with default settings.
24
     * Sets browser name to "firefox" and enables BiDi protocol.
25
     */
26
    public FirefoxOptions();
27
    
28
    /**
29
     * Creates FirefoxOptions from existing capabilities.
30
     * @param source Capabilities to copy settings from
31
     */
32
    public FirefoxOptions(Capabilities source);
33
}
34
```
35

36
**Usage Examples:**
37

38
```java
39
import org.openqa.selenium.firefox.FirefoxOptions;
40

41
// Basic options creation  
42
FirefoxOptions options = new FirefoxOptions();
43

44
// Options from existing capabilities
45
Capabilities existingCaps = new ImmutableCapabilities("browserName", "firefox");
46
FirefoxOptions options = new FirefoxOptions(existingCaps);
47
```
48

49
### Environment Configuration
50

51
Configures options from system properties and environment variables.
52

53
```java { .api }
54
/**
55
 * Configures Firefox options from system properties and environment variables.
56
 * @return This FirefoxOptions instance for method chaining
57
 */
58
public FirefoxOptions configureFromEnv();
59
```
60

61
**Usage Examples:**
62

63
```java
64
// Configure from environment automatically
65
FirefoxOptions options = new FirefoxOptions().configureFromEnv();
66

67
// Set system properties before configuration
68
System.setProperty("webdriver.firefox.bin", "/opt/firefox/firefox");
69
System.setProperty("webdriver.firefox.profile", "/tmp/firefox-profile");
70
FirefoxOptions options = new FirefoxOptions().configureFromEnv();
71
```
72

73
### Binary Configuration  
74

75
Specifies the Firefox executable to use, supporting different Firefox installations.
76

77
```java { .api }
78
/**
79
 * Gets the Firefox binary configuration.
80
 * @return FirefoxBinary instance
81
 * @deprecated Use getBinaryOrNull() or system properties instead
82
 */
83
@Deprecated
84
public FirefoxBinary getBinary();
85

86
/**
87
 * Gets the Firefox binary as Optional.
88
 * @return Optional containing FirefoxBinary, empty if not set
89
 * @deprecated Use system properties instead
90
 */
91
@Deprecated
92
public Optional<FirefoxBinary> getBinaryOrNull();
93

94
/**
95
 * Sets the Firefox binary to use.
96
 * @param binary FirefoxBinary instance
97
 * @return This FirefoxOptions instance for method chaining
98
 * @deprecated Use setBinary(Path) instead
99
 */
100
@Deprecated
101
public FirefoxOptions setBinary(FirefoxBinary binary);
102

103
/**
104
 * Sets the Firefox executable path.
105
 * @param path Path to Firefox executable
106
 * @return This FirefoxOptions instance for method chaining
107
 */
108
public FirefoxOptions setBinary(Path path);
109

110
/**
111
 * Sets the Firefox executable path as string.
112
 * @param path String path to Firefox executable  
113
 * @return This FirefoxOptions instance for method chaining
114
 */
115
public FirefoxOptions setBinary(String path);
116
```
117

118
**Usage Examples:**
119

120
```java
121
import java.nio.file.Paths;
122

123
FirefoxOptions options = new FirefoxOptions()
124
    .setBinary("/usr/bin/firefox")
125
    .setBinary(Paths.get("/Applications/Firefox.app/Contents/MacOS/firefox"));
126
```
127

128
### Profile Configuration
129

130
Sets the Firefox user profile for customization and data persistence.
131

132
```java { .api }
133
/**
134
 * Gets the current Firefox profile.
135
 * @return FirefoxProfile instance, null if not set
136
 */
137
public FirefoxProfile getProfile();
138

139
/**
140
 * Sets the Firefox profile to use.
141
 * @param profile FirefoxProfile instance with custom settings
142
 * @return This FirefoxOptions instance for method chaining
143
 */
144
public FirefoxOptions setProfile(FirefoxProfile profile);
145
```
146

147
### Command Line Arguments
148

149
Adds command-line arguments passed to the Firefox process.
150

151
```java { .api }
152
/**
153
 * Adds command-line arguments to Firefox process.
154
 * @param arguments Variable number of argument strings
155
 * @return This FirefoxOptions instance for method chaining
156
 */
157
public FirefoxOptions addArguments(String... arguments);
158

159
/**
160
 * Adds command-line arguments from a list.
161
 * @param arguments List of argument strings
162
 * @return This FirefoxOptions instance for method chaining  
163
 */
164
public FirefoxOptions addArguments(List<String> arguments);
165
```
166

167
**Usage Examples:**
168

169
```java
170
FirefoxOptions options = new FirefoxOptions()
171
    .addArguments("--headless")
172
    .addArguments("--width=1920", "--height=1080")
173
    .addArguments(Arrays.asList("--disable-extensions", "--no-sandbox"));
174
```
175

176
### Firefox Preferences
177

178
Sets Firefox about:config preferences for detailed browser behavior control.
179

180
```java { .api }
181
/**
182
 * Sets a Firefox preference value.
183
 * @param key Preference name (about:config key)
184
 * @param value Preference value (String, Integer, Boolean)
185
 * @return This FirefoxOptions instance for method chaining
186
 */
187
public FirefoxOptions addPreference(String key, Object value);
188
```
189

190
**Usage Examples:**
191

192
```java
193
FirefoxOptions options = new FirefoxOptions()
194
    .addPreference("browser.startup.page", 1)
195
    .addPreference("browser.startup.homepage", "https://example.com")  
196
    .addPreference("dom.webnotifications.enabled", false)
197
    .addPreference("browser.download.folderList", 2)
198
    .addPreference("browser.download.dir", "/path/to/downloads");
199
```
200

201
### Logging Configuration
202

203
Configures GeckoDriver logging level for debugging and troubleshooting.
204

205
```java { .api }
206
/**
207
 * Sets the GeckoDriver log level.
208
 * @param logLevel Log level from FirefoxDriverLogLevel enum
209
 * @return This FirefoxOptions instance for method chaining
210
 */
211
public FirefoxOptions setLogLevel(FirefoxDriverLogLevel logLevel);
212
```
213

214
### Android Configuration
215

216
Configures Firefox for Android automation when using mobile testing.
217

218
```java { .api }
219
/**
220
 * Sets the Android package name for Firefox Android automation.
221
 * @param androidPackage Package name (e.g., "org.mozilla.firefox")
222
 * @return This FirefoxOptions instance for method chaining
223
 */
224
public FirefoxOptions setAndroidPackage(String androidPackage);
225

226
/**
227
 * Sets the Android activity for Firefox Android automation.
228
 * @param activity Activity name to start
229
 * @return This FirefoxOptions instance for method chaining
230
 */
231
public FirefoxOptions setAndroidActivity(String activity);
232

233
/**
234
 * Sets the Android device serial number for targeting specific devices.
235
 * @param serial Device serial number
236
 * @return This FirefoxOptions instance for method chaining
237
 */
238
public FirefoxOptions setAndroidDeviceSerialNumber(String serial);
239

240
/**
241
 * Sets Android intent arguments as array.
242
 * @param args Intent argument array
243
 * @return This FirefoxOptions instance for method chaining
244
 */
245
public FirefoxOptions setAndroidIntentArguments(String[] args);
246

247
/**
248
 * Sets Android intent arguments as list.
249
 * @param args Intent argument list
250
 * @return This FirefoxOptions instance for method chaining
251
 */
252
public FirefoxOptions setAndroidIntentArguments(List<String> args);
253
```
254

255
**Usage Examples:**
256

257
```java
258
FirefoxOptions options = new FirefoxOptions()
259
    .setAndroidPackage("org.mozilla.firefox")
260
    .setAndroidActivity("org.mozilla.gecko.BrowserApp")
261
    .setAndroidDeviceSerialNumber("emulator-5554")
262
    .setAndroidIntentArguments(new String[]{"--verbose", "--debug"});
263
```
264

265
### BiDi Protocol Configuration
266

267
Enables modern WebDriver BiDi protocol support for advanced automation features.
268

269
```java { .api }
270
/**
271
 * Enables WebDriver BiDi protocol support.
272
 * Required for BiDi functionality access.
273
 * @return This FirefoxOptions instance for method chaining
274
 */
275
public FirefoxOptions enableBiDi();
276
```
277

278
### Capability Merging
279

280
Merges additional capabilities with Firefox-specific options.
281

282
```java { .api }
283
/**
284
 * Merges the provided capabilities with existing options.
285
 * @param capabilities Additional capabilities to merge
286
 * @return New FirefoxOptions instance with merged capabilities
287
 */
288
public FirefoxOptions merge(Capabilities capabilities);
289
```
290

291
**Complete Configuration Example:**
292

293
```java
294
import org.openqa.selenium.firefox.FirefoxOptions;
295
import org.openqa.selenium.firefox.FirefoxProfile;
296
import org.openqa.selenium.firefox.FirefoxDriverLogLevel;
297
import java.nio.file.Paths;
298

299
// Create comprehensive Firefox configuration
300
FirefoxProfile profile = new FirefoxProfile();
301
profile.setPreference("browser.cache.disk.enable", false);
302
profile.setPreference("browser.cache.memory.enable", false);
303

304
FirefoxOptions options = new FirefoxOptions()
305
    // Binary configuration
306
    .setBinary("/opt/firefox/firefox")
307
    
308
    // Profile setup
309
    .setProfile(profile)
310
    
311
    // Command line arguments
312
    .addArguments("--headless")
313
    .addArguments("--width=1920", "--height=1080")
314
    
315
    // Firefox preferences
316
    .addPreference("browser.startup.page", 0)
317
    .addPreference("browser.startup.homepage", "about:blank")
318
    .addPreference("dom.webnotifications.enabled", false)
319
    .addPreference("media.navigator.permission.disabled", true)
320
    
321
    // Logging  
322
    .setLogLevel(FirefoxDriverLogLevel.INFO)
323
    
324
    // BiDi support
325
    .enableBiDi()
326
    
327
    // Standard WebDriver capabilities
328
    .setAcceptInsecureCerts(true)
329
    .setPageLoadStrategy(PageLoadStrategy.NORMAL);
330

331
// Use with driver
332
WebDriver driver = new FirefoxDriver(options);
333
```