跳到主要内容

WebDriver 协议

newSession​

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

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

用法​
browser.newSession(capabilities)
参数​
名称类型详情
capabilitiesobject一个 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...
返回​
  • <Object> status: 包含驱动程序状态的对象。

getTimeouts​

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

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

用法​
browser.getTimeouts()
示例​
examples.js
loading...
返回​
  • <Object> timeouts: 包含 script、pageLoad 和 implicit 超时持续时间的对象。

setTimeouts​

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

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

用法​
browser.setTimeouts(implicit, pageLoad, script)
参数​
名称类型详情
implicit
可选		number会话隐式等待超时的整数（毫秒）
pageLoad
可选		number会话页面加载超时的整数（毫秒）
script
可选		number会话脚本超时的整数（毫秒）
示例​
examples.js
loading...

getUrl​

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

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

用法​
browser.getUrl()
示例​
examples.js
loading...
返回​
  • <string> url: 当前顶级浏览上下文活动文档的文档 URL

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

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

信息

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

用法​
browser.navigateTo(url)
参数​
名称类型详情
urlstring表示绝对 URL 的字符串（以 http(s) 开头），可能包含片段（#...），也可能是本地方案（about: 等）
示例​
examples.js
loading...

back​

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

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

用法​
browser.back()
示例​
examples.js
loading...

forward​

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

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

用法​
browser.forward()
示例​
examples.js
loading...

refresh​

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

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

用法​
browser.refresh()
示例​
examples.js
loading...

getTitle​

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

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

用法​
browser.getTitle()
示例​
examples.js
loading...
返回​
  • <string> title: 返回一个字符串，与当前顶级浏览上下文的 document.title 相同。

getWindowHandle​

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

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

用法​
browser.getWindowHandle()
示例​
examples.js
loading...
返回​
  • <string> handle: 返回一个字符串，它是当前顶级浏览上下文的窗口句柄。

closeWindow​

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

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

用法​
browser.closeWindow()
示例​
examples.js
loading...

switchToWindow​

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

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

信息

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

用法​
browser.switchToWindow(handle)
参数​
名称类型详情
handlestring表示窗口句柄的字符串，应该是在调用 getWindowHandles 时返回的字符串之一
示例​
examples.js
loading...

createWindow​

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

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

用法​
browser.createWindow(type)
参数​
名称类型详情
typestring如果新创建的窗口与当前浏览上下文共享一个操作系统级别的窗口，则设置为 'tab'，否则设置为 'window'。
示例​
examples.js
loading...
返回​
  • <Object> window: 新窗口对象，包含值为句柄的 'handle' 和值为创建窗口类型的 'type'

getWindowHandles​

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

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

用法​
browser.getWindowHandles()
示例​
examples.js
loading...
返回​
  • <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...
返回​
  • <string> pdf: 分页文档的 base64 编码 PDF 表示。

switchToFrame​

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

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

警告

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

用法​
browser.switchToFrame(id)
参数​
名称类型详情
idnumber, object, null三种可能类型之一：null：表示顶级浏览上下文（即非 iframe），数字，表示对应于框架的窗口对象的索引，使用 findElement 接收的 Element 对象。
示例​
examples.js
loading...

switchToParentFrame​

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

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

用法​
browser.switchToParentFrame()
示例​
examples.js
loading...

getWindowRect​

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

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

信息

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

用法​
browser.getWindowRect()
示例​
examples.js
loading...
返回​
  • <Object> windowRect: "窗口矩形"对象的 JSON 表示。它有 4 个属性：x, y, width 和 height。

setWindowRect​

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

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

信息

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

用法​
browser.setWindowRect(x, y, width, height)
参数​
名称类型详情
xnumber, null窗口对象的 screenX 属性
ynumber, null窗口对象的 screenY 属性
widthnumber, null顶级浏览上下文的外部尺寸宽度，包括浏览器 chrome 等...
heightnumber, null顶级浏览上下文的外部尺寸高度，包括浏览器 chrome 等...
示例​
examples.js
loading...
返回​
  • <Object> windowRect: 基于新窗口状态的"窗口矩形"对象的 JSON 表示。

maximizeWindow​

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

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

用法​
browser.maximizeWindow()
示例​
examples.js
loading...
返回​
  • <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)
参数​
名称类型详情
usingstring有效的元素定位策略
valuestring用于查找元素的实际选择器
示例​
examples.js
loading...
返回​
  • <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)
参数​
名称类型详情
shadowIdString阴影根元素的元素 id
usingstring有效的元素定位策略
valuestring用于查找元素的实际选择器
示例​
examples.js
loading...
返回​
  • <object> element: 元素阴影对象的 JSON 表示，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

findElements​

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

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

信息

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

