WebDriver 协议

newSession

New Session 命令在终端节点创建一个新的 WebDriver 会话。如果创建失败，将返回会话未创建错误。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.newSession(capabilities)

参数

名称	类型	详情
capabilities	object	一个 JSON 对象，表示在能力处理算法中最终合并和匹配的一组能力

返回

• <Object> session: 包含 sessionId 和已创建 WebDriver 会话能力的对象。

---

deleteSession

Delete Session 命令关闭与当前会话相关的任何顶级浏览上下文，终止连接，并最终关闭当前会话。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.deleteSession(deleteSessionOpts)

参数

名称	类型	详情
deleteSessionOpts 可选	object	包含 deleteSession 命令选项的对象，例如 { shutdownDriver: boolean }

---

status

Status 命令返回有关远程端是否处于可以创建新会话的状态的信息，并且还可以包含特定于实现的任意元信息。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.status()

示例

examples.js

loading...

View on GitHub

返回

• <Object> status: 包含驱动程序状态的对象。

---

getTimeouts

Get Timeouts 命令获取与当前会话关联的超时持续时间。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getTimeouts()

示例

examples.js

loading...

View on GitHub

返回

• <Object> timeouts: 包含 script、pageLoad 和 implicit 超时持续时间的对象。

---

setTimeouts

Set Timeouts 命令设置与当前会话关联的超时持续时间。可以控制的超时列在下面的会话超时表中。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.setTimeouts(implicit, pageLoad, script)

参数

名称	类型	详情
implicit 可选	number	会话隐式等待超时的整数（毫秒）
pageLoad 可选	number	会话页面加载超时的整数（毫秒）
script 可选	number	会话脚本超时的整数（毫秒）

示例

examples.js

loading...

View on GitHub

---

getUrl

Get Current URL 命令返回当前顶级浏览上下文的 URL。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getUrl()

示例

examples.js

loading...

View on GitHub

返回

• <string> url: 当前顶级浏览上下文活动文档的文档 URL

---

navigateTo

navigateTo (go) 命令用于使用户代理导航当前顶级浏览上下文到新位置。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：url。建议使用此命令替代。

用法

browser.navigateTo(url)

参数

名称	类型	详情
url	string	表示绝对 URL 的字符串（以 http(s) 开头），可能包含片段（#...），也可能是本地方案（about: 等）

示例

examples.js

loading...

View on GitHub

---

back

Back 命令使浏览器在当前顶级浏览上下文的联合会话历史记录中后退一步。这相当于在浏览器 chrome 中按下后退按钮或调用 window.history.back。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.back()

示例

examples.js

loading...

View on GitHub

---

forward

Forward 命令使浏览器在当前顶级浏览上下文的联合会话历史记录中前进一步。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.forward()

示例

examples.js

loading...

View on GitHub

---

refresh

Refresh 命令使浏览器重新加载当前顶级浏览上下文中的页面。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.refresh()

示例

examples.js

loading...

View on GitHub

---

getTitle

Get Title 命令返回当前顶级浏览上下文的文档标题，相当于调用 document.title。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getTitle()

示例

examples.js

loading...

View on GitHub

返回

• <string> title: 返回一个字符串，与当前顶级浏览上下文的 document.title 相同。

---

getWindowHandle

Get Window Handle 命令返回当前顶级浏览上下文的窗口句柄。它可以作为 Switch To Window 的参数。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getWindowHandle()

示例

examples.js

loading...

View on GitHub

返回

• <string> handle: 返回一个字符串，它是当前顶级浏览上下文的窗口句柄。

---

closeWindow

Close Window 命令关闭当前顶级浏览上下文。完成后，如果没有更多开放的顶级浏览上下文，WebDriver 会话本身将关闭。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.closeWindow()

示例

examples.js

loading...

View on GitHub

---

switchToWindow

Switch To Window 命令用于为当前会话选择当前顶级浏览上下文，即将用于处理命令的上下文。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：switchWindow。建议使用此命令替代。

用法

browser.switchToWindow(handle)

参数

名称	类型	详情
handle	string	表示窗口句柄的字符串，应该是在调用 getWindowHandles 时返回的字符串之一

示例

examples.js

loading...

View on GitHub

---

createWindow

创建新的顶级浏览上下文。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.createWindow(type)

参数

