0
# Configuration Options
1

2
Comprehensive configuration system for IE-specific browser settings and behaviors. The InternetExplorerOptions class provides a fluent API for configuring Internet Explorer WebDriver capabilities.
3

4
## Capabilities
5

6
### InternetExplorerOptions Class
7

8
Main configuration class extending AbstractDriverOptions with IE-specific functionality.
9

10
```java { .api }
11
/**
12
 * Configuration options for Internet Explorer WebDriver.
13
 * Provides fluent API for setting IE-specific capabilities.
14
 */
15
public class InternetExplorerOptions extends AbstractDriverOptions<InternetExplorerOptions> {
16
    
17
    public static final String IE_OPTIONS = "se:ieOptions";
18
    
19
    /**
20
     * Creates default InternetExplorerOptions with browser name set to IE.
21
     */
22
    public InternetExplorerOptions();
23
    
24
    /**
25
     * Creates InternetExplorerOptions from existing capabilities.
26
     * @param source Existing capabilities to copy from
27
     */
28
    public InternetExplorerOptions(Capabilities source);
29
    
30
    /**
31
     * Merges this options with additional capabilities.
32
     * @param extraCapabilities Additional capabilities to merge
33
     * @return New InternetExplorerOptions instance with merged capabilities
34
     */
35
    @Override
36
    public InternetExplorerOptions merge(Capabilities extraCapabilities);
37
}
38
```
39

40
### Browser Behavior Options
41

42
Methods for configuring IE browser behavior and interaction patterns.
43

44
```java { .api }
45
/**
46
 * Ignores the browser zoom level during automation.
47
 * Prevents zoom-related element location issues.
48
 * @return Self reference for method chaining
49
 */
50
public InternetExplorerOptions ignoreZoomSettings();
51

52
/**
53
 * Requires window focus before performing operations.
54
 * Ensures reliable element interaction in multi-window environments.
55
 * @return Self reference for method chaining
56
 */
57
public InternetExplorerOptions requireWindowFocus();
58

59
/**
60
 * Enables persistent sending of WM_MOUSEMOVE messages during mouse hover.
61
 * Improves hover behavior reliability.
62
 * @return Self reference for method chaining
63
 */
64
public InternetExplorerOptions enablePersistentHovering();
65

66
/**
67
 * Sets the initial URL to load when IE launches.
68
 * @param url Initial browser URL (cannot be null)
69
 * @return Self reference for method chaining
70
 */
71
public InternetExplorerOptions withInitialBrowserUrl(String url);
72

73
/**
74
 * Configures how elements are scrolled into view.
75
 * @param behavior Scroll behavior (TOP or BOTTOM)
76
 * @return Self reference for method chaining
77
 */
78
public InternetExplorerOptions elementScrollTo(ElementScrollBehavior behavior);
79
```
80

81
### Timeout Configuration
82

83
Methods for configuring various timeout values.
84

85
```java { .api }
86
/**
87
 * Sets timeout for attaching to new browser windows.
88
 * @param duration Timeout duration
89
 * @param unit Time unit for duration
90
 * @return Self reference for method chaining
91
 */
92
public InternetExplorerOptions withAttachTimeout(long duration, TimeUnit unit);
93

94
/**
95
 * Sets timeout for attaching to new browser windows.
96
 * @param duration Timeout as Duration object
97
 * @return Self reference for method chaining
98
 */
99
public InternetExplorerOptions withAttachTimeout(Duration duration);
100

101
/**
102
 * Sets timeout for file upload dialog operations.
103
 * @param duration Timeout duration
104
 * @param unit Time unit for duration
105
 * @return Self reference for method chaining
106
 */
107
public InternetExplorerOptions waitForUploadDialogUpTo(long duration, TimeUnit unit);
108

109
/**
110
 * Sets timeout for file upload dialog operations.
111
 * @param duration Timeout as Duration object
112
 * @return Self reference for method chaining
113
 */
114
public InternetExplorerOptions waitForUploadDialogUpTo(Duration duration);
115
```
116

117
### Process and API Configuration
118

119
Methods for configuring IE process creation and Windows API usage.
120

121
```java { .api }
122
/**
123
 * Forces use of Windows CreateProcess API when launching IE.
124
 * Alternative to default ShellExecute method.
125
 * @return Self reference for method chaining
126
 */
127
public InternetExplorerOptions useCreateProcessApiToLaunchIe();
128

129
/**
130
 * Uses Windows ShellWindows API when attaching to IE instances.
131
 * Alternative attachment mechanism.
132
 * @return Self reference for method chaining
133
 */
134
public InternetExplorerOptions useShellWindowsApiToAttachToIe();
135

136
/**
137
 * Adds command line switches for IE process when using CreateProcess API.
138
 * @param switches Variable number of command line switches
139
 * @return Self reference for method chaining
140
 */
141
public InternetExplorerOptions addCommandSwitches(String... switches);
142

143
/**
144
 * Uses per-process proxy settings instead of system-wide proxy.
145
 * Only valid with DIRECT, MANUAL, or SYSTEM proxy types.
146
 * @return Self reference for method chaining
147
 */
148
public InternetExplorerOptions usePerProcessProxy();
149
```
150

151
### Session and Cache Management
152

153
Methods for managing IE sessions and browser cache.
154

155
```java { .api }
156
/**
157
 * Clears Internet Explorer cache before launching browser.
158
 * WARNING: Clears system cache for ALL IE instances, including existing ones.
159
 * @return Self reference for method chaining
160
 */
161
public InternetExplorerOptions destructivelyEnsureCleanSession();
162
```
163

