Documentation

Table of Contents

2 浏览器项目 JavaScript 对象
- 概述
- 浏览器
- Element
- Cookie
- Alert
- Result

2 浏览器项目 JavaScript 对象

概述

本节描述了使用Duktape实现的Zabbix对JavaScript语言的扩展，用于在浏览器项目脚本中使用。这些扩展补充了附加JavaScript对象页面中描述的JavaScript对象。

浏览器

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

要构建一个 Browser 对象，使用 new Browser(options) 语法。 options (JSON 对象) 参数指定浏览器选项，通常是 WebDriver 选项方法的结果（例如，Browser.chromeOptions()）。

以下方法适用于 Browser 对象。

方法	描述
`navigate(url)`	导航到指定的 URL。参数： `url` - (字符串) 要导航到的 URL。
`getUrl()`	返回打开页面 URL 的字符串。
`getPageSource()`	返回打开页面源代码的字符串。
`findElement(strategy, selector)`	返回包含打开页面中一个元素的 `Element` 对象（如果没有任何元素与 `strategy` 和 `selector` 匹配，则返回 `null`）。参数： `strategy` - (字符串，CSS 选择器/链接文本/部分链接文本/标签名称/Xpath) 定位策略； `selector` - (字符串) 使用指定定位策略的元素选择器。
`findElements(strategy, target)`	返回包含打开页面中多个元素的 `Element` 对象数组（如果没有元素与定位策略和目标匹配，则返回空数组）。参数： `strategy` - (字符串，CSS 选择器/链接文本/部分链接文本/标签名称/Xpath) 定位策略； `target` - (字符串) 使用指定定位策略的元素选择器。
`getCookies()`	返回一个由 `Cookie` 对象组成的数组。
`addCookie(cookie)`	设置 Cookie。参数： `cookie` - (`Cookie` 对象) 要设置的 Cookie。
`getScreenshot()`	返回表示浏览器视口图像的 Base64 编码字符串。
`setScreenSize(x,y)`	设置浏览器视口大小。参数： `x` - (字符串) 高度（像素）； `y` - (字符串) 宽度（像素）。
`setScriptTimeout(timeout)`	设置脚本加载超时时间。参数： `timeout` - (整数) 以毫秒为单位的超时值。
`setSessionTimeout(timeout)`	设置会话（页面加载）超时时间。参数： `timeout` - (整数) 以毫秒为单位的超时值。
`setElementWaitTimeout(timeout)`	设置元素定位策略（隐式）超时时间。参数： `timeout` - (整数) 以毫秒为单位的超时值。
`collectPerfEntries(mark)`	收集性能条目，以便使用 `getResult()` 方法检索。参数： `mark` - (字符串，可选) 性能快照标记。
`getRawPerfEntries()`	返回一个由性能条目对象组成的数组。
`getResult()`	返回一个包含浏览器会话统计信息（错误信息、性能快照等）的 `Result` 对象。
`getError()`	返回一个包含浏览器错误的 `BrowserError` 对象（如果没有浏览器错误，则返回 `null`）。
`setError(message)`	设置要在 `Result` 对象中包含的自定义错误消息。参数： `message` - (字符串) 错误消息。
`discardError()`	丢弃将在 `Result` 对象中返回的错误。
`getAlert()`	返回包含浏览器警告的 `Alert` 对象（如果没有浏览器警告，则返回 `null`）。
`chromeOptions()`	返回一个包含预定义 Chrome 浏览器选项的 `chromeOptions` 对象。
`firefoxOptions()`	返回一个包含预定义 Firefox 浏览器选项的 `firefoxOptions` 对象。
`safariOptions()`	返回一个包含预定义 Safari 浏览器选项的 `safariOptions` 对象。
`edgeOptions()`	返回一个包含预定义 Edge 浏览器选项的 `edgeOptions` 对象。
`switchFrame(target)`	切换到指定的框架。自版本 7.0.4 起支持。参数： `target` - (浏览器元素或整数，可选) 目标框架。要通过元素选择框架，传递元素。要通过索引选择框架，传递数字。如果留空，将切换到顶级浏览上下文。

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

BrowserError - 从 Error 对象派生，如果 Browser 构造函数失败则抛出；包含一个额外的 browser 属性，其中包含引发此 BrowserError 的 Browser 对象。
WebdriverError - 从 BrowserError 派生；包含与 BrowserError 对象相同的属性，指示错误是否是在响应 WebDriver 响应中的错误时生成的。

Element

Element对象由Browser对象的findElement()/findElements()方法返回，不能直接构造。

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

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

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

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

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

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

Alert

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

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

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

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

Result

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

通常，Result对象被字符串化并从脚本返回，然后通过预处理解析为依赖项值。

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

属性	类型	描述
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()`方法一起指定的性能快照标记。
navigation	object	导航统计信息。
resource	object	此步骤的资源摘要。
user	array of objects	标记/测量类型统计信息数组。
marks	array of objects	标记的性能快照索引。
name	string	性能快照标记名称。
index	integer	详细信息数组中的性能快照索引。