Web Client Management

/**
 * Creates a new WebClient with default browser version (Chrome)
 */
public WebClient();

/**
 * Creates a new WebClient with specified browser version
 * @param browserVersion Browser version to emulate
 */
public WebClient(BrowserVersion browserVersion);

/**
 * Gets the client configuration options
 * @return WebClientOptions for configuration
 */
public WebClientOptions getOptions();

/**
 * Gets the browser version being emulated
 * @return BrowserVersion currently configured
 */
public BrowserVersion getBrowserVersion();

/**
 * Closes the client and releases all resources
 */
public void close();

// Default Chrome browser
WebClient webClient = new WebClient();

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

// Using try-with-resources for automatic cleanup
try (WebClient webClient = new WebClient(BrowserVersion.CHROME)) {
    // Client automatically closed
}

/**
 * Navigate to a page using a URL string
 * @param url URL to navigate to
 * @return Page object representing the loaded page
 * @throws IOException if navigation fails
 */
public <P extends Page> P getPage(String url) throws IOException;

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

/**
 * Navigate using a custom WebRequest with headers, parameters, and method
 * @param request WebRequest with custom configuration
 * @return Page object representing the loaded page
 * @throws IOException if navigation fails
 */
public <P extends Page> P getPage(WebRequest request) throws IOException;

// Simple URL navigation
HtmlPage page = webClient.getPage("https://example.com");

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

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

public class WebClientOptions {
    /**
     * Enable or disable JavaScript execution
     * @param enabled true to enable JavaScript
     */
    public void setJavaScriptEnabled(boolean enabled);
    
    /**
     * Check if JavaScript is enabled
     * @return true if JavaScript is enabled
     */
    public boolean isJavaScriptEnabled();
    
    /**
     * Enable or disable CSS processing
     * @param enabled true to enable CSS
     */
    public void setCssEnabled(boolean enabled);
    
    /**
     * Check if CSS processing is enabled
     * @return true if CSS is enabled
     */
    public boolean isCssEnabled();
    
    /**
     * Configure whether to throw exceptions on JavaScript errors
     * @param throwException true to throw exceptions on script errors
     */
    public void setThrowExceptionOnScriptError(boolean throwException);
    
    /**
     * Configure whether to throw exceptions on HTTP error status codes
     * @param throwException true to throw exceptions on failing status codes
     */
    public void setThrowExceptionOnFailingStatusCode(boolean throwException);
    
    /**
     * Set connection timeout in milliseconds
     * @param timeout timeout in milliseconds
     */
    public void setTimeout(int timeout);
    
    /**
     * Enable or disable automatic redirect following
     * @param enabled true to follow redirects
     */
    public void setRedirectEnabled(boolean enabled);
    
    /**
     * Enable or disable popup blocker
     * @param enabled true to block popups
     */
    public void setPopupBlockerEnabled(boolean enabled);
}

WebClientOptions options = webClient.getOptions();

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

// Configure for API testing
options.setJavaScriptEnabled(false);
options.setThrowExceptionOnFailingStatusCode(true); // Fail on HTTP errors

/**
 * Get all open browser windows
 * @return List of WebWindow objects
 */
public List<WebWindow> getWebWindows();

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

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

/**
 * Get the current active window
 * @return the current WebWindow
 */
public WebWindow getCurrentWindow();

/**
 * Set the current active window
 * @param window the WebWindow to make current
 */
public void setCurrentWindow(WebWindow window);

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

/**
 * Open a window with target handling (_blank, _self, named windows)
 * @param opener the window that initiated the open
 * @param windowName the target window name
 * @param defaultName default name if windowName is generic
 * @return the target WebWindow
 */
public WebWindow openTargetWindow(WebWindow opener, String windowName, String defaultName);

/**
 * Open a new window with the specified URL
 * @param url the URL to load in the new window
 * @param windowName the name for the new window
 * @return the newly created WebWindow
 * @throws IOException if window creation fails
 */
public WebWindow openWindow(URL url, String windowName) throws IOException;

/**
 * Get the current web connection
 * @return WebConnection instance
 */
public WebConnection getWebConnection();

/**
 * Set a custom web connection
 * @param connection custom WebConnection implementation
 */
public void setWebConnection(WebConnection connection);

// Wait for JavaScript to complete after page load
webClient.waitForBackgroundJavaScript(5000); // Wait up to 5 seconds

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

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

// Switch to different window
List<WebWindow> allWindows = webClient.getWebWindows();
for (WebWindow window : allWindows) {
    if ("targetFrame".equals(window.getName())) {
        webClient.setCurrentWindow(window);
        break;
    }
}

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

// Open popup window
WebWindow popupWindow = webClient.openWindow(
    new URL("https://example.com/popup"), 
    "popupWindow"
);

// Handle window targets (from links/forms with target="_blank", etc.)
WebWindow targetWindow = webClient.openTargetWindow(
    currentWindow, 
    "_blank", 
    "newWindow"
);

/**
 * Get the cookie manager for this client
 * @return CookieManager instance
 */
public CookieManager getCookieManager();

/**
 * Set a custom cookie manager
 * @param manager custom CookieManager implementation  
 */
public void setCookieManager(CookieManager manager);

CookieManager cookieManager = webClient.getCookieManager();

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

// Clear all cookies
cookieManager.clearCookies();

/**
 * Set handler for JavaScript alert() calls
 * @param handler AlertHandler implementation
 */
public void setAlertHandler(AlertHandler handler);

/**
 * Set handler for JavaScript confirm() calls  
 * @param handler ConfirmHandler implementation
 */
public void setConfirmHandler(ConfirmHandler handler);

/**
 * Set handler for JavaScript prompt() calls
 * @param handler PromptHandler implementation  
 */
public void setPromptHandler(PromptHandler handler);

// Handle alerts by printing to console
webClient.setAlertHandler((page, message) -> {
    System.out.println("Alert: " + message);
});

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

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