用法​
browser.findElements(using, value)
参数​
名称类型详情
usingstring有效的元素定位策略
valuestring用于查找元素的实际选择器
示例​
examples.js
loading...
返回​
  • <object[]> elements: 元素对象表示的（可能为空的）JSON 列表，例如 [{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]。

findElementsFromShadowRoot​

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

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

信息

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

用法​
browser.findElementsFromShadowRoot(shadowId, using, value)
参数​
名称类型详情
shadowIdString阴影根元素的元素 id
usingstring有效的元素定位策略
valuestring用于查找元素的实际选择器
示例​
examples.js
loading...
返回​
  • <object[]> elements: 元素对象表示的（可能为空的）JSON 列表，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

findElementFromElement​

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

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

信息

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

用法​
browser.findElementFromElement(elementId, using, value)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
usingstring有效的元素定位策略
valuestring用于查找元素的实际选择器
示例​
examples.js
loading...
返回​
  • <object> element: 元素对象的 JSON 表示，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

findElementsFromElement​

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

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

信息

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

用法​
browser.findElementsFromElement(elementId, using, value)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
usingstring有效的元素定位策略
valuestring用于查找元素的实际选择器
示例​
examples.js
loading...
返回​
  • <object[]> elements: 元素对象表示的（可能为空的）JSON 列表，例如 [{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]。

getElementShadowRoot​

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

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

信息

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

用法​
browser.getElementShadowRoot(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...
返回​
  • <string> shadowRoot: 元素阴影根的 JSON 表示，例如 { 'shadow-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

getActiveElement​

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

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

用法​
browser.getActiveElement()
示例​
examples.js
loading...
返回​
  • <string> element: 元素对象的 JSON 表示，例如 { 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。

isElementSelected​

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

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

信息

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

用法​
browser.isElementSelected(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...
返回​
  • <Boolean> isSelected: 基于选中状态的 true 或 false。

isElementDisplayed​

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

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

信息

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

用法​
browser.isElementDisplayed(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...
返回​
  • <Boolean> isDisplayed: 基于可见状态的 true 或 false。

getElementAttribute​

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

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

信息

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

用法​
browser.getElementAttribute(elementId, name)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
nameString要检索的属性值的名称
示例​
examples.js
loading...
返回​
  • <string> attribute: 元素的命名属性。

getElementProperty​

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

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

信息

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

用法​
browser.getElementProperty(elementId, name)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
nameString要检索的属性的名称
示例​
examples.js
loading...
返回​
  • <string> property: 元素的命名属性，通过在元素对象上调用 GetOwnProperty 访问。

getElementCSSValue​

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

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

信息

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

用法​
browser.getElementCSSValue(elementId, propertyName)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
propertyNameString要检索的 CSS 属性的名称
示例​
examples.js
loading...
返回​
  • <string> cssValue: 从元素的样式声明中对应于属性名称的参数的计算值（除非文档类型是 xml，在这种情况下，返回值仅为空字符串）。

getElementText​

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

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

用法​
browser.getElementText(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...
返回​
  • <string> text: 元素的可见文本（包括子元素），遵循 Selenium Atoms 中定义的算法 bot.dom.getVisibleText。

getElementTagName​

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

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

信息

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

用法​
browser.getElementTagName(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...
返回​
  • <string> text: 元素的 tagName 属性。

getElementRect​

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

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

信息

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

用法​
browser.getElementRect(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...
返回​
  • <Object> elementRect: 表示元素位置和边界矩形的 JSON 对象。

isElementEnabled​

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

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

信息

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

用法​
browser.isElementEnabled(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...
返回​
  • <Boolean> isEnabled: 如果元素在 xml 文档中，或者是禁用的表单控件：false，否则为 true。

elementClick​

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

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

信息

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

用法​
browser.elementClick(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...

elementClear​

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

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

信息

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

用法​
browser.elementClear(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
示例​
examples.js
loading...

elementSendKeys​

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

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

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

信息

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

用法​
browser.elementSendKeys(elementId, text)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
textstring作为击键发送到元素的字符串
示例​
examples.js
loading...

getPageSource​

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

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

用法​
browser.getPageSource()
示例​
examples.js
loading...
返回​
  • <string> pageSource: 当前浏览上下文活动文档的 DOM

executeScript​

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

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

信息

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

用法​
browser.executeScript(script, args)
参数​
名称类型详情
scriptstring一个字符串，您想要执行的 Javascript 函数体
argsstring, object, number, boolean, null, undefined[]一个 JSON 值数组，这些值将被反序列化并作为参数传递给您的函数
示例​
examples.js
loading...
返回​
  • <*> result: 您脚本的返回值，您脚本返回的 Promise 的实现，或者您脚本返回的 Promise 拒绝的原因的错误。

executeAsyncScript​

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

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

信息

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

用法​
browser.executeAsyncScript(script, args)
参数​
名称类型详情
scriptstring一个字符串，您想要执行的 Javascript 函数体
argsstring, object, number, boolean, null, undefined[]一个 JSON 值数组，这些值将被反序列化并作为参数传递给您的函数
示例​
examples.js
loading...
返回​
  • <*> result: 您脚本的返回值，您脚本返回的 Promise 的实现，或者您脚本返回的 Promise 拒绝的原因的错误。

getAllCookies​

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

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

用法​
browser.getAllCookies()
示例​
examples.js
loading...
返回​
  • <Object[]> cookies: 序列化 cookie 的列表。每个序列化 cookie 都有一些可能返回也可能不返回的可选字段，除了 name 和 value。

addCookie​

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

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

用法​
browser.addCookie(cookie)
参数​
名称类型详情
cookieobject表示 cookie 的 JSON 对象。它必须至少有 name 和 value 字段，并且可能有更多字段，包括过期时间等
示例​
examples.js
loading...

deleteAllCookies​

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

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

用法​
browser.deleteAllCookies()
示例​
examples.js
loading...

getNamedCookie​

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

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

用法​
browser.getNamedCookie(name)
参数​
名称类型详情
nameString要检索的 cookie 的名称
示例​
examples.js
loading...
返回​
  • <Object> cookie: 一个序列化的 cookie，具有 name 和 value 字段。还有一些可选字段，如 path、domain 和 expiry-time，也可能存在。

deleteCookie​

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

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

用法​
browser.deleteCookie(name)
参数​
名称类型详情
nameString要删除的 cookie 的名称
示例​
examples.js
loading...

performActions​

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

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

用法​
browser.performActions(actions)
参数​
名称类型详情
actionsobject[]对象列表，每个对象代表一个输入源及其关联的操作

releaseActions​

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

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

用法​
browser.releaseActions()

dismissAlert​

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

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

用法​
browser.dismissAlert()
示例​
examples.js
loading...

acceptAlert​

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

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

用法​
browser.acceptAlert()

getAlertText​

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

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

用法​
browser.getAlertText()
示例​
examples.js
loading...
返回​
  • <string> alertText: 用户提示的消息。

sendAlertText​

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

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

用法​
browser.sendAlertText(text)
参数​
名称类型详情
textstring设置提示的字符串

takeScreenshot​

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

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

用法​
browser.takeScreenshot()
返回​
  • <string> screenshot: 包含初始视口屏幕截图的 base64 编码 PNG 图像数据。

takeElementScreenshot​

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

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

用法​
browser.takeElementScreenshot(elementId, scroll)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
scroll
可选		boolean将元素滚动到视图中。默认值：true
返回​
  • <string> screenshot: 包含元素边界矩形可见区域的屏幕截图的 base64 编码 PNG 图像数据，在将其滚动到视图中后。

getElementComputedRole​

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

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

用法​
browser.getElementComputedRole(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
返回​
  • <string> role: 计算元素的 WAI-ARIA 角色的结果。

getElementComputedLabel​

获取元素的可访问名称。

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

用法​
browser.getElementComputedLabel(elementId)
参数​
名称类型详情
elementIdString在先前调用 Find Element(s) 时返回的元素 id
返回​
  • <string> label: 元素的可访问名称和描述计算的结果。

setPermissions​

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

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

用法​
browser.setPermissions(descriptor, state, oneRealm)
参数​
名称类型详情
descriptorobject每个强大功能都有一个或多个方面，网站可以请求访问这些方面的权限。为了描述这些方面，每个功能都定义了 PermissionDescriptor 的子类型作为其权限描述符类型。注意: 此功能尚未在所有浏览器中实现。
statestring确定权限是被授予、拒绝还是提示。
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)
参数​
名称类型详情
messagestring在报告中显示的消息。
group
可选		string指定将报告发送到的端点组。

createMockSensor​

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

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

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

getMockSensor​

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

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

用法​
browser.getMockSensor(type)
参数​
名称类型详情
typeString要检索信息的模拟传感器类型。
返回​
  • <object> sensorReading: 模拟传感器读数的值。

updateMockSensor​

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

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

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

deleteMockSensor​

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

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

用法​
browser.deleteMockSensor(type)
参数​
名称类型详情
typeString要删除的模拟传感器类型。

setTimeZone​

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

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

用法​
browser.setTimeZone(time_zone)
参数​
名称类型详情
time_zonestring时区名称，例如 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)
参数​
名称类型详情
authenticatorIdString验证器的 id

addCredential​

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

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

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

getCredentials​

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

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

用法​
browser.getCredentials(authenticatorId)
参数​
名称类型详情
authenticatorIdString验证器的 id
返回​
  • <object[]> credentials: 返回凭证数组。

removeAllCredentials​

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

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

用法​
browser.removeAllCredentials(authenticatorId)
参数​
名称类型详情
authenticatorIdString验证器的 id

removeCredential​

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

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

用法​
browser.removeCredential(authenticatorId, credentialId)
参数​
名称类型详情
authenticatorIdString验证器的 id
credentialIdString凭证的 id

setUserVerified​

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

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

用法​
browser.setUserVerified(authenticatorId)
参数​
名称类型详情
authenticatorIdString验证器的 id

Welcome! How can I help?

WebdriverIO AI Copilot