164
### Security Configuration
165

166
Methods for handling IE security domains and protected mode settings.
167

168
```java { .api }
169
/**
170
 * Ignores browser protected mode settings during startup.
171
 * WARNING: Makes tests unstable and hard to debug. Use with caution.
172
 * @return Self reference for method chaining
173
 */
174
public InternetExplorerOptions introduceFlakinessByIgnoringSecurityDomains();
175
```
176

177
### Screenshot and Dialog Options
178

179
Methods for configuring screenshot behavior and dialog handling.
180

181
```java { .api }
182
/**
183
 * Enables full page screenshot capture instead of viewport-only.
184
 * @return Self reference for method chaining
185
 */
186
public InternetExplorerOptions takeFullPageScreenshot();
187

188
/**
189
 * Uses legacy file upload dialog handling mechanism.
190
 * For compatibility with older IE versions or specific configurations.
191
 * @return Self reference for method chaining
192
 */
193
public InternetExplorerOptions useLegacyUploadDialog();
194
```
195

196
### Edge Integration Options
197

198
Methods for integrating with Microsoft Edge in IE mode.
199

200
```java { .api }
201
/**
202
 * Configures IE driver to attach to Edge browser in IE mode.
203
 * @return Self reference for method chaining
204
 */
205
public InternetExplorerOptions attachToEdgeChrome();
206

207
/**
208
 * Sets path to Edge executable for IE mode operations.
209
 * @param path Full path to Edge executable
210
 * @return Self reference for method chaining
211
 */
212
public InternetExplorerOptions withEdgeExecutablePath(String path);
213

214
/**
215
 * Ignores process matching when attaching to browser instances.
216
 * @return Self reference for method chaining
217
 */
218
public InternetExplorerOptions ignoreProcessMatch();
219
```
220

221
## Usage Examples
222

223
### Basic Configuration
224

225
```java
226
InternetExplorerOptions options = new InternetExplorerOptions()
227
    .ignoreZoomSettings()
228
    .requireWindowFocus()
229
    .enablePersistentHovering();
230

231
WebDriver driver = new InternetExplorerDriver(options);
232
```
233

234
### Timeout Configuration
235

236
```java
237
InternetExplorerOptions options = new InternetExplorerOptions()
238
    .withAttachTimeout(30, TimeUnit.SECONDS)
239
    .waitForUploadDialogUpTo(Duration.ofMinutes(2));
240
```
241

242
### Advanced Process Configuration
243

244
```java
245
InternetExplorerOptions options = new InternetExplorerOptions()
246
    .useCreateProcessApiToLaunchIe()
247
    .addCommandSwitches("-private", "-noframemerging")
248
    .usePerProcessProxy()
249
    .destructivelyEnsureCleanSession();
250
```
251

252
### Edge Integration
253

254
```java
255
InternetExplorerOptions options = new InternetExplorerOptions()
256
    .attachToEdgeChrome()
257
    .withEdgeExecutablePath("C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe")
258
    .ignoreProcessMatch();
259
```
260

261
### Security and Compatibility
262

263
```java
264
InternetExplorerOptions options = new InternetExplorerOptions()
265
    .withInitialBrowserUrl("about:blank")
266
    .takeFullPageScreenshot()
267
    .useLegacyUploadDialog()
268
    // Use with extreme caution:
269
    .introduceFlakinessByIgnoringSecurityDomains();
270
```
271

272
## Configuration Best Practices
273

274
1. **Zoom Settings**: Always use `ignoreZoomSettings()` for consistent element location
275
2. **Window Focus**: Use `requireWindowFocus()` in multi-window test environments
276
3. **Timeouts**: Set appropriate timeouts based on your application's response times
277
4. **Security Domains**: Avoid `introduceFlakinessByIgnoringSecurityDomains()` unless absolutely necessary
278
5. **Clean Sessions**: Use `destructivelyEnsureCleanSession()` carefully as it affects all IE instances
279
6. **Command Switches**: Test command line switches thoroughly as they can affect browser behavior
280
7. **Edge Integration**: Verify Edge installation and paths when using Edge IE mode features
281

282
## Capability Constants
283

284
All IE-specific capability constants used internally by InternetExplorerOptions:
285

286
```java { .api }
287
/**
288
 * Capability constants used by InternetExplorerOptions.
289
 * These are automatically set by the fluent API methods.
290
 */
291
public static final String IE_OPTIONS = "se:ieOptions";
292

293
// Private capability constants (used internally)
294
private static final String FULL_PAGE_SCREENSHOT = "ie.enableFullPageScreenshot";
295
private static final String UPLOAD_DIALOG_TIMEOUT = "ie.fileUploadDialogTimeout";
296
private static final String FORCE_WINDOW_SHELL_API = "ie.forceShellWindowsApi";
297
private static final String LEGACY_FILE_UPLOAD_DIALOG_HANDLING = "ie.useLegacyFileUploadDialogHandling";
298
private static final String ATTACH_TO_EDGE_CHROME = "ie.edgechromium";
299
private static final String EDGE_EXECUTABLE_PATH = "ie.edgepath";
300
private static final String IGNORE_PROCESS_MATCH = "ie.ignoreprocessmatch";
301
```
302

303
## Capability Inheritance
304

305
InternetExplorerOptions extends AbstractDriverOptions, providing access to standard WebDriver capabilities:
306

307
- Proxy configuration
308
- Page load strategy
309
- Timeouts (implicit, page load, script)
310
- Unhandled prompt behavior
311
- Browser logging preferences