2 Browser item JavaScript objects

Overview

This section describes Zabbix additions to the JavaScript language implemented with Duktape for use in the Browser item script. These additions supplement the JavaScript objects described on the Additional JavaScript objects page.

Browser

The Browser object manages WebDriver sessions, initializing a session upon creation and terminating it upon destruction. A single script can support up to four Browser objects.

To construct a Browser object, use the new Browser(options) syntax. The options (JSON object) parameter specifies browser options, usually the WebDriver options method result (for example, Browser.chromeOptions()).

The following methods are supported with the Browser object.

Method	Description
`navigate(url)`	Navigate to the specified URL. Parameters: `url` - (string) URL to navigate to.
`getUrl()`	Return a string of the opened page URL.
`getPageSource()`	Return a string of the opened page source.
`findElement(strategy, selector)`	Return an `Element` object with one element in the opened page (or return `null` if no elements match `strategy` and `selector`). Parameters: `strategy` - (string, CSS selector/link text/partial link text/tag name/Xpath) Location strategy; `selector` - (string) Element selector using the specified location strategy.
`findElements(strategy, target)`	Return an array of `Element` objects with multiple elements in the opened page (or return an empty array if no elements match location strategy and target). Parameters: `strategy` - (string, CSS selector/link text/partial link text/tag name/Xpath) Location strategy; `target` - (string) Element selector using the specified location strategy.
`getCookies()`	Return an array of `Cookie` objects.
`addCookie(cookie)`	Set cookies. Parameters: `cookie` - (`Cookie` object) Cookie to set.
`getScreenshot()`	Return a base64 encoded string representing an image of the browser's viewport.
`setScreenSize(x,y)`	Set the browser's viewport size. Parameters: `x` - (string) Height in pixels; `y` - (string) Width in pixels.
`setScriptTimeout(timeout)`	Set script loading timeout. Parameters: `timeout` - (integer) Timeout value in milliseconds.
`setSessionTimeout(timeout)`	Set session (page load) timeout. Parameters: `timeout` - (integer) Timeout value in milliseconds.
`setElementWaitTimeout(timeout)`	Set element location strategy (implicit) timeout. Parameters: `timeout` - (integer) Timeout value in milliseconds.
`collectPerfEntries(mark)`	Collect performance entries to retrieve with the `getResult()` method. Parameters: `mark` - (string, optional) Performance snapshot mark.
`getRawPerfEntries()`	Return an array of performance entry objects.
`getResult()`	Return a `Result` object with browser session statistics (error information, performance snapshots, etc.).
`getError()`	Return a `BrowserError` object with browser errors (or return `null` if there are no browser errors).
`setError(message)`	Set a custom error message to be included in the `Result` object. Parameters: `message` - (string) Error message.
`discardError()`	Discard the error to be returned in the `Result` object.
`getAlert()`	Return an `Alert` object with browser alerts (or return `null` if there are no browser alerts).
`chromeOptions()`	Return a `chromeOptions` object with predefined Chrome browser options.
`firefoxOptions()`	Return a `firefoxOptions` object with predefined Firefox browser options.
`safariOptions()`	Return a `safariOptions` object with predefined Safari browser options.
`edgeOptions()`	Return an `edgeOptions` object with predefined Edge browser options.
`switchFrame(target)`	Switch to the specified frame. Supported since version 7.0.4. Parameters: `target` - (browser element or integer, optional) Target frame. To select a frame by element, pass the element. To select a frame by index, pass the number. If left empty, will switch to the top-level browsing context.

All Browser methods can throw the following errors:

BrowserError - derived from the Error object that is thrown if the Browser constructor fails; contains an additional browser property with a Browser object that threw this BrowserError.
WebdriverError - derived from BrowserError; contains the same properties as the BrowserError object, which indicate if the error was generated in response to an error in the WebDriver response.

Element

The Element object is returned by the Browser object findElement()/findElements() methods and cannot be constructed directly.

The Element object represents an element in the web page and provides methods to interact with it.

The following methods are supported with the Element object.

Method	Description
`getAttribute(name)`	Return an attribute value string of the element attribute (or return `null` if the specified attribute was not found). Parameters: `name` - (string) Attribute name.
`getProperty(name)`	Return a property value string of the element property (or return `null` if the specified property was not found). Parameters: `name` - (string) Property name.
`getText()`	Return a text value string of the element text.
`click()`	Click on an element.
`clear()`	Clear the content of an editable element.
`sendKeys(keys)`	Send keys. Parameters: `keys` - (string) Keys to send.

The Cookie object is returned by the Browser object getCookies() method and passed to the addCookie() method.

While the Cookie object does not have any methods, it can contain the following properties:

Property	Type	Description
name	string	Name of the cookie.
value	string	Value of the cookie.
path	string	Path for which the cookie is valid. Defaults to `"/"` if omitted when adding a cookie.
domain	string	Domain to which the cookie is visible. Defaults to the URL domain of the session's current browsing context's active document if omitted when adding a cookie.
secure	boolean	Indicates whether the cookie is secure. Defaults to `false` if omitted when adding a cookie.
httpOnly	boolean	Indicates whether the cookie is HTTP-only. Defaults to `false` if omitted when adding a cookie.
expiry	integer	Expiration time of the cookie (in seconds since the Unix Epoch). Must not be set if omitted when adding a cookie.
sameSite	string	The `sameSite` attribute of the cookie, which controls whether the cookie should be restricted to a first-party or same-site context. Can be set to either `"Lax"` or `"Strict"`. Defaults to `"None"` if omitted when adding a cookie.

Alert

The Alert object represents a web page alert, is returned by Browser object getAlert() method, and cannot be constructed directly.

The Alert object contains the text property with the alert text (or null if there are no alerts).

The following methods are supported with the Alert object.

Method	Description
`accept()`	Accept the alert.
`dismiss()`	Dismiss the alert.

Result

The Result object contains session statistics and is returned by the Browser object getResult() method.

Typically, the Result object is stringified and returned from the script, and then parsed into dependent item values through preprocessing.

While the Result object does not have any methods, it can contain the following properties.

Property			Type	Description
duration			string	Session duration from session creation to result retrieval.
error			object	Error information.
	http_status		integer	HTTP status returned by the WebDriver (or 0 if there are no WebDriver errors).
	error_code		string	Error returned by the WebDriver (or empty string if there are no WebDriver errors).
	message		string	WebDriver error message (or empty string if there are no WebDriver errors).
performance_data			object	Performance statistics.
	summary		object	Performance summary.
		navigation	object	Navigation summary.
		resource	object	Resource summary.
	details		array of objects	Performance statistics after each operation that could have resulted in navigation.
		mark	string	(optional) Performance snapshot mark specified with the `collectPerfEntries()` method.
		navigation	object	Navigation statistics.
		resource	object	Resource summary for this step.
		user	array of objects	Array of mark/measure type statistics.
	marks		array of objects	Marked performance snapshot indexes.
		name	string	Performance snapshot mark name.
		index	integer	Performance snapshot index in details array.

Documentation