0
# Browser Automation
1

2
Core browser automation functionality for loading pages, managing browser instances, configuring options, and handling basic navigation. This is the foundation for all HtmlUnit operations.
3

4
## Capabilities
5

6
### WebClient Class
7

8
The main entry point for all HtmlUnit browser automation operations.
9

10
```java { .api }
11
/**
12
 * Main browser automation class that simulates a web browser
13
 */
14
public class WebClient implements AutoCloseable {
15
    /** Create WebClient with default Chrome browser */
16
    public WebClient();
17
    
18
    /** Create WebClient with specific browser version */
19
    public WebClient(BrowserVersion browserVersion);
20
    
21
    /** Create WebClient with browser version and proxy settings */
22
    public WebClient(BrowserVersion browserVersion, String proxyHost, int proxyPort);
23
    
24
    /** Load page from URL string */
25
    public <P extends Page> P getPage(String url) throws IOException, FailingHttpStatusCodeException;
26
    
27
    /** Load page from URL object */
28
    public <P extends Page> P getPage(URL url) throws IOException, FailingHttpStatusCodeException;
29
    
30
    /** Load page from custom WebRequest */
31
    public <P extends Page> P getPage(WebRequest request) throws IOException, FailingHttpStatusCodeException;
32
    
33
    /** Load page into specific window */
34
    public <P extends Page> P getPage(WebWindow webWindow, WebRequest webRequest) throws IOException, FailingHttpStatusCodeException;
35
    
36
    /** Load WebResponse into specific window */
37
    public Page loadWebResponseInto(WebResponse webResponse, WebWindow webWindow) throws IOException;
38
    
39
    /** Get current browser configuration options */
40
    public WebClientOptions getOptions();
41
    
42
    /** Get browser version being simulated */
43
    public BrowserVersion getBrowserVersion();
44
    
45
    /** Get current active window */
46
    public WebWindow getCurrentWindow();
47
    
48
    /** Set current active window */
49
    public void setCurrentWindow(WebWindow window);
50
    
51
    /** Open new window with URL */
52
    public WebWindow openWindow(URL url, String windowName) throws IOException;
53
    
54
    /** Open modal dialog window */
55
    public DialogWindow openDialogWindow(URL url, WebWindow opener, Object dialogArguments) throws IOException;
56
    
57
    /** Find window by name */
58
    public WebWindow getWebWindowByName(String name);
59
    
60
    /** Add default request header for all requests */
61
    public void addRequestHeader(String name, String value);
62
    
63
    /** Remove default request header */
64
    public void removeRequestHeader(String name);
65
    
66
    /** Get HTTP connection handler */
67
    public WebConnection getWebConnection();
68
    
69
    /** Set custom HTTP connection handler */
70
    public void setWebConnection(WebConnection webConnection);
71
    
72
    /** Get cookie manager */
73
    public CookieManager getCookieManager();
74
    
75
    /** Set custom cookie manager */
76
    public void setCookieManager(CookieManager cookieManager);
77
    
78
    /** Set credentials provider for authentication */
79
    public void setCredentialsProvider(CredentialsProvider credentialsProvider);
80
    
81
    /** Set JavaScript alert handler */
82
    public void setAlertHandler(AlertHandler alertHandler);
83
    
84
    /** Get JavaScript alert handler */
85
    public AlertHandler getAlertHandler();
86
    
87
    /** Set JavaScript confirm handler */
88
    public void setConfirmHandler(ConfirmHandler confirmHandler);
89
    
90
    /** Get JavaScript confirm handler */
91
    public ConfirmHandler getConfirmHandler();
92
    
93
    /** Set JavaScript prompt handler */
94
    public void setPromptHandler(PromptHandler promptHandler);
95
    
96
    /** Get JavaScript prompt handler */
97
    public PromptHandler getPromptHandler();
98
    
99
    /** Set JavaScript error listener */
100
    public void setJavaScriptErrorListener(JavaScriptErrorListener javaScriptErrorListener);
101
    
102
    /** Get JavaScript error listener */
103
    public JavaScriptErrorListener getJavaScriptErrorListener();
104
    
105
    /** Close and cleanup all resources */
106
    public void close();
107
    
108
    /** Wait for background JavaScript jobs to complete */
109
    public int waitForBackgroundJavaScript(long timeoutMillis);
110
    
111
    /** Wait for background JavaScript jobs with timeout */
112
    public int waitForBackgroundJavaScriptStartingBefore(long delayMillis);
113
}
114
```
115

116
**Usage Examples:**
117

