options.md

HtmlUnitDriverOptions Class

The HtmlUnitDriverOptions class provides methods to manage options specific to HtmlUnitDriver. This browser-specific options object is assigned to the custom capability name garg:htmlunitOptions.

HtmlUnitDriverOptions example usage:

HtmlUnitDriverOptions options = new HtmlUnitDriverOptions()
    .setWebClientVersion(BrowserVersion.FIREFOX_ESR)
    .setJavaScriptEnabled(true);

// For use with HtmlUnitDriver:
HtmlUnitDriver driver = new HtmlUnitDriver(options);

// For use with RemoteWebDriver:
RemoteWebDriver driver = new RemoteWebDriver(
    new URL("http://localhost:4444/"),
    new HtmlUnitDriverOptions());

Getting/setting HtmlUnitDriver options:

In addition to methods for reading and writing specific HtmlUnitDriver options, you can use the standard Capabilities API:

• is(String)
• getCapability(String)
• setCapability(String, Object)

Getting individual browser version traits:

HtmlUnitDriverOptions contains a BrowserVersion capability which can be read and written directly:

• getWebClientVersion()
• setWebClientVersion(BrowserVersion)

The individual traits of the BrowserVersion object can be read directly as well via the standard Capabilities API. For example:

HtmlUnitDriverOptions options = new HtmlUnitDriverOptions(BrowserVersion.EDGE);
// System time zone accessed via BrowserVersion API
TimeZone viaBrowserVersion = options.getWebClientVersion.getSystemTimezone();
// System time zone accessed via standard Capabilities API
TimeZone viaCapabilityName = (TimeZone) options.getCapability(BrowserVersionTrait.optSystemTimezone);

NOTE: Although HtmlUnitDriverOptions objects are mutable (their capabilities can be altered), the individual traits of the BrowserVersion object within these objects cannot be altered:

HtmlUnitDriverOptions options = new HtmlUnitDriverOptions(BrowserVersion.CHROME);
options.setCapability(BrowserVersionTrait.optUserAgent, "HtmlUnitDriver emulating Google Chrome");
// => UnsupporterOperationException: Individual browser version traits are immutable; 'optUserAgent' cannot be set

For more details, see The BrowserVersionTraits Enumeration below.

The HtmlUnitOption Enumeration

The HtmlUnitDriverOptions class provides a few targeted methods for manipulating frequently-used or complex capabilities (e.g. - isJavaScriptEnabled()). However, the majority of the capabilities of HtmlUnitDriver are manipulated via the standard Capabilities API as shown above. All of the capabilities defined by HtmlUnitDriver are represented in the HtmlUnitOption enumeration, which provides the capability names, accessors, and mutators for the browser options.

HtmlUnitOption/BrowserVersionTrait example usage:

HtmlUnitDriverOptions options = new HtmlUnitDriverOptions();
boolean popupBlockerEnabled = options.is(HtmlUnitOption.optPopupBlockerEnabled);
// NOTE: See subsection "Getting individual browser version traits" above
String  browserLanguage = (String) options.getCapability(BrowserVersionTrait.optBrowserLanguage);
options.setCapability(HtmlUnitOption.optGeolocationEnabled, true);