名称	类型	详情
type	string	如果新创建的窗口与当前浏览上下文共享一个操作系统级别的窗口，则设置为 'tab'，否则设置为 'window'。

示例

examples.js

loading...

View on GitHub

返回

• <Object> window: 新窗口对象，包含值为句柄的 'handle' 和值为创建窗口类型的 'type'

---

getWindowHandles

Get Window Handles 命令返回每个打开的顶级浏览上下文的窗口句柄列表。返回窗口句柄的顺序是任意的。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getWindowHandles()

示例

examples.js

loading...

View on GitHub

返回

• <String[]> handles: 窗口句柄列表的数组。

---

printPage

Print Page 命令将文档渲染为分页 PDF 文档。注意: Chrome 目前仅在无头模式下支持此功能，参见 crbug753118)。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.printPage(orientation, scale, background, width, height, top, bottom, left, right, shrinkToFit, pageRanges)

参数

名称	类型	详情
orientation 可选	string	页面方向。默认值：portrait
scale 可选	number	页面缩放。默认值：1
background 可选	boolean	页面背景。默认值：false
width 可选	number	页面宽度，单位厘米。默认值：21.59（来自页面）
height 可选	number	页面高度，单位厘米。默认值：27.94（来自页面）
top 可选	number	页面上边距，单位厘米。默认值：1
bottom 可选	number	页面下边距，单位厘米。默认值：1
left 可选	number	页面左边距，单位厘米。默认值：1
right 可选	number	页面右边距，单位厘米。默认值：1
shrinkToFit 可选	boolean	缩小 PDF 以适应页面。默认值：true
pageRanges 可选	object[]	页面范围。默认值：[]

示例

examples.js

loading...

View on GitHub

返回

• <string> pdf: 分页文档的 base64 编码 PDF 表示。

---

switchToFrame

Switch To Frame 命令用于选择当前顶级浏览上下文或当前浏览上下文的子浏览上下文，作为后续命令的当前浏览上下文。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

警告

此协议命令已弃用
此命令已弃用，我们鼓励大家使用 switchFrame 来切换到框架。更多关于此命令的信息请访问 https://webdriver.io/docs/api/browser/switchFrame

用法

browser.switchToFrame(id)

参数

名称	类型	详情
id	number, object, null	三种可能类型之一：null：表示顶级浏览上下文（即非 iframe），数字，表示对应于框架的窗口对象的索引，使用 findElement 接收的 Element 对象。

示例

examples.js

loading...

View on GitHub

---

switchToParentFrame

Switch to Parent Frame 命令将将来命令的当前浏览上下文设置为当前浏览上下文的父级。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.switchToParentFrame()

示例

examples.js

loading...

View on GitHub

---

getWindowRect

Get Window Rect 命令返回与当前顶级浏览上下文对应的操作系统窗口在屏幕上的大小和位置。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：getWindowSize。建议使用此命令替代。

用法

browser.getWindowRect()

示例

examples.js

loading...

View on GitHub

返回

• <Object> windowRect: "窗口矩形"对象的 JSON 表示。它有 4 个属性：x, y, width 和 height。

---

setWindowRect

Set Window Rect 命令更改与当前顶级浏览上下文对应的操作系统窗口的大小和位置。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：setWindowSize。建议使用此命令替代。

用法

browser.setWindowRect(x, y, width, height)

参数

名称	类型	详情
x	number, null	窗口对象的 screenX 属性
y	number, null	窗口对象的 screenY 属性
width	number, null	顶级浏览上下文的外部尺寸宽度，包括浏览器 chrome 等...
height	number, null	顶级浏览上下文的外部尺寸高度，包括浏览器 chrome 等...

示例

examples.js

loading...

View on GitHub

返回

• <Object> windowRect: 基于新窗口状态的"窗口矩形"对象的 JSON 表示。

---

maximizeWindow

Maximize Window 命令调用窗口管理器特定的"最大化"操作（如果有的话）在包含当前顶级浏览上下文的窗口上。这通常会在不全屏的情况下将窗口增加到最大可用大小。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.maximizeWindow()

示例

examples.js

loading...

View on GitHub

返回

• <Object> windowRect: 基于新窗口状态的"窗口矩形"对象的 JSON 表示。

---

minimizeWindow

Minimize Window 命令调用窗口管理器特定的"最小化"操作（如果有的话）在包含当前顶级浏览上下文的窗口上。这通常会将窗口隐藏在系统托盘中。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.minimizeWindow()