118
```java
119
import com.gargoylesoftware.htmlunit.WebClient;
120
import com.gargoylesoftware.htmlunit.BrowserVersion;
121
import com.gargoylesoftware.htmlunit.html.HtmlPage;
122

123
// Basic browser automation
124
try (WebClient webClient = new WebClient()) {
125
    HtmlPage page = webClient.getPage("https://example.com");
126
    String title = page.getTitleText();
127
    System.out.println("Page title: " + title);
128
}
129

130
// Browser with specific version
131
try (WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
132
    webClient.getOptions().setJavaScriptEnabled(true);
133
    webClient.getOptions().setCssEnabled(false);
134
    
135
    HtmlPage page = webClient.getPage("https://example.com");
136
    // Work with page...
137
}
138

139
// Browser with proxy
140
try (WebClient webClient = new WebClient(BrowserVersion.CHROME, "proxy.example.com", 8080)) {
141
    webClient.addRequestHeader("User-Agent", "Custom Bot 1.0");
142
    HtmlPage page = webClient.getPage("https://example.com");
143
    // Work with page...
144
}
145
```
146

147
### WebClientOptions Class
148

149
Configuration options for customizing WebClient behavior.
150

151
```java { .api }
152
/**
153
 * Configuration options for WebClient behavior
154
 */
155
public class WebClientOptions {
156
    /** Check if JavaScript execution is enabled */
157
    public boolean isJavaScriptEnabled();
158
    
159
    /** Enable or disable JavaScript execution */
160
    public void setJavaScriptEnabled(boolean enabled);
161
    
162
    /** Check if CSS processing is enabled */
163
    public boolean isCssEnabled();
164
    
165
    /** Enable or disable CSS processing */
166
    public void setCssEnabled(boolean enabled);
167
    
168
    /** Check if exceptions are thrown on JavaScript errors */
169
    public boolean isThrowExceptionOnScriptError();
170
    
171
    /** Set whether to throw exceptions on JavaScript errors */
172
    public void setThrowExceptionOnScriptError(boolean throwExceptionOnScriptError);
173
    
174
    /** Check if failing HTTP status codes throw exceptions */
175
    public boolean isThrowExceptionOnFailingStatusCode();
176
    
177
    /** Set whether to throw exceptions on failing HTTP status codes */
178
    public void setThrowExceptionOnFailingStatusCode(boolean throwExceptionOnFailingStatusCode);
179
    
180
    /** Check if images are downloaded */
181
    public boolean isDownloadImages();
182
    
183
    /** Set whether to download images */
184
    public void setDownloadImages(boolean downloadImages);
185
    
186
    /** Get connection timeout in milliseconds */
187
    public int getTimeout();
188
    
189
    /** Set connection timeout in milliseconds */
190
    public void setTimeout(int timeout);
191
    
192
    /** Check if HTTP redirects are followed */
193
    public boolean isRedirectEnabled();
194
    
195
    /** Set whether to follow HTTP redirects */
196
    public void setRedirectEnabled(boolean enabled);
197
    
198
    /** Check if insecure SSL connections are allowed */
199
    public boolean isUseInsecureSSL();
200
    
201
    /** Set whether to allow insecure SSL connections */
202
    public void setUseInsecureSSL(boolean useInsecureSSL);
203
    
204
    /** Get proxy configuration */
205
    public ProxyConfig getProxyConfig();
206
    
207
    /** Set proxy configuration */
208
    public void setProxyConfig(ProxyConfig proxyConfig);
209
    
210
    /** Check if applets are enabled */
211
    public boolean isAppletEnabled();
212
    
213
    /** Set whether applets are enabled */
214
    public void setAppletEnabled(boolean enabled);
215
    
216
    /** Check if ActiveX objects are enabled */
217
    public boolean isActiveXNative();
218
    
219
    /** Set whether ActiveX objects are enabled */
220
    public void setActiveXNative(boolean enabled);
221
    
222
    /** Get maximum redirects allowed */
223
    public int getMaxInMemory();
224
    
225
    /** Set maximum redirects allowed */
226
    public void setMaxInMemory(int maxInMemory);
227
    
228
    /** Get screen dimensions */
229
    public Dimension getScreenSize();
230
    
231
    /** Set screen dimensions */
232
    public void setScreenSize(Dimension screenSize);
233
}
234
```
235

236
### BrowserVersion Class
237

238
Browser version configuration and feature detection.
239