property name	value type	default	description
webClientVersion	BrowserVersion	BrowserVersion.BEST_SUPPORTED	Browser version of this HtmlUnitDriver.
javascriptEnabled	boolean	true	Enables/disables JavaScript support.
cssEnabled	boolean	true	Enables/disables CSS support. If disabled, HtmlUnit will not download linked CSS files and also not trigger the associated onload/onerror events.
printContentOnFailingStatusCode	boolean	true	Print document on failing status code. 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.
throwExceptionOnFailingStatusCode	boolean	true	Throw exception on failing status code. 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.
throwExceptionOnScriptError	boolean	true	Throw exception on script error. 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.
popupBlockerEnabled	boolean	false	Enable/disable the popup window blocker. 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.
isRedirectEnabled	boolean	true	Enables/disables automatic redirection. Sets whether or not redirections will be followed automatically on receipt of a redirect status code from the server.
tempFileDirectory	File	(none) (use system default)	Directory for response content temporary files. 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.
sslClientCertificateStore	KeyStore	(none)	The SSL client certificate KeyStore to use. NOTE: This option is omitted when serializing session settings.
sslClientCertificateType	char[]	(none)	Type of the specified SSL client certificate KeyStore (e.g. - jks or pkcs12).
sslClientCertificatePassword	char[]	(none)	Password for the specified SSL client certificate KeyStore.
sslTrustStore	KeyStore	(none)	The SSL server certificate trust store. All server certificates will be validated against this trust store.
sslTrustStoreType	char[]	(none)	Type of the specified SSL trust KeyStore (e.g. - jks or pkcs12).
sslTrustStorePassword	char[]	(none)	Password for the specified SSL trust KeyStore.
sslClientProtocols	String[]	(none) (use default protocols)	Protocol versions enabled for use on SSL connections.
sslClientCipherSuites	String[]	(none) (use default suites)	Cipher suites enabled for use on SSL connections.
geolocationEnabled	boolean	false	Enables/disables geo-location support.
doNotTrackEnabled	boolean	false	Enables/disables "Do Not Track" support.
homePage	String	"https://www.htmlunit.org/"	Home page for this client.
proxyConfig	ProxyConfig	(none)	Proxy configuration for this client.
timeout	int	90,000	WebConnection timeout for this client. Set to zero (0) for an infinite wait.
connectionTimeToLive	long	-1L (use HTTP default)	HttpClient connection pool connTimeToLive (in milliseconds). Use this if you are working with web pages behind a DNS based load balancer.
useInsecureSSL	boolean	false	Accept/reject connection to servers with expired or corrupt certificates. 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.
sslInsecureProtocol	String	(none) (use SSL)	SSL protocol to use when USE_INSECURE_SSL is set to true.
maxInMemory	int	500 * 1024	Maximum bytes to have in memory. Content that exceeds the specified maximum size is stored in a temporary file. Specifying 0 or -1 deactivates this storage feature.
historySizeLimit	int	50	Maximum number of pages to cache in history. 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.
historyPageCacheLimit	int	Integer.MAX_VALUE	Maximum number of pages to cache in history. 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.
localAddress	InetAddress	(none) (use localhost)	Local address to be used for request execution. On machines with multiple network interfaces, this parameter can be used to select the network interface from which the connection originates.
downloadImages	boolean	false	Enables/disables automatic image downloading.
screenWidth	int	1920	Screen width.
screenHeight	int	1080	Screen height.
webSocketEnabled	boolean	true	Enables/disables WebSocket support.
webSocketMaxTextMessageSize	int	-1 (use default size)	WebSocket maxTextMessageSize parameter.
webSocketMaxTextMessageBufferSize	int	-1 (use default size)	WebSocket maxTextMessageBufferSize parameter.
webSocketMaxBinaryMessageSize	int	-1 (use default size)	WebSocket maxBinaryMessageSize parameter.
webSocketMaxBinaryMessageBufferSize	int	-1 (use default size)	WebSocket maxBinaryMessageBufferSize parameter.
fetchPolyfillEnabled	boolean	false	Enables/disables fetch polyfill
fileProtocolForXMLHttpRequestsAllowed	boolean	false	Allows/blocks file protocol for XMLHttpRequests. 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.

The BrowserVersionTrait Enumeration

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). Note that these traits are immutable.

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.

For additional information, see Getting individual browser version traits above.

trait name	value type	default	description
numericCode	int	0	Returns the numeric code for the browser represented by this BrowserVersion.
nickname	String	(none)	Returns the nickname for the browser represented by this BrowserVersion.
applicationVersion	String	(none)	Returns the application version. e.g. - "4.0 (compatible; MSIE 6.0b; Windows 98)".
userAgent	String	(none)	Returns the user agent string. e.g. - "Mozilla/4.0 (compatible; MSIE 6.0b; Windows 98)"
applicationName	String	(none)	Returns the application name. e.g. - "Microsoft Internet Explorer"
applicationCodeName	String	"Mozilla"	Returns the application code name.
applicationMinorVersion	String	"0"	Returns the application minor version.
vendor	String	""	Returns the browser vendor. e.g. - "Google Inc."
browserLanguage	String	"en-US"	Returns the browser language.
isOnline	boolean	true	Returns true if the browser is currently online.
platform	String	"Win32"	Returns the platform on which the application is running.
systemTimezone	TimeZone	TimeZone.getTimeZone(      "America/New_York")	Returns the system TimeZone.
acceptEncodingHeader	String	(none)	Returns the value used by the browser for the Accept-Encoding header.
acceptLanguageHeader	String	(none)	Returns the value used by the browser for the Accept-Language header.
htmlAcceptHeader	String	(none)	Returns the value used by the browser for the Accept header if requesting a page.
imgAcceptHeader	String	(none)	Returns the value used by the browser for the Accept header if requesting an image.
cssAcceptHeader	String	(none)	Returns the value used by the browser for the Accept header if requesting a CSS declaration.
scriptAcceptHeader	String	(none)	Returns the value used by the browser for the Accept header if requesting a script.
xmlHttpRequestAcceptHeader	String	(none)	Returns the value used by the browser for the Accept header if performing an XMLHttpRequest.
secClientHintUserAgentHeader	String	(none)	Returns the value used by the browser for the Sec-CH-UA header.
secClientHintUserAgentPlatformHeader	String	(none)	Returns the value used by the browser for the Sec-CH-UA-Platform header.

HtmlUnitOption and BrowserVersionTrait System Property Definitions

Each HtmlUnitOption property can be overridden by a corresponding Java system property whose name matches the pattern webdriver.htmlunit.<property-or-trait-name> (e.g. - webdriver.htmlunit.javascriptEnabled). If defined, these system properties are applied as default values when HtmlUnitDriver is instantiated. Subsequent requests to update corresponding capabilities on existing drivers are honored as expected.

Written with StackEdit.