返回

• <Object> windowRect: （新的）当前顶级浏览上下文的"窗口矩形"对象的 JSON 表示。

---

fullscreenWindow

Fullscreen Window 命令调用窗口管理器特定的"全屏"操作（如果有的话）在包含当前顶级浏览上下文的窗口上。这通常会将窗口增加到物理显示器的大小，并可以隐藏工具栏等浏览器 chrome 元素。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.fullscreenWindow()

返回

• <Object> windowRect: （新的）当前顶级浏览上下文的"窗口矩形"对象的 JSON 表示。

---

findElement

Find Element 命令用于在当前浏览上下文中查找可用于未来命令的元素。此命令返回元素的 JSON 表示，可以传递给 $ 命令以将引用转换为扩展的 WebdriverIO 元素。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：$。建议使用此命令替代。

用法

browser.findElement(using, value)

参数

名称	类型	详情
using	string	有效的元素定位策略
value	string	用于查找元素的实际选择器

示例

examples.js

loading...

View on GitHub

返回

• <object> element: 元素对象的 JSON 表示，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

---

findElementFromShadowRoot

Find Element From Shadow Root 命令用于在元素的阴影根中查找可用于未来命令的元素。此命令返回元素的 JSON 表示，可以传递给 $ 命令以将引用转换为扩展的 WebdriverIO 元素。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：shadow$。建议使用此命令替代。

用法

browser.findElementFromShadowRoot(shadowId, using, value)

参数

名称	类型	详情
shadowId	String	阴影根元素的元素 id
using	string	有效的元素定位策略
value	string	用于查找元素的实际选择器

示例

examples.js

loading...

View on GitHub

返回

• <object> element: 元素阴影对象的 JSON 表示，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

---

findElements

Find Elements 命令用于在当前浏览上下文中查找可用于未来命令的元素。此命令返回元素的 JSON 表示数组，可以传递给 $ 命令以将引用转换为扩展的 WebdriverIO 元素（参见 findElement）。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：$$。建议使用此命令替代。

用法

browser.findElements(using, value)

参数

名称	类型	详情
using	string	有效的元素定位策略
value	string	用于查找元素的实际选择器

示例

examples.js

loading...

View on GitHub

返回

