[comment]: # (tags: browser)

[comment]: # ({b2b7cc8c-5b27f125})
## 2 浏览器项目 JavaScript 对象

[comment]: # ({/b2b7cc8c-5b27f125})

[comment]: # ({78a26b1c-8dceeea0})
#### 概述

本节描述了使用Duktape实现的Zabbix对JavaScript语言的扩展，用于在[浏览器项目](/manual/config/items/itemtypes/browser)脚本中使用。
这些扩展补充了[附加JavaScript对象](/manual/config/items/preprocessing/javascript/javascript_objects)页面中描述的JavaScript对象。

[comment]: # ({/78a26b1c-8dceeea0})

[comment]: # ({4c174987-63b1c0c6})
#### Browser

`Browser` 对象用于管理 WebDriver 会话，在创建时初始化会话，并在销毁时终止会话。
单个脚本最多可支持四个 `Browser` 对象。

要构造 `Browser` 对象，请使用 `new Browser(options)` 语法。
`options`（*JSON object*）参数用于指定浏览器选项，通常为 WebDriver options 方法的返回结果（例如 `Browser.chromeOptions()`）。

`Browser` 对象支持以下方法。

|Method|Description|
|---|-------|
|`navigate(url)`|导航到指定的 URL。<br><br>参数：<br>`url` - (string) 要导航到的 URL。|
|`getUrl()`|返回已打开页面 URL 的字符串。|
|`getPageSource()`|返回已打开页面源代码的字符串。|
|`findElement(strategy, selector)`|返回一个 [`Element`](#element) 对象，表示已打开页面中的单个元素（如果没有元素匹配 `strategy` 和 `selector`，则返回 `null`）。<br><br>参数：<br>`strategy` - (string, css selector/link text/partial link text/tag name/xpath) [定位策略](https://www.selenium.dev/documentation/webdriver/elements/locators/)；<br>`selector` - (string) 使用指定定位策略的元素选择器。|
|`findElements(strategy, target)`|返回一个包含多个 [`Element`](#element) 对象的数组，表示已打开页面中的多个元素（如果没有元素匹配定位策略和 target，则返回空数组）。<br><br>参数：<br>`strategy` - (string, css selector/link text/partial link text/tag name/xpath) [定位策略](https://www.selenium.dev/documentation/webdriver/elements/locators/)；<br>`target` - (string) 使用指定定位策略的元素选择器。|
|`getCookies()`|返回一个 [`Cookie`](#cookie) 对象数组。|
|`addCookie(cookie)`|设置 Cookie。<br><br>参数：<br>`cookie` - ([`Cookie`](#cookie) object) 要设置的 Cookie。|
|`getScreenshot()`|返回一个 base64 编码的字符串，表示浏览器视口的图像。|
|`setScreenSize(x,y)`|设置浏览器视口大小。<br><br>参数：<br>`x` - (string) 以像素为单位的宽度；<br>`y` - (string) 以像素为单位的高度。|
|`setScriptTimeout(timeout)`|设置脚本加载超时时间。<br><br>参数：<br>`timeout` - (integer) 以毫秒为单位的超时值。|
|`setSessionTimeout(timeout)`|设置会话（页面加载）超时时间。<br><br>参数：<br>`timeout` - (integer) 以毫秒为单位的超时值。|
|`setElementWaitTimeout(timeout)`|设置元素定位策略的（隐式）超时时间。<br><br>参数：<br>`timeout` - (integer) 以毫秒为单位的超时值。|
|`collectPerfEntries(mark)`|收集性能条目，以便通过 `getResult()` 方法获取。<br><br>参数：<br>`mark` - (string, optional) 性能快照标记。|
|`getRawPerfEntries()`|返回一个性能条目对象数组。|
|`getResult()`|返回一个 [`Result`](#result) 对象，其中包含浏览器会话统计信息（错误信息、性能快照等）。|
|`getError()`|返回一个包含浏览器错误的 `BrowserError` 对象（如果没有浏览器错误，则返回 `null`）。|
|`setError(message)`|设置一条自定义错误消息，以包含在 [`Result`](#result) 对象中。<br><br>参数：<br>`message` - (string) 错误消息。|
|`discardError()`|丢弃将在 [`Result`](#result) 对象中返回的错误。|
|`getAlert()`|返回一个包含浏览器警报的 [`Alert`](#alert) 对象（如果没有浏览器警报，则返回 `null`）。|
|`chromeOptions()`|返回一个包含预定义 Chrome 浏览器选项的 `chromeOptions` 对象。|
|`firefoxOptions()`|返回一个包含预定义 Firefox 浏览器选项的 `firefoxOptions` 对象。|
|`safariOptions()`|返回一个包含预定义 Safari 浏览器选项的 `safariOptions` 对象。|
|`edgeOptions()`|返回一个包含预定义 Edge 浏览器选项的 `edgeOptions` 对象。|
|`switchFrame(target)`|切换到指定的 frame。<br><br>参数：<br>`target` - （浏览器元素或 integer，可选）目标 frame。要按元素选择 frame，请传入该元素。要按索引选择 frame，请传入数字。如果留空，则切换到顶层浏览上下文。|

所有 Browser 方法都可能抛出以下错误：

-   `BrowserError` - 派生自 `Error` 对象；如果 `Browser` 构造函数失败，则会抛出该错误；包含一个额外的 `browser` 属性，其值为抛出此 `BrowserError` 的 `Browser` 对象。
-   `WebdriverError` - 派生自 `BrowserError`；包含与 `BrowserError` 对象相同的属性，用于指示该错误是否是在响应 WebDriver 返回错误时生成的。

[comment]: # ({/4c174987-63b1c0c6})

[comment]: # ({e7ef4e6b-d4cb4fbc})
#### 元素

`Element` 对象由 [`Browser`](#browser) 对象的 `findElement()`/`findElements()` 方法返回，且不能直接构造。

`Element` 对象表示网页中的一个元素，并提供与其交互的方法。

`Element` 对象支持以下方法。

|方法|描述|
|--|--------|
|`getAttribute(name)`|返回元素属性的属性值字符串（如果未找到指定属性，则返回 `null`）。<br><br>参数：<br>`name` - (string) 属性名。|
|`getProperty(name)`|返回元素属性的属性值字符串（如果未找到指定属性，则返回 `null`）。<br><br>参数：<br>`name` - (string) 属性名。|
|`getText()`|返回元素文本的文本值字符串。|
|`click()`|单击元素。|
|`clear()`|清除可编辑元素的内容。|
|`sendKeys(keys)`|发送按键。<br><br>参数：<br>`keys` - (string) 要发送的按键。|

[comment]: # ({/e7ef4e6b-d4cb4fbc})

[comment]: # ({d06955ba-8f51d1aa})
#### Cookie

`Cookie` 对象由 [`Browser`](#browser) 对象的 `getCookies()` 方法返回，并传递给 `addCookie()` 方法。

虽然 `Cookie` 对象没有任何方法，但它可以包含以下属性：

|属性|Type|说明|
|--|--|------|
|name|string|Cookie 的名称。|
|value|string|Cookie 的值。|
|path|string|Cookie 有效的路径。<br>添加 Cookie 时如果省略，默认为 `"/"`。|
|domain|string|Cookie 可见的域。<br>添加 Cookie 时如果省略，默认为会话当前浏览上下文的活动文档的 URL 域。|
|secure|boolean|指示 Cookie 是否为安全 Cookie。<br>添加 Cookie 时如果省略，默认为 `false`。|
|httpOnly|boolean|指示 Cookie 是否仅限 HTTP。<br>添加 Cookie 时如果省略，默认为 `false`。|
|expiry|integer|Cookie 的过期时间（自 Unix 纪元以来的秒数）。添加 Cookie 时如果省略，则不得设置此属性。|
|sameSite|string|Cookie 的 `sameSite` 属性，用于控制 Cookie 是否应限制为第一方或同站点上下文。<br>可设置为 `"Lax"` 或 `"Strict"`。<br>添加 Cookie 时如果省略，默认为 `"None"`。|

[comment]: # ({/d06955ba-8f51d1aa})

[comment]: # ({a5a93a3d-a8d4ccbd})
#### Alert

`Alert`对象表示网页警报，由[`Browser`](#browser)对象的`getAlert()`方法返回，不能直接构造。

`Alert`对象包含具有警报文本的`text`属性（如果没有警报，则为`null`）。

以下方法与`Alert`对象一起使用。

|方法|描述|
|--|--------|
|`accept()`|接受警报。|
|`dismiss()`|关闭警报。|

[comment]: # ({/a5a93a3d-a8d4ccbd})

[comment]: # ({aaeb76e3-54b41590})
#### Result

`Result` 对象包含会话统计信息，并由 [`Browser`](#browser) 对象的 `getResult()` 方法返回。

通常，`Result` 对象会被转换为字符串并由脚本返回，然后通过预处理解析为依赖项监控项值。

虽然 `Result` 对象没有任何方法，但它可以包含以下属性。

|Property|<|<|Type|Description|
|-|-|-|-----|---------------------|
|duration|<|<|string|从会话创建到结果检索之间的会话持续时间。|
|error|<|<|object|错误信息。|
|<|http_status|<|integer|WebDriver 返回的 HTTP 状态（如果没有 WebDriver 错误，则为 0）。|
|^|error_code|<|string|WebDriver 返回的错误（如果没有 WebDriver 错误，则为空字符串）。|
|^|message|<|string|WebDriver 错误消息（如果没有 WebDriver 错误，则为空字符串）。|
|performance_data|<|<|object|性能统计信息。|
|<|summary|<|object|性能摘要。|
|^|<|navigation|object|导航摘要。|
|^|^|resource|object|资源摘要。|
|<|details|<|array of objects|每次可能导致导航的操作后的性能统计信息。|
|^|<|mark|string|*(可选)* 使用 [`collectPerfEntries()`](#browser) 方法指定的性能快照标记。|
|^|^|navigation|object|导航统计信息。|
|^|^|resource|object|此步骤的资源摘要。|
|^|^|user|array of objects|标记/度量类型统计信息数组。|
|<|marks|<|array of objects|已标记的性能快照索引。|
|^|<|name|string|性能快照标记名称。|
|^|^|index|integer|`details` 数组中的性能快照索引。|

[comment]: # ({/aaeb76e3-54b41590})