0
# Web Client Management
1

2
Core browser functionality providing the main entry point for all web automation tasks. WebClient manages browser configuration, page navigation, window management, and resource lifecycle.
3

4
## Capabilities
5

6
### WebClient Creation and Configuration
7

8
Creates and configures the main browser client with customizable browser version and options.
9

10
```java { .api }
11
/**
12
 * Creates a new WebClient with default browser version (Chrome)
13
 */
14
public WebClient();
15

16
/**
17
 * Creates a new WebClient with specified browser version
18
 * @param browserVersion Browser version to emulate
19
 */
20
public WebClient(BrowserVersion browserVersion);
21

22
/**
23
 * Gets the client configuration options
24
 * @return WebClientOptions for configuration
25
 */
26
public WebClientOptions getOptions();
27

28
/**
29
 * Gets the browser version being emulated
30
 * @return BrowserVersion currently configured
31
 */
32
public BrowserVersion getBrowserVersion();
33

34
/**
35
 * Closes the client and releases all resources
36
 */
37
public void close();
38
```
39

40
**Usage Examples:**
41

42
```java
43
// Default Chrome browser
44
WebClient webClient = new WebClient();
45

46
// Specific browser version
47
WebClient firefoxClient = new WebClient(BrowserVersion.FIREFOX);
48

49
// Using try-with-resources for automatic cleanup
50
try (WebClient webClient = new WebClient(BrowserVersion.CHROME)) {
51
    // Client automatically closed
52
}
53
```
54

55
### Page Navigation
56

57
Navigate to web pages using URLs or WebRequest objects, with full support for redirects and various content types.
58

59
```java { .api }
60
/**
61
 * Navigate to a page using a URL string
62
 * @param url URL to navigate to
63
 * @return Page object representing the loaded page
64
 * @throws IOException if navigation fails
65
 */
66
public <P extends Page> P getPage(String url) throws IOException;
67

68
/**
69
 * Navigate to a page using a URL object  
70
 * @param url URL object to navigate to
71
 * @return Page object representing the loaded page
72
 * @throws IOException if navigation fails
73
 */
74
public <P extends Page> P getPage(URL url) throws IOException;
75

76
/**
77
 * Navigate using a custom WebRequest with headers, parameters, and method
78
 * @param request WebRequest with custom configuration
79
 * @return Page object representing the loaded page
80
 * @throws IOException if navigation fails
81
 */
82
public <P extends Page> P getPage(WebRequest request) throws IOException;
83
```
84

85
**Usage Examples:**
86

87
```java
88
// Simple URL navigation
89
HtmlPage page = webClient.getPage("https://example.com");
90

91
// URL object navigation
92
URL url = new URL("https://api.example.com/data");
93
TextPage apiResponse = webClient.getPage(url);
94

95
// Custom request with headers
96
WebRequest request = new WebRequest(new URL("https://api.example.com/data"));
97
request.setAdditionalHeader("Authorization", "Bearer token");
98
request.setHttpMethod(HttpMethod.POST);
99
Page response = webClient.getPage(request);
100
```
101

102
### Client Options Configuration
103

104
Configure browser behavior including JavaScript, CSS, error handling, timeouts, and redirects.
105

106
```java { .api }
107
public class WebClientOptions {
108
    /**
109
     * Enable or disable JavaScript execution
110
     * @param enabled true to enable JavaScript
111
     */
112
    public void setJavaScriptEnabled(boolean enabled);
113
    
114
    /**
115
     * Check if JavaScript is enabled
116
     * @return true if JavaScript is enabled
117
     */
118
    public boolean isJavaScriptEnabled();
119
    
120
    /**
121
     * Enable or disable CSS processing
122
     * @param enabled true to enable CSS
123
     */
124
    public void setCssEnabled(boolean enabled);
125
    
126
    /**
127
     * Check if CSS processing is enabled
128
     * @return true if CSS is enabled
129
     */
130
    public boolean isCssEnabled();
131
    
132
    /**
133
     * Configure whether to throw exceptions on JavaScript errors
134
     * @param throwException true to throw exceptions on script errors
135
     */
136
    public void setThrowExceptionOnScriptError(boolean throwException);
137
    
138
    /**
139
     * Configure whether to throw exceptions on HTTP error status codes
140
     * @param throwException true to throw exceptions on failing status codes
141
     */
142
    public void setThrowExceptionOnFailingStatusCode(boolean throwException);
143
    
144
    /**
145
     * Set connection timeout in milliseconds
146
     * @param timeout timeout in milliseconds
147
     */
148
    public void setTimeout(int timeout);
149
    
150
    /**
151
     * Enable or disable automatic redirect following
152
     * @param enabled true to follow redirects
153
     */
154
    public void setRedirectEnabled(boolean enabled);
155
    
156
    /**
157
     * Enable or disable popup blocker
158
     * @param enabled true to block popups
159
     */
160
    public void setPopupBlockerEnabled(boolean enabled);
161
}
162
```
163

164
**Usage Examples:**
165

166
```java
167
WebClientOptions options = webClient.getOptions();
168

169
// Configure for testing JavaScript-heavy sites
170
options.setJavaScriptEnabled(true);
171
options.setCssEnabled(false); // Faster loading
172
options.setThrowExceptionOnScriptError(false); // Continue on JS errors
173
options.setTimeout(30000); // 30 second timeout
174

175
// Configure for API testing
176
options.setJavaScriptEnabled(false);
177
options.setThrowExceptionOnFailingStatusCode(true); // Fail on HTTP errors
178
```
179

180
### Window Management
181

182
Manage browser windows, frames, and navigation history.
183