• <object[]> elements: 元素对象表示的（可能为空的）JSON 列表，例如 [{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]。

---

findElementsFromShadowRoot

Find Elements 命令用于在元素的阴影根中查找可用于未来命令的元素。此命令返回元素的 JSON 表示数组，可以传递给 $ 命令以将引用转换为扩展的 WebdriverIO 元素（参见 findElement）。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：shadow$$。建议使用此命令替代。

用法

browser.findElementsFromShadowRoot(shadowId, using, value)

参数

名称	类型	详情
shadowId	String	阴影根元素的元素 id
using	string	有效的元素定位策略
value	string	用于查找元素的实际选择器

示例

examples.js

loading...

View on GitHub

返回

• <object[]> elements: 元素对象表示的（可能为空的）JSON 列表，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

---

findElementFromElement

Find Element From Element 命令用于从当前浏览上下文中的网页元素查找可用于未来命令的元素。此命令返回元素的 JSON 表示，可以传递给 $ 命令以将引用转换为扩展的 WebdriverIO 元素（参见 findElement）。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：$。建议使用此命令替代。

用法

browser.findElementFromElement(elementId, using, value)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id
using	string	有效的元素定位策略
value	string	用于查找元素的实际选择器

示例

examples.js

loading...

View on GitHub

返回

• <object> element: 元素对象的 JSON 表示，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

---

findElementsFromElement

Find Elements From Element 命令用于从当前浏览上下文中的网页元素查找可用于未来命令的元素。此命令返回元素的 JSON 表示数组，可以传递给 $ 命令以将引用转换为扩展的 WebdriverIO 元素（参见 findElement）。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：$$。建议使用此命令替代。

用法

browser.findElementsFromElement(elementId, using, value)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id
using	string	有效的元素定位策略
value	string	用于查找元素的实际选择器

示例

examples.js

loading...

View on GitHub

返回

• <object[]> elements: 元素对象表示的（可能为空的）JSON 列表，例如 [{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]。

---

getElementShadowRoot

获取元素的阴影根对象。结果对象可用于使用例如 findElementFromShadowRoots 或 findElementsFromShadowRoots 来获取此阴影根内的元素。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：shadow$。建议使用此命令替代。

用法

browser.getElementShadowRoot(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

返回

• <string> shadowRoot: 元素阴影根的 JSON 表示，例如 { 'shadow-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

---

getActiveElement

Get Active Element 返回当前浏览上下文的文档元素的活动元素。此命令返回元素的 JSON 表示，可以传递给 $ 命令以将引用转换为扩展的 WebdriverIO 元素（参见 findElement）。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getActiveElement()

示例

examples.js

loading...

View on GitHub

返回

• <string> element: 元素对象的 JSON 表示，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

---

isElementSelected

Is Element Selected 确定引用的元素是否被选中。此操作仅对复选框和单选按钮状态的输入元素或选项元素有意义。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：isSelected。建议使用此命令替代。

用法

browser.isElementSelected(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

返回

• <Boolean> isSelected: 基于选中状态的 true 或 false。

---

isElementDisplayed

Is Element Displayed 确定元素的可见性，以人眼感知可见为指导。在这种上下文中，元素的显示性与 visibility 或 display 样式属性无关。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：isDisplayed。建议使用此命令替代。

用法

browser.isElementDisplayed(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

返回

• <Boolean> isDisplayed: 基于可见状态的 true 或 false。

---

getElementAttribute

Get Element Attribute 命令将返回网页元素的属性。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：getAttribute。建议使用此命令替代。

用法

browser.getElementAttribute(elementId, name)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id
name	String	要检索的属性值的名称

示例

examples.js

loading...

View on GitHub

返回

• <string> attribute: 元素的命名属性。

---

getElementProperty

Get Element Property 命令将返回获取元素属性的结果。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：getProperty。建议使用此命令替代。

用法

browser.getElementProperty(elementId, name)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id
name	String	要检索的属性的名称

示例

examples.js

loading...

View on GitHub

返回

• <string> property: 元素的命名属性，通过在元素对象上调用 GetOwnProperty 访问。

---

getElementCSSValue

Get Element CSS Value 命令检索给定网页元素的给定 CSS 属性的计算值。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：getCSSProperty。建议使用此命令替代。

用法

browser.getElementCSSValue(elementId, propertyName)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id
propertyName	String	要检索的 CSS 属性的名称

示例

examples.js

loading...

View on GitHub

返回

• <string> cssValue: 从元素的样式声明中对应于属性名称的参数的计算值（除非文档类型是 xml，在这种情况下，返回值仅为空字符串）。

---

getElementText

Get Element Text 命令旨在返回元素的文本"如呈现"。元素的呈现文本也用于通过链接文本和部分链接文本定位元素。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getElementText(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

返回

• <string> text: 元素的可见文本（包括子元素），遵循 Selenium Atoms 中定义的算法 bot.dom.getVisibleText。

---

getElementTagName

Get Element Tag Name 命令返回给定网页元素的限定元素名称。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：getTagName。建议使用此命令替代。

用法

browser.getElementTagName(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

返回

• <string> text: 元素的 tagName 属性。

---

getElementRect

Get Element Rect 命令返回给定网页元素的尺寸和坐标。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：getSize、getLocation。建议使用这些命令替代。

用法

browser.getElementRect(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

返回

• <Object> elementRect: 表示元素位置和边界矩形的 JSON 对象。

---

isElementEnabled

Is Element Enabled 确定引用的元素是否启用。此操作仅对表单控件有意义。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：isEnabled。建议使用此命令替代。

用法

browser.isElementEnabled(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

返回

• <Boolean> isEnabled: 如果元素在 xml 文档中，或者是禁用的表单控件：false，否则为 true。

---

elementClick

Element Click 命令如果元素尚未可指针交互，则将元素滚动到视图中，并点击其视图中心点。如果元素的中心点被另一个元素遮挡，则返回元素点击被拦截错误。如果元素在视口外，则返回元素不可交互错误。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：click。建议使用此命令替代。

用法

browser.elementClick(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

---

elementClear

Element Clear 命令将可编辑或可重置的元素滚动到视图中，然后尝试清除其选定的文件或文本内容。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：clearValue。建议使用此命令替代。

用法

browser.elementClear(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

示例

examples.js

loading...

View on GitHub

---

elementSendKeys

Element Send Keys 命令将表单控件元素滚动到视图中，然后将提供的键发送到元素。如果元素不可键盘交互，则返回元素不可交互错误。

输入过程中可以通过发送空键（U+E000，NULL）来清除用于输入的键输入状态。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：addValue、setValue。建议使用这些命令替代。

用法

browser.elementSendKeys(elementId, text)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id
text	string	作为击键发送到元素的字符串

示例

examples.js

loading...

View on GitHub

---

getPageSource

Get Page Source 命令返回当前浏览上下文活动文档的 DOM 的字符串序列化。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getPageSource()

示例

examples.js

loading...

View on GitHub

返回

• <string> pageSource: 当前浏览上下文活动文档的 DOM

---

executeScript

Execute Script 命令在当前浏览上下文的上下文中执行 JavaScript 函数并返回函数的返回值。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：execute。建议使用此命令替代。

用法

browser.executeScript(script, args)

参数

名称	类型	详情
script	string	一个字符串，您想要执行的 Javascript 函数体
args	string, object, number, boolean, null, undefined[]	一个 JSON 值数组，这些值将被反序列化并作为参数传递给您的函数

示例

examples.js

loading...

View on GitHub

返回

• <*> result: 您脚本的返回值，您脚本返回的 Promise 的实现，或者您脚本返回的 Promise 拒绝的原因的错误。

---

executeAsyncScript

Execute Async Script 命令使 JavaScript 作为匿名函数执行。与 Execute Script 命令不同，函数的结果被忽略。相反，作为最后一个参数提供了一个附加参数。这是一个函数，当被调用时，将其第一个参数作为响应返回。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

信息

此协议命令嵌入在以下便捷方法中：executeAsync。建议使用此命令替代。

用法

browser.executeAsyncScript(script, args)

参数

名称	类型	详情
script	string	一个字符串，您想要执行的 Javascript 函数体
args	string, object, number, boolean, null, undefined[]	一个 JSON 值数组，这些值将被反序列化并作为参数传递给您的函数

示例

examples.js

loading...

View on GitHub

返回

• <*> result: 您脚本的返回值，您脚本返回的 Promise 的实现，或者您脚本返回的 Promise 拒绝的原因的错误。

---

getAllCookies

Get All Cookies 命令返回与当前浏览上下文的活动文档地址相关的所有 cookie。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getAllCookies()

示例

examples.js

loading...

View on GitHub

返回

• <Object[]> cookies: 序列化 cookie 的列表。每个序列化 cookie 都有一些可能返回也可能不返回的可选字段，除了 name 和 value。

---

addCookie

Add Cookie 命令将单个 cookie 添加到与活动文档地址关联的 cookie 存储中。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.addCookie(cookie)

参数

名称	类型	详情
cookie	object	表示 cookie 的 JSON 对象。它必须至少有 name 和 value 字段，并且可能有更多字段，包括过期时间等

示例

examples.js

loading...

View on GitHub

---

deleteAllCookies

Delete All Cookies 命令允许删除与活动文档地址关联的所有 cookie。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.deleteAllCookies()

示例

examples.js

loading...

View on GitHub

---

getNamedCookie

Get Named Cookie 命令从当前浏览上下文的活动文档的 cookie 存储中的关联 cookie 返回请求名称的 cookie。如果未找到 cookie，则返回无此类 cookie 错误。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getNamedCookie(name)

参数

名称	类型	详情
name	String	要检索的 cookie 的名称

示例

examples.js

loading...

View on GitHub

返回

• <Object> cookie: 一个序列化的 cookie，具有 name 和 value 字段。还有一些可选字段，如 path、domain 和 expiry-time，也可能存在。

---

deleteCookie

Delete Cookie 命令允许您通过参数名称删除单个 cookie，或者如果名称未定义，则删除与活动文档地址关联的所有 cookie。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.deleteCookie(name)

参数

名称	类型	详情
name	String	要删除的 cookie 的名称

示例

examples.js

loading...

View on GitHub

---

performActions

Perform Actions 命令用于执行复杂的用户操作。有关更多详情，请参见规范。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.performActions(actions)

参数

名称	类型	详情
actions	object[]	对象列表，每个对象代表一个输入源及其关联的操作

---

releaseActions

Release Actions 命令用于释放当前按下的所有键和指针按钮。这会导致事件被触发，就好像状态是通过明确的一系列操作释放的一样。它还会清除虚拟设备的所有内部状态。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.releaseActions()

---

dismissAlert

Dismiss Alert 命令在存在简单对话框时将其关闭，否则报错。请求关闭用户提示（可能没有取消按钮）的请求与接受它具有相同的效果。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.dismissAlert()

示例

examples.js

loading...

View on GitHub

---

acceptAlert

Accept Alert 命令在存在简单对话框时接受它，否则报错。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.acceptAlert()

---

getAlertText

Get Alert Text 命令返回当前用户提示的消息。如果没有当前用户提示，它将返回错误。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getAlertText()

示例

examples.js

loading...

View on GitHub

返回

• <string> alertText: 用户提示的消息。

---

sendAlertText

Send Alert Text 命令将 window.prompt 用户提示的文本字段设置为给定值。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.sendAlertText(text)

参数

名称	类型	详情
text	string	设置提示的字符串

---

takeScreenshot

Take Screenshot 命令拍摄顶级浏览上下文视口的屏幕截图。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.takeScreenshot()

返回

• <string> screenshot: 包含初始视口屏幕截图的 base64 编码 PNG 图像数据。

---

takeElementScreenshot

Take Element Screenshot 命令拍摄元素边界矩形所包含的可见区域的屏幕截图。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.takeElementScreenshot(elementId, scroll)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id
scroll 可选	boolean	将元素滚动到视图中。默认值：true

返回

• <string> screenshot: 包含元素边界矩形可见区域的屏幕截图的 base64 编码 PNG 图像数据，在将其滚动到视图中后。

---

getElementComputedRole

获取元素的计算 WAI-ARIA 角色。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getElementComputedRole(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

返回

• <string> role: 计算元素的 WAI-ARIA 角色的结果。

---

getElementComputedLabel

获取元素的可访问名称。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getElementComputedLabel(elementId)

参数

名称	类型	详情
elementId	String	在先前调用 Find Element(s) 时返回的元素 id

返回

• <string> label: 元素的可访问名称和描述计算的结果。

---

setPermissions

模拟用户对 PermissionDescriptor 的权限状态的修改。注意: 此功能尚未在所有浏览器中实现。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.setPermissions(descriptor, state, oneRealm)

参数

名称	类型	详情
descriptor	object	每个强大功能都有一个或多个方面，网站可以请求访问这些方面的权限。为了描述这些方面，每个功能都定义了 PermissionDescriptor 的子类型作为其权限描述符类型。注意: 此功能尚未在所有浏览器中实现。
state	string	确定权限是被授予、拒绝还是提示。
oneRealm 可选	boolean	是否将权限应用于所有执行上下文。

示例

// 设置 midi 权限
browser.setPermissions(
  { name: 'midi', sysex: true },
  'granted' // 也可以是 "denied" 或 "prompt"
);

// 设置剪贴板权限
browser.setPermissions({ name: 'clipboard-read' }, 'granted');
// 现在你可以通过以下方式读取剪贴板
const clipboardText = await browser.execute(() => navigator.clipboard.readText());

---

generateTestReport

为测试生成报告。Reporting API 的扩展。注意: 此功能尚未在所有浏览器中实现。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.generateTestReport(message, group)

参数

名称	类型	详情
message	string	在报告中显示的消息。
group 可选	string	指定将报告发送到的端点组。

---

createMockSensor

创建一个模拟传感器来模拟如环境光传感器之类的传感器。注意: 此功能尚未在所有浏览器中实现。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.createMockSensor(mockSensorType, maxSamplingFrequency, minSamplingFrequency)

参数

名称	类型	详情
mockSensorType	string	要模拟的传感器 API 类型，例如 'ambient-light'
maxSamplingFrequency 可选	number	表示频率（Hz）的双精度数，用于设置关联模拟传感器支持的最大采样频率。
minSamplingFrequency 可选	number	表示频率（Hz）的双精度数，用于设置关联模拟传感器支持的最小采样频率。

---

getMockSensor

检索关于给定类型模拟传感器的信息。注意: 此功能尚未在所有浏览器中实现。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getMockSensor(type)

参数

名称	类型	详情
type	String	要检索信息的模拟传感器类型。

返回

• <object> sensorReading: 模拟传感器读数的值。

---

updateMockSensor

更新模拟传感器类型。注意: 此功能尚未在所有浏览器中实现。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.updateMockSensor(type, mockSensorType, maxSamplingFrequency, minSamplingFrequency)

参数

名称	类型	详情
type	String	要更新信息的模拟传感器类型。
mockSensorType	string	要模拟的传感器 API 类型，例如 'ambient-light'
maxSamplingFrequency 可选	number	表示频率（Hz）的双精度数，用于设置关联模拟传感器支持的最大采样频率。
minSamplingFrequency 可选	number	表示频率（Hz）的双精度数，用于设置关联模拟传感器支持的最小采样频率。

---

deleteMockSensor

Delete Session 命令关闭与当前会话相关的任何顶级浏览上下文，终止连接，并最终关闭当前会话。注意: 此功能尚未在所有浏览器中实现。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.deleteMockSensor(type)

参数

名称	类型	详情
type	String	要删除的模拟传感器类型。

---

setTimeZone

为测试目的模拟时区的更改。注意: 此功能尚未在所有浏览器中实现。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.setTimeZone(time_zone)

参数

名称	类型	详情
time_zone	string	时区名称，例如 Asia/Tokyo

---

addVirtualAuthenticator

创建一个软件虚拟验证器。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.addVirtualAuthenticator(protocol, transport, hasResidentKey, hasUserVerification, isUserConsenting, isUserVerified, extensions, uvm)

参数

名称	类型	详情
protocol 可选	string	有效值：'ctap1/u2f'、'ctap2'、'ctap2_1'。
transport 可选	string	有效值：'usb'、'nfc'、'ble' 或 'internal'。
hasResidentKey 可选	boolean	有效值：true、false。
hasUserVerification 可选	boolean	有效值：true、false。
isUserConsenting 可选	boolean	有效值：true、false。
isUserVerified 可选	boolean	有效值：包含扩展标识符的数组。
extensions 可选	string[]	有效值：最多 3 个用户验证方法条目。
uvm 可选	object[]

返回

• <string> authenticatorId: 返回验证器的字符串 ID。

---

removeVirtualAuthenticator

移除先前创建的虚拟验证器。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.removeVirtualAuthenticator(authenticatorId)

参数

名称	类型	详情
authenticatorId	String	验证器的 id

---

addCredential

将公钥凭证源注入现有的虚拟验证器。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.addCredential(authenticatorId, credentialId, isResidentCredential, rpId, privateKey, userHandle, signCount, largeBlob)

参数

名称	类型	详情
authenticatorId	String	验证器的 ID
credentialId	string	使用 Base64url 编码的凭证 ID。
isResidentCredential	boolean	如果设置为 true，则创建客户端可发现凭证。如果设置为 false，则创建服务器端凭证。
rpId	string	凭证范围的依赖方 ID。
privateKey	string	包含单个私钥的非对称密钥包，符合 [RFC5958]，使用 Base64url 编码。
userHandle	string	与凭证关联的 userHandle，使用 Base64url 编码。此属性可能未定义。
signCount	number	与公钥凭证源关联的签名计数器的初始值。
largeBlob 可选	string	与公钥凭证源关联的大型、每个凭证的 blob，使用 Base64url 编码。此属性可能未定义。

---

getCredentials

为存储在虚拟验证器中的每个公钥凭证源返回一个凭证参数对象，无论它们是使用 Add Credential 还是 navigator.credentials.create() 存储的。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.getCredentials(authenticatorId)

参数

名称	类型	详情
authenticatorId	String	验证器的 id

返回

• <object[]> credentials: 返回凭证数组。

---

removeAllCredentials

移除存储在虚拟验证器上的所有公钥凭证源。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.removeAllCredentials(authenticatorId)

参数

名称	类型	详情
authenticatorId	String	验证器的 id

---

removeCredential

移除存储在虚拟验证器上的公钥凭证源。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.removeCredential(authenticatorId, credentialId)

参数

名称	类型	详情
authenticatorId	String	验证器的 id
credentialId	String	凭证的 id

---

setUserVerified

Set User Verified 扩展命令在虚拟验证器上设置 isUserVerified 属性。

WebDriver 协议命令。更多详情可在官方协议文档中找到。

用法

browser.setUserVerified(authenticatorId)

参数

名称	类型	详情
authenticatorId	String	验证器的 id