|
| 1 | +# HtmlUnitDriverOptions Class |
| 2 | + |
| 3 | +The **HtmlUnitDriverOptions** class provides methods to manage options specific to **HtmlUnitDriver**. This browser-specific |
| 4 | +options object is assigned to the custom capability name **`garg:htmlunitOptions`**. |
| 5 | + |
| 6 | +### HtmlUnitDriverOptions example usage: |
| 7 | + |
| 8 | +```java |
| 9 | +HtmlUnitDriverOptions options = new HtmlUnitDriverOptions() |
| 10 | + .setWebClientVersion(BrowserVersion.FIREFOX_ESR) |
| 11 | + .setJavaScriptEnabled(true); |
| 12 | + |
| 13 | +// For use with HtmlUnitDriver: |
| 14 | +HtmlUnitDriver driver = new HtmlUnitDriver(options); |
| 15 | + |
| 16 | +// For use with RemoteWebDriver: |
| 17 | +RemoteWebDriver driver = new RemoteWebDriver( |
| 18 | + new URL("http://localhost:4444/"), |
| 19 | + new HtmlUnitDriverOptions()); |
| 20 | +``` |
| 21 | + |
| 22 | +## Getting/setting HtmlUnitDriver options: |
| 23 | + |
| 24 | +In addition to methods for reading and writing specific **HtmlUnitDriver** options, you can use |
| 25 | +the standard **Capabilities** API: |
| 26 | + |
| 27 | +* `is(String)` |
| 28 | +* `getCapability(String)` |
| 29 | +* `setCapability(String, Object)` |
| 30 | + |
| 31 | +### Getting individual browser version traits: |
| 32 | + |
| 33 | +**HtmlUnitDriverOptions** contains a **BrowserVersion** capability which can be read and written directly: |
| 34 | + |
| 35 | +* `getWebClientVersion()` |
| 36 | +* `setWebClientVersion(BrowserVersion)` |
| 37 | + |
| 38 | +The individual traits of the **BrowserVersion** object can be read directly as well via the standard |
| 39 | +**Capabilities** API. For example: |
| 40 | + |
| 41 | +```java |
| 42 | +HtmlUnitDriverOptions options = new HtmlUnitDriverOptions(BrowserVersion.EDGE); |
| 43 | +// System time zone accessed via BrowserVersion API |
| 44 | +TimeZone viaBrowserVersion = options.getWebClientVersion.getSystemTimezone(); |
| 45 | +// System time zone accessed via standard Capabilities API |
| 46 | +TimeZone viaCapabilityName = (TimeZone) options.getCapability(BrowserVersionTrait.optSystemTimezone); |
| 47 | +``` |
| 48 | + |
| 49 | +**NOTE**: Although **HtmlUnitDriverOptions** objects are mutable (their capabilities can be altered), |
| 50 | +the individual traits of the **BrowserVersion** object within these objects cannot be altered: |
| 51 | + |
| 52 | +```java |
| 53 | +HtmlUnitDriverOptions options = new HtmlUnitDriverOptions(BrowserVersion.CHROME); |
| 54 | +options.setCapability(BrowserVersionTrait.optUserAgent, "HtmlUnitDriver emulating Google Chrome"); |
| 55 | +// => UnsupporterOperationException: Individual browser version traits are immutable; 'optUserAgent' cannot be set |
| 56 | +``` |
| 57 | + |
| 58 | +For more details, see [The BrowserVersionTraits Enumeration](#the-browserversiontrait-enumeration) below. |
| 59 | + |
| 60 | +## The HtmlUnitOption Enumeration |
| 61 | + |
| 62 | +The **HtmlUnitDriverOptions** class provides a few targeted methods for manipulating frequently-used or complex capabilities |
| 63 | +(e.g. - `isJavaScriptEnabled()`). However, the majority of the capabilities of **HtmlUnitDriver** are manipulated via the |
| 64 | +standard **Capabilities** API as shown above. All of the capabilities defined by **HtmlUnitDriver** are represented |
| 65 | +in the **HtmlUnitOption** enumeration, which provides the capability names, accessors, and mutators for the browser options. |
| 66 | + |
| 67 | +### HtmlUnitOption/BrowserVersionTrait example usage: |
| 68 | + |
| 69 | +```java |
| 70 | +HtmlUnitDriverOptions options = new HtmlUnitDriverOptions(); |
| 71 | +boolean popupBlockerEnabled = options.is(HtmlUnitOption.optPopupBlockerEnabled); |
| 72 | +// NOTE: See subsection "Getting individual browser version traits" above |
| 73 | +String browserLanguage = (String) options.getCapability(BrowserVersionTrait.optBrowserLanguage); |
| 74 | +options.setCapability(HtmlUnitOption.optGeolocationEnabled, true); |
| 75 | +``` |
| 76 | + |
| 77 | +| property name | value type | default | description | |
| 78 | +|--|--|--|--| |
| 79 | +| webClientVersion | **BrowserVersion** | BrowserVersion.BEST_SUPPORTED | Browser version of this **HtmlUnitDriver**. | |
| 80 | +| javascriptEnabled | boolean | `true` | Enables/disables JavaScript support. | |
| 81 | +| cssEnabled | boolean | `true` | <details><summary>Enables/disables CSS support. </summary>If disabled, **HtmlUnit** will not download linked CSS files and also not trigger the associated `onload`/`onerror` events.</details> | |
| 82 | +| printContentOnFailingStatusCode | boolean | `true` | <details><summary>Print document on failing status code. </summary>Specifies whether or not the content of the resulting document will be printed to the console in the event of a failing response code. Successful response codes are in the range **200-299**.</details> | |
| 83 | +| throwExceptionOnFailingStatusCode | boolean | `true` | <details><summary>Throw exception on failing status code. </summary>Specifies whether or not an exception will be thrown in the event of a failing status code. Successful status codes are in the range **200-299**.</details> | |
| 84 | +| throwExceptionOnScriptError | boolean | `true` | <details><summary>Throw exception on script error. </summary>Indicates if an exception should be thrown when a script execution fails or if it should be caught and just logged to allow page execution to continue.</details> | |
| 85 | +| popupBlockerEnabled | boolean | `false` | <details><summary>Enable/disable the popup window blocker. </summary>By default, the popup blocker is disabled, and popup windows are allowed. When set to `true`, the `window.open()` function has no effect and returns `null`.</details> | |
| 86 | +| isRedirectEnabled | boolean | `true` | <details><summary>Enables/disables automatic redirection. </summary>Sets whether or not redirections will be followed automatically on receipt of a redirect status code from the server.</details> | |
| 87 | +| tempFileDirectory | **File** | _(none)_ (use system default) | <details><summary>Directory for response content temporary files. </summary>Path to the directory to be used for storing the response content in a temporary file. The specified directory is created if it doesn't exist.</details> | |
| 88 | +| sslClientCertificateStore | **KeyStore** | _(none)_ | <details><summary>The SSL client certificate **KeyStore** to use. </summary>**NOTE**: This option is omitted when serializing session settings.</details> | |
| 89 | +| sslClientCertificateType | char[] | _(none)_ | Type of the specified SSL client certificate **KeyStore** (e.g. - `jks` or `pkcs12`). | |
| 90 | +| sslClientCertificatePassword | char[] | _(none)_ | Password for the specified SSL client certificate **KeyStore**. | |
| 91 | +| sslTrustStore | KeyStore | _(none)_ | <details><summary>The SSL server certificate trust store. </summary>All server certificates will be validated against this trust store.</details> | |
| 92 | +| sslTrustStoreType | char[] | _(none)_ | Type of the specified SSL trust **KeyStore** (e.g. - `jks` or `pkcs12`). | |
| 93 | +| sslTrustStorePassword | char[] | _(none)_ | Password for the specified SSL trust **KeyStore**. | |
| 94 | +| sslClientProtocols | **String[]** | _(none)_ (use default protocols) | Protocol versions enabled for use on SSL connections. | |
| 95 | +| sslClientCipherSuites | **String[]** | _(none)_ (use default suites) | Cipher suites enabled for use on SSL connections. | |
| 96 | +| geolocationEnabled | boolean | `false` | Enables/disables geo-location support. | |
| 97 | +| doNotTrackEnabled | boolean | `false` | Enables/disables "Do Not Track" support. | |
| 98 | +| homePage | **String** | "https://www.htmlunit.org/" | Home page for this client. | |
| 99 | +| proxyConfig | **ProxyConfig** | _(none)_ | Proxy configuration for this client. | |
| 100 | +| timeout | int | 90,000 | <details><summary>**WebConnection** timeout for this client. </summary>Set to zero (0) for an infinite wait.</details> | |
| 101 | +| connectionTimeToLive | long | -1L (use HTTP default) | <details><summary>**HttpClient** connection pool `connTimeToLive` (in milliseconds). </summary>Use this if you are working with web pages behind a DNS based load balancer.</details> | |
| 102 | +| useInsecureSSL | boolean | `false` | <details><summary>Accept/reject connection to servers with expired or corrupt certificates. </summary>If set to `true`, the client will accept connections to any host, regardless of whether they have valid certificates or not. This is especially useful when you are trying to connect to a server with expired or corrupt certificates.</details> | |
| 103 | +| sslInsecureProtocol | **String** | _(none)_ (use SSL) | SSL protocol to use when `USE_INSECURE_SSL` is set to `true`. | |
| 104 | +| maxInMemory | int | 500 * 1024 | <details><summary>Maximum bytes to have in memory. </summary>Content that exceeds the specified maximum size is stored in a temporary file. Specifying **0** or **-1** deactivates this storage feature.</details> | |
| 105 | +| historySizeLimit | int | 50 | <details><summary>Maximum number of pages to cache in history. </summary>**HtmlUnit** uses `SoftReference<Page>` for storing the pages that are part of the history. If you like to fine tune this, you can use **HISTORY_PAGE_CACHE_LIMIT** to limit the number of page references stored by the history.</details> | |
| 106 | +| historyPageCacheLimit | int | Integer.MAX_VALUE | <details><summary>Maximum number of pages to cache in history. </summary>If this value is smaller than **HISTORY_SIZE_LIMIT**, **HtmlUnit** will only use soft references for the first **HISTORY_PAGE_CACHE_LIMIT** entries in the history. For older entries, only the URL is saved; the page will be (re)retrieved on demand.</details> | |
| 107 | +| localAddress | **InetAddress** | _(none)_ (use `localhost`) | <details><summary>Local address to be used for request execution. </summary>On machines with multiple network interfaces, this parameter can be used to select the network interface from which the connection originates.</details> | |
| 108 | +| downloadImages | boolean | `false` | Enables/disables automatic image downloading. | |
| 109 | +| screenWidth | int | 1920 | Screen width. | |
| 110 | +| screenHeight | int | 1080 | Screen height. | |
| 111 | +| webSocketEnabled | boolean | `true` | Enables/disables WebSocket support. | |
| 112 | +| webSocketMaxTextMessageSize | int | -1 (use default size) | WebSocket `maxTextMessageSize` parameter. | |
| 113 | +| webSocketMaxTextMessageBufferSize | int | -1 (use default size) | WebSocket `maxTextMessageBufferSize` parameter. | |
| 114 | +| webSocketMaxBinaryMessageSize | int | -1 (use default size) | WebSocket `maxBinaryMessageSize` parameter. | |
| 115 | +| webSocketMaxBinaryMessageBufferSize | int | -1 (use default size) | WebSocket `maxBinaryMessageBufferSize` parameter. | |
| 116 | +| fetchPolyfillEnabled | boolean | `false` | Enables/disables fetch polyfill | |
| 117 | +| fileProtocolForXMLHttpRequestsAllowed | boolean | `false` | <details><summary>Allows/blocks file protocol for **XMLHttpRequests**. </summary>If set to `true`, the client will accept **XMLHttpRequests** to URLs using the `file` protocol. Allowing this introduces security problems and is therefore not allowed by current browsers. But some browsers have special settings to open this door; therefore, we have this option.</details> | |
| 118 | + |
| 119 | +## The BrowserVersionTrait Enumeration |
| 120 | + |
| 121 | + The **BrowserVersion** capability of **HtmlUnitDriverOptions** is comprised of many individual traits, and each of these can be read discretely via the standard **Capabiltiies** API. Examples of this are shown above (e.g. - [SYSTEM_TIME_ZONE](#getting-individual-browser-version-traits)). Note that these traits are immutable. |
| 122 | + |
| 123 | + > **NOTE**: Technically, the traits of **BrowserVersion** objects can be revised, but alterations made to existing instances aren't propagated to the associated **HtmlUnitDriver**; browser version traits are only imported en masse when a new browser version is specified. To avoid confusion, setting of individual traits is only supported via the **BrowserVersionBuilder** class. |
| 124 | +
|
| 125 | +For additional information, see [Getting individual browser version traits](#getting-individual-browser-version-traits) above. |
| 126 | + |
| 127 | +| trait name | value type | default | description | |
| 128 | +|--|--|--|--| |
| 129 | +| numericCode | int | **0** | Returns the numeric code for the browser represented by this **BrowserVersion**. | |
| 130 | +| nickname | **String** | _(none)_ | Returns the nickname for the browser represented by this **BrowserVersion**. | |
| 131 | +| applicationVersion | **String** | _(none)_ | <details><summary>Returns the application version. </summary>e.g. - "4.0 (compatible; MSIE 6.0b; Windows 98)".</details> | |
| 132 | +| userAgent | **String** | _(none)_ | <details><summary>Returns the user agent string. </summary>e.g. - "Mozilla/4.0 (compatible; MSIE 6.0b; Windows 98)"</details> | |
| 133 | +| applicationName | **String** | _(none)_ | <details><summary>Returns the application name. </summary>e.g. - "Microsoft Internet Explorer"</details> | |
| 134 | +| applicationCodeName | **String** | "Mozilla" | Returns the application code name. | |
| 135 | +| applicationMinorVersion | **String** | "0" | Returns the application minor version. | |
| 136 | +| vendor | **String** | "" | <details><summary>Returns the browser vendor. </summary>e.g. - "Google Inc."</details> | |
| 137 | +| browserLanguage | **String** | "en-US" | Returns the browser language. | |
| 138 | +| isOnline | boolean | `true` | Returns `true` if the browser is currently online. | |
| 139 | +| platform | **String** | "Win32" | Returns the platform on which the application is running. | |
| 140 | +| systemTimezone | **TimeZone** | <code>TimeZone.getTimeZone( "America/New_York")</code> | Returns the system **TimeZone**. | |
| 141 | +| acceptEncodingHeader | **String** | _(none)_ | Returns the value used by the browser for the `Accept-Encoding` header. | |
| 142 | +| acceptLanguageHeader | **String** | _(none)_ | Returns the value used by the browser for the `Accept-Language` header. | |
| 143 | +| htmlAcceptHeader | **String** | _(none)_ | Returns the value used by the browser for the `Accept` header if requesting a page. | |
| 144 | +| imgAcceptHeader | **String** | _(none)_ | Returns the value used by the browser for the `Accept` header if requesting an image. | |
| 145 | +| cssAcceptHeader | **String** | _(none)_ | Returns the value used by the browser for the `Accept` header if requesting a CSS declaration. | |
| 146 | +| scriptAcceptHeader | **String** | _(none)_ | Returns the value used by the browser for the `Accept` header if requesting a script. | |
| 147 | +| xmlHttpRequestAcceptHeader | **String** | _(none)_ | Returns the value used by the browser for the `Accept` header if performing an **XMLHttpRequest**. | |
| 148 | +| secClientHintUserAgentHeader | **String** | _(none)_ | Returns the value used by the browser for the `Sec-CH-UA` header. | |
| 149 | +| secClientHintUserAgentPlatformHeader | **String** | _(none)_ | Returns the value used by the browser for the `Sec-CH-UA-Platform` header. | |
| 150 | + |
| 151 | +### HtmlUnitOption and BrowserVersionTrait System Property Definitions |
| 152 | + |
| 153 | +Each **HtmlUnitOption** property can be overridden by a corresponding Java system property whose name matches the pattern |
| 154 | +**webdriver.htmlunit._<property-or-trait-name>_** (e.g. - `webdriver.htmlunit.javascriptEnabled`). If defined, these |
| 155 | +system properties are applied as default values when **HtmlUnitDriver** is instantiated. Subsequent requests to update |
| 156 | +corresponding capabilities on existing drivers are honored as expected. |
| 157 | + |
| 158 | +> Written with [StackEdit](https://stackedit.io/). |
0 commit comments