184
```java { .api }
185
/**
186
 * Get all open browser windows
187
 * @return List of WebWindow objects
188
 */
189
public List<WebWindow> getWebWindows();
190

191
/**
192
 * Wait for background JavaScript to complete
193
 * @param timeoutMillis maximum time to wait in milliseconds  
194
 * @return number of JavaScript jobs that completed
195
 */
196
public int waitForBackgroundJavaScript(long timeoutMillis);
197

198
/**
199
 * Wait for background JavaScript that started before a given time
200
 * @param delayMillis only wait for jobs that started before this delay
201
 * @return number of JavaScript jobs that completed
202
 */
203
public int waitForBackgroundJavaScriptStartingBefore(long delayMillis);
204

205
/**
206
 * Get the current active window
207
 * @return the current WebWindow
208
 */
209
public WebWindow getCurrentWindow();
210

211
/**
212
 * Set the current active window
213
 * @param window the WebWindow to make current
214
 */
215
public void setCurrentWindow(WebWindow window);
216

217
/**
218
 * Get all top-level windows (main windows, not frames)
219
 * @return List of TopLevelWindow objects
220
 */
221
public List<TopLevelWindow> getTopLevelWindows();
222

223
/**
224
 * Open a window with target handling (_blank, _self, named windows)
225
 * @param opener the window that initiated the open
226
 * @param windowName the target window name
227
 * @param defaultName default name if windowName is generic
228
 * @return the target WebWindow
229
 */
230
public WebWindow openTargetWindow(WebWindow opener, String windowName, String defaultName);
231

232
/**
233
 * Open a new window with the specified URL
234
 * @param url the URL to load in the new window
235
 * @param windowName the name for the new window
236
 * @return the newly created WebWindow
237
 * @throws IOException if window creation fails
238
 */
239
public WebWindow openWindow(URL url, String windowName) throws IOException;
240

241
/**
242
 * Get the current web connection
243
 * @return WebConnection instance
244
 */
245
public WebConnection getWebConnection();
246

247
/**
248
 * Set a custom web connection
249
 * @param connection custom WebConnection implementation
250
 */
251
public void setWebConnection(WebConnection connection);
252
```
253

254
**Usage Examples:**
255

256
```java
257
// Wait for JavaScript to complete after page load
258
webClient.waitForBackgroundJavaScript(5000); // Wait up to 5 seconds
259

260
// Wait for JavaScript that started before page load completed
261
webClient.waitForBackgroundJavaScriptStartingBefore(1000);
262

263
// Window management
264
WebWindow currentWindow = webClient.getCurrentWindow();
265
System.out.println("Current window: " + currentWindow.getName());
266

267
// Switch to different window
268
List<WebWindow> allWindows = webClient.getWebWindows();
269
for (WebWindow window : allWindows) {
270
    if ("targetFrame".equals(window.getName())) {
271
        webClient.setCurrentWindow(window);
272
        break;
273
    }
274
}
275

276
// Get only top-level windows (not frames)
277
List<TopLevelWindow> topWindows = webClient.getTopLevelWindows();
278
System.out.println("Top-level windows: " + topWindows.size());
279

280
// Open popup window
281
WebWindow popupWindow = webClient.openWindow(
282
    new URL("https://example.com/popup"), 
283
    "popupWindow"
284
);
285

286
// Handle window targets (from links/forms with target="_blank", etc.)
287
WebWindow targetWindow = webClient.openTargetWindow(
288
    currentWindow, 
289
    "_blank", 
290
    "newWindow"
291
);
292
```
293

294
### Cookie Management
295

296
Access and configure cookie handling through the integrated CookieManager.
297

298
```java { .api }
299
/**
300
 * Get the cookie manager for this client
301
 * @return CookieManager instance
302
 */
303
public CookieManager getCookieManager();
304

305
/**
306
 * Set a custom cookie manager
307
 * @param manager custom CookieManager implementation  
308
 */
309
public void setCookieManager(CookieManager manager);
310
```
311

312
**Usage Examples:**
313

314
```java
315
CookieManager cookieManager = webClient.getCookieManager();
316

317
// Add a cookie
318
Cookie sessionCookie = new Cookie("example.com", "sessionId", "abc123");
319
cookieManager.addCookie(sessionCookie);
320

321
// Clear all cookies
322
cookieManager.clearCookies();
323
```
324

325
### JavaScript Event Handlers
326

327
Configure handlers for JavaScript dialog boxes and errors.
328

329
```java { .api }
330
/**
331
 * Set handler for JavaScript alert() calls
332
 * @param handler AlertHandler implementation
333
 */
334
public void setAlertHandler(AlertHandler handler);
335

336
/**
337
 * Set handler for JavaScript confirm() calls  
338
 * @param handler ConfirmHandler implementation
339
 */
340
public void setConfirmHandler(ConfirmHandler handler);
341

342
/**
343
 * Set handler for JavaScript prompt() calls
344
 * @param handler PromptHandler implementation  
345
 */
346
public void setPromptHandler(PromptHandler handler);
347
```
348

349
**Usage Examples:**
350

351
```java
352
// Handle alerts by printing to console
353
webClient.setAlertHandler((page, message) -> {
354
    System.out.println("Alert: " + message);
355
});
356

357
// Handle confirms by always returning true
358
webClient.setConfirmHandler((page, message) -> {
359
    System.out.println("Confirm: " + message + " -> OK");
360
    return true;
361
});
362

363
// Handle prompts with default values
364
webClient.setPromptHandler((page, message, defaultValue) -> {
365
    System.out.println("Prompt: " + message);
366
    return defaultValue != null ? defaultValue : "default response";
367
});
368
```