240
```java { .api }
241
/**
242
 * Represents a specific browser version with its capabilities
243
 */
244
public class BrowserVersion {
245
    /** Google Chrome (latest version) */
246
    public static final BrowserVersion CHROME;
247
    
248
    /** Mozilla Firefox (latest version) */
249
    public static final BrowserVersion FIREFOX;
250
    
251
    /** Mozilla Firefox ESR (Extended Support Release) */
252
    public static final BrowserVersion FIREFOX_ESR;
253
    
254
    /** Microsoft Edge */
255
    public static final BrowserVersion EDGE;
256
    
257
    /** Internet Explorer 11 */
258
    public static final BrowserVersion INTERNET_EXPLORER;
259
    
260
    /** Best supported browser (currently Chrome) */
261
    public static final BrowserVersion BEST_SUPPORTED;
262
    
263
    /** Get browser application name */
264
    public String getApplicationName();
265
    
266
    /** Get browser version string */
267
    public String getApplicationVersion();
268
    
269
    /** Get User-Agent string */
270
    public String getUserAgent();
271
    
272
    /** Check if browser supports specific feature */
273
    public boolean hasFeature(BrowserFeature feature);
274
    
275
    /** Get browser major version number */
276
    public float getBrowserVersionNumeric();
277
    
278
    /** Check if this is Internet Explorer */
279
    public boolean isIE();
280
    
281
    /** Check if this is Firefox */
282
    public boolean isFirefox();
283
    
284
    /** Check if this is Chrome */
285
    public boolean isChrome();
286
    
287
    /** Check if this is Edge */
288
    public boolean isEdge();
289
}
290
```
291

292
**Usage Examples:**
293

294
```java
295
import com.gargoylesoftware.htmlunit.BrowserVersion;
296
import com.gargoylesoftware.htmlunit.WebClient;
297

298
// Configure for specific browser
299
try (WebClient webClient = new WebClient(BrowserVersion.FIREFOX)) {
300
    // Configure options
301
    WebClientOptions options = webClient.getOptions();
302
    options.setJavaScriptEnabled(true);
303
    options.setCssEnabled(false);
304
    options.setTimeout(30000); // 30 seconds
305
    options.setThrowExceptionOnScriptError(false);
306
    options.setThrowExceptionOnFailingStatusCode(false);
307
    
308
    // Load page
309
    HtmlPage page = webClient.getPage("https://example.com");
310
    
311
    // Browser-specific behavior
312
    BrowserVersion browser = webClient.getBrowserVersion();
313
    if (browser.isFirefox()) {
314
        System.out.println("Running in Firefox mode");
315
        System.out.println("User Agent: " + browser.getUserAgent());
316
    }
317
}
318
```
319

320
### Page Interface
321

322
Base interface for all page types returned by WebClient.
323

324
```java { .api }
325
/**
326
 * Base interface for all page types
327
 */
328
public interface Page {
329
    /** Get the HTTP response that created this page */
330
    public WebResponse getWebResponse();
331
    
332
    /** Get the window containing this page */
333
    public WebWindow getEnclosingWindow();
334
    
335
    /** Get the URL of this page */
336
    public URL getUrl();
337
    
338
    /** Initialize page after loading */
339
    public void initialize();
340
    
341
    /** Clean up page resources */
342
    public void cleanUp();
343
    
344
    /** Check if page supports JavaScript */
345
    public boolean isHtmlPage();
346
}
347
```
348

349
### Common Page Types
350

351
```java { .api }
352
/**
353
 * HTML page with full DOM support
354
 */
355
public class HtmlPage extends SgmlPage {
356
    // See HTML DOM Manipulation documentation for full API
357
}
358

359
/**
360
 * Plain text page
361
 */
362
public class TextPage extends AbstractPage {
363
    /** Get text content of the page */
364
    public String getContent();
365
}
366

367
/**
368
 * Page with unexpected content type
369
 */
370
public class UnexpectedPage extends AbstractPage {
371
    /** Get input stream for page content */
372
    public InputStream getInputStream() throws IOException;
373
    
374
    /** Get page content as bytes */
375
    public byte[] getBytes();
376
}
377

378
/**
379
 * XML page with DOM support
380
 */
381
public class XmlPage extends SgmlPage {
382
    /** Get XML content as string */
383
    public String asXml();
384
    
385
    /** Get XML document */
386
    public Document getXmlDocument();
387
}
388
```
389

390
### Browser Constants
391

392
```java { .api }
393
/**
394
 * Common target window names
395
 */
396
public static final String TARGET_BLANK = "_blank";
397
public static final String TARGET_SELF = "_self";
398
public static final String TARGET_PARENT = "_parent";
399
public static final String TARGET_TOP = "_top";
400

401
/**
402
 * HTTP status codes
403
 */
404
public static final int OK = 200;
405
public static final int NOT_FOUND = 404;
406
public static final int FORBIDDEN = 403;
407
public static final int INTERNAL_SERVER_ERROR = 500;
408
```