WebDriver 協議
newSession
New Session 命令會使用端點節點建立新的 WebDriver 會話。如果建立失敗，則會傳回「會話未建立」錯誤。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.newSession(capabilities)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
capabilities | 物件 | 一個 JSON 物件，是在功能處理演算法中最終合併和匹配的功能集 |
傳回
- <物件>
session：包含已建立 WebDriver 會話的 sessionId 和功能物件。
deleteSession
Delete Session 命令會關閉與目前會話相關聯的任何最上層瀏覽上下文，終止連線，最後關閉目前會話。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.deleteSession(deleteSessionOpts)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
deleteSessionOpts可選 | 物件 | 包含 deleteSession 命令選項的物件，例如 { shutdownDriver: boolean } |
status
Status 命令會傳回遠端端點是否處於可以建立新會話的狀態的資訊，並且還可以包含特定於實作的任意元資訊。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.status()
範例
loading...
傳回
- <物件>
status：包含驅動程式狀態的物件。
getTimeouts
Get Timeouts 命令會取得與目前會話相關聯的逾時持續時間。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.getTimeouts()
範例
loading...
傳回
- <物件>
timeouts：包含script、pageLoad和implicit逾時的逾時持續時間的物件。
setTimeouts
Set Timeouts 命令會設定與目前會話相關聯的逾時持續時間。可以控制的逾時會在下面的會話逾時表格中列出。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.setTimeouts(implicit, pageLoad, script)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
implicit可選 | 數字 | 會話隱式等待逾時的毫秒整數 |
pageLoad可選 | 數字 | 會話頁面載入逾時的毫秒整數 |
script可選 | 數字 | 會話指令碼逾時的毫秒整數 |
範例
loading...
getUrl
Get Current URL 命令會傳回目前最上層瀏覽上下文的 URL。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.getUrl()
範例
loading...
傳回
- <字串>
url：目前最上層瀏覽上下文的作用中文件的文件 URL
navigateTo
navigateTo (go) 命令用於讓使用者代理程式將目前最上層瀏覽上下文導覽至新的位置。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
此協議命令內嵌於以下方便的方法中：url。建議改用此命令。
用法
browser.navigateTo(url)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
url | 字串 | 表示絕對 URL (以 http(s) 開頭) 的字串，可能包含片段 (#...)，也可能是本機配置 (about: 等) |
範例
loading...
back
Back 命令會導致瀏覽器在目前最上層瀏覽上下文的聯合會話歷史記錄中向後移動一步。這相當於按下瀏覽器 chrome 中的「上一頁」按鈕或呼叫 window.history.back。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.back()
範例
loading...
forward
Forward 命令會導致瀏覽器在目前最上層瀏覽上下文的聯合會話歷史記錄中向前移動一步。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.forward()
範例
loading...
refresh
Refresh 命令會導致瀏覽器在目前最上層瀏覽上下文中重新載入頁面。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.refresh()
範例
loading...
getTitle
Get Title 命令會傳回目前最上層瀏覽上下文的文件標題，相當於呼叫 document.title。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.getTitle()
範例
loading...
傳回
- <字串>
title：傳回的字串與目前最上層瀏覽上下文的document.title相同。
getWindowHandle
Get Window Handle 命令會傳回目前最上層瀏覽上下文的視窗控制代碼。它可以作為「切換到視窗」的引數。
WebDriver 協議命令。更多詳細資訊可以在官方協議文件中找到。
用法
browser.getWindowHandle()
範例
loading...
回傳值
- <string>
handle： 回傳一個字串，該字串為目前最上層瀏覽環境的視窗控制代碼。
closeWindow
關閉視窗命令會關閉目前最上層的瀏覽環境。一旦完成，如果沒有其他最上層瀏覽環境開啟，WebDriver 會話本身也會關閉。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.closeWindow()
範例
loading...
switchToWindow
切換視窗命令用於選取目前會話的當前最上層瀏覽環境，也就是將用於處理命令的瀏覽環境。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
此協定命令嵌入於以下便利方法中：switchWindow。建議改用此命令。
用法
browser.switchToWindow(handle)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
handle | 字串 | 一個代表視窗控制代碼的字串，應為呼叫 getWindowHandles 時回傳的其中一個字串 |
範例
loading...
createWindow
建立新的最上層瀏覽環境。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.createWindow(type)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
type | 字串 | 如果新建立的視窗與目前的瀏覽環境共用作業系統層級的視窗，請設為 'tab'，否則設為 'window'。 |
範例
loading...
回傳值
- <Object>
window： 新視窗物件，包含 'handle'（值為控制代碼）和 'type'（值為建立的視窗類型）
getWindowHandles
取得視窗控制代碼命令會回傳每個開啟的最上層瀏覽環境的視窗控制代碼清單。回傳視窗控制代碼的順序是任意的。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getWindowHandles()
範例
loading...
回傳值
- <String[]>
handles： 包含視窗控制代碼清單的陣列。
printPage
列印頁面命令會將文件渲染為分頁 PDF 文件。注意： Chrome 目前僅在無頭模式中支援此功能，請參閱 crbug753118）。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.printPage(orientation, scale, background, width, height, top, bottom, left, right, shrinkToFit, pageRanges)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
orientation可選 | 字串 | 頁面方向。預設值：portrait |
scale可選 | 數字 | 頁面縮放比例。預設值：1 |
background可選 | 布林值 | 頁面背景。預設值：false |
width可選 | 數字 | 頁面寬度（公分）。預設值：取自頁面的 21.59 |
height可選 | 數字 | 頁面高度（公分）。預設值：取自頁面的 27.94 |
top可選 | 數字 | 頁面頂部邊界（公分）。預設值：1 |
bottom可選 | 數字 | 頁面底部邊界（公分）。預設值：1 |
left可選 | 數字 | 頁面左邊界（公分）。預設值：1 |
right可選 | 數字 | 頁面右邊界（公分）。預設值：1 |
shrinkToFit可選 | 布林值 | 將 PDF 縮小以符合頁面。預設值：true |
pageRanges可選 | 物件 [] | 頁面範圍。預設值 [] |
範例
loading...
回傳值
- <string>
pdf： 分頁文件的 base64 編碼 PDF 表示法。
switchToFrame
切換框架命令用於選取目前最上層瀏覽環境或目前瀏覽環境的子瀏覽環境，以作為後續命令的目前瀏覽環境。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
此協定命令已過時
此命令已過時，我們鼓勵大家改用 switchFrame 來切換框架。請參閱 https://webdriverio.dev.org.tw/docs/api/browser/switchFrame 以取得更多關於此命令的資訊。
用法
browser.switchToFrame(id)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
id | 數字、物件、空值 | 三種可能的類型之一：空值：表示最上層瀏覽環境（也就是說，不是 iframe），數字：表示對應於框架的視窗物件索引，或使用 findElement 收到的元素物件。 |
範例
loading...
switchToParentFrame
切換到父框架命令會將未來命令的目前瀏覽環境設定為目前瀏覽環境的父環境。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.switchToParentFrame()
範例
loading...
getWindowRect
取得視窗矩形命令會回傳對應於目前最上層瀏覽環境的作業系統視窗在螢幕上的大小和位置。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
此協定命令嵌入於以下便利方法中：getWindowSize。建議改用此命令。
用法
browser.getWindowRect()
範例
loading...
回傳值
- <Object>
windowRect： 「視窗矩形」物件的 JSON 表示法。此物件有 4 個屬性：x、y、width和height。
setWindowRect
設定視窗矩形命令會變更對應於目前最上層瀏覽環境的作業系統視窗的大小和位置。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
此協定命令嵌入於以下便利方法中：setWindowSize。建議改用此命令。
用法
browser.setWindowRect(x, y, width, height)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
x | 數字、空值 | 視窗物件的 screenX 屬性 |
y | 數字、空值 | 視窗物件的 screenY 屬性 |
width | 數字、空值 | 最上層瀏覽環境外部尺寸的寬度，包含瀏覽器框架等... |
height | 數字、空值 | 最上層瀏覽環境外部尺寸的高度，包含瀏覽器框架等... |
範例
loading...
回傳值
- <Object>
windowRect： 根據新視窗狀態的「視窗矩形」物件 JSON 表示法。
maximizeWindow
最大化視窗命令會在包含目前最上層瀏覽環境的視窗上，叫用視窗管理員特定的「最大化」操作（如果有的話）。這通常會將視窗增大到最大可用大小，而不會進入全螢幕。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.maximizeWindow()
範例
loading...
回傳值
- <Object>
windowRect： 根據新視窗狀態的「視窗矩形」物件 JSON 表示法。
minimizeWindow
最小化視窗命令會在包含目前最上層瀏覽環境的視窗上，叫用視窗管理員特定的「最小化」操作（如果有的話）。這通常會將視窗隱藏在系統匣中。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.minimizeWindow()
回傳值
- <Object>
windowRect： （新的）目前最上層瀏覽環境的「視窗矩形」物件 JSON 表示法。
fullscreenWindow
全螢幕視窗命令會在包含目前最上層瀏覽環境的視窗上，叫用視窗管理員特定的「全螢幕」操作（如果有的話）。這通常會將視窗增大到實體顯示器的大小，並且可以隱藏瀏覽器框架元素，例如工具列。
WebDriver 協議指令。更多詳細資訊請參閱官方協議文件。
用法
browser.fullscreenWindow()
回傳
- <Object>
windowRect： （新的）目前最上層瀏覽環境的「視窗矩形」物件 JSON 表示法。
findElement
Find Element 指令用於在目前的瀏覽環境中尋找一個元素，以便用於後續指令。此指令會回傳元素的 JSON 表示法，該表示法可傳遞至 $ 指令，以將參照轉換為擴充的 WebdriverIO 元素。
WebDriver 協議指令。更多詳細資訊請參閱官方協議文件。
此協議指令已嵌入在以下方便的方法中：$。建議改用此指令。
用法
browser.findElement(using, value)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
using | 字串 | 有效的元素定位策略 |
value | 字串 | 將用於尋找元素的實際選擇器 |
範例
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)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
shadowId | 字串 | 陰影根元素的元素 ID |
using | 字串 | 有效的元素定位策略 |
value | 字串 | 將用於尋找元素的實際選擇器 |
範例
loading...
回傳
- <object>
element: 元素陰影物件的 JSON 表示法，例如{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。
findElements
Find Elements 指令用於在目前的瀏覽環境中尋找元素，以便用於後續指令。此指令會回傳元素的 JSON 表示法陣列，該陣列可傳遞至 $ 指令，以將參照轉換為擴充的 WebdriverIO 元素（請參閱 findElement）。
WebDriver 協議指令。更多詳細資訊請參閱官方協議文件。
此協議指令已嵌入在以下方便的方法中：$$。建議改用此指令。
用法
browser.findElements(using, value)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
using | 字串 | 有效的元素定位策略 |
value | 字串 | 將用於尋找元素的實際選擇器 |
範例
loading...
回傳
- <object[]>
elements: (可能為空) 元素物件表示法的 JSON 清單，例如[{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]。
findElementsFromShadowRoot
Find Elements 指令用於尋找元素陰影根內的元素，以便用於後續指令。此指令會回傳元素的 JSON 表示法陣列，該陣列可傳遞至 $ 指令，以將參照轉換為擴充的 WebdriverIO 元素（請參閱 findElement）。
WebDriver 協議指令。更多詳細資訊請參閱官方協議文件。
此協議指令已嵌入在以下方便的方法中：shadow$$。建議改用此指令。
用法
browser.findElementsFromShadowRoot(shadowId, using, value)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
shadowId | 字串 | 陰影根元素的元素 ID |
using | 字串 | 有效的元素定位策略 |
value | 字串 | 將用於尋找元素的實際選擇器 |
範例
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)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
using | 字串 | 有效的元素定位策略 |
value | 字串 | 將用於尋找元素的實際選擇器 |
範例
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)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
using | 字串 | 有效的元素定位策略 |
value | 字串 | 將用於尋找元素的實際選擇器 |
範例
loading...
回傳
- <object[]>
elements: (可能為空) 元素物件表示法的 JSON 清單，例如[{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }]。
getElementShadowRoot
取得元素的陰影根物件。結果物件可用於使用例如 findElementFromShadowRoots 或 findElementsFromShadowRoots 等指令，擷取此陰影根內的元素。
WebDriver 協議指令。更多詳細資訊請參閱官方協議文件。
此協議指令已嵌入在以下方便的方法中：shadow$。建議改用此指令。
用法
browser.getElementShadowRoot(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
回傳
- <string>
shadowRoot: 元素陰影根的 JSON 表示法，例如{ 'shadow-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。
getActiveElement
Get Active Element 會回傳目前瀏覽環境的文件元素的活動元素。此指令會回傳元素的 JSON 表示法，該表示法可傳遞至 $ 指令，以將參照轉換為擴充的 WebdriverIO 元素（請參閱 findElement）。
WebDriver 協議指令。更多詳細資訊請參閱官方協議文件。
用法
browser.getActiveElement()
範例
loading...
回傳
- <string>
element: 元素物件的 JSON 表示法，例如{ 'element-6066-11e4-a52e-4f735466cecf': 'ELEMENT_1' }。
isElementSelected
Is Element Selected 會判斷所參照的元素是否已選取。此操作僅在核取方塊和單選按鈕狀態的輸入元素或選項元素上才有意義。
WebDriver 協議指令。更多詳細資訊請參閱官方協議文件。
此協議指令已嵌入在以下方便的方法中：isSelected。建議改用此指令。
用法
browser.isElementSelected(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
回傳
- <Boolean>
isSelected: 根據選取狀態，回傳true或false。
isElementDisplayed
「元素是否顯示」判斷元素的能見度，其標準為人眼感知到的可見性。在此上下文中，元素的顯示與否和 visibility 或 display 樣式屬性無關。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：isDisplayed。建議改用此方法。
用法
browser.isElementDisplayed(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
回傳值
- <布林值>
isDisplayed：根據可見狀態回傳true或false。
getElementAttribute
「取得元素屬性」指令會回傳網頁元素的屬性。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：getAttribute。建議改用此方法。
用法
browser.getElementAttribute(elementId, name)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
name | 字串 | 要檢索的屬性值的名稱 |
範例
loading...
回傳值
- <字串>
attribute：元素的指定屬性。
getElementProperty
「取得元素屬性」指令會回傳取得元素屬性的結果。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：getProperty。建議改用此方法。
用法
browser.getElementProperty(elementId, name)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
name | 字串 | 要檢索的屬性名稱 |
範例
loading...
回傳值
- <字串>
property：元素的指定屬性，透過在元素物件上呼叫 GetOwnProperty 來存取。
getElementCSSValue
「取得元素 CSS 值」指令會檢索指定網頁元素的指定 CSS 屬性的計算值。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：getCSSProperty。建議改用此方法。
用法
browser.getElementCSSValue(elementId, propertyName)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
propertyName | 字串 | 要檢索的 CSS 屬性名稱 |
範例
loading...
回傳值
- <字串>
cssValue：對應於元素樣式宣告中屬性名稱的參數的計算值（除非文件類型為 xml，在這種情況下，回傳值僅為空字串）。
getElementText
「取得元素文字」指令旨在回傳元素「呈現的」文字。元素的呈現文字也用於透過其連結文字和部分連結文字來定位元素。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
用法
browser.getElementText(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
回傳值
- <字串>
text：元素的顯示文字（包括子元素），遵循 Selenium Atoms 中定義的bot.dom.getVisibleText演算法。
getElementTagName
「取得元素標籤名稱」指令會回傳指定網頁元素的合格元素名稱。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：getTagName。建議改用此方法。
用法
browser.getElementTagName(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
回傳值
- <字串>
text：元素的 tagName 屬性。
getElementRect
「取得元素矩形」指令會回傳指定網頁元素的尺寸和座標。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：getSize、getLocation。建議改用這些方法。
用法
browser.getElementRect(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
回傳值
- <物件>
elementRect：一個 JSON 物件，代表元素的位置和邊界矩形。
isElementEnabled
「元素是否啟用」判斷參考的元素是否已啟用。此操作僅適用於表單控制項。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：isEnabled。建議改用此方法。
用法
browser.isElementEnabled(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
回傳值
- <布林值>
isEnabled：如果元素位於 xml 文件中，或是已停用的表單控制項：false，否則為true。
elementClick
「元素點擊」指令會將元素捲動至檢視畫面，如果元素尚未可進行指標互動，則點擊其檢視畫面中的中心點。如果元素的中心點被另一個元素遮蔽，則會回傳元素點擊攔截錯誤。如果元素位於視窗外，則會回傳元素不可互動錯誤。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：click。建議改用此方法。
用法
browser.elementClick(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
elementClear
「元素清除」指令會將可編輯或可重設的元素捲動至檢視畫面，然後嘗試清除其選取的檔案或文字內容。
WebDriver 通訊協定指令。更多詳細資訊請參閱官方通訊協定文件。
此通訊協定指令已嵌入以下方便的方法：clearValue。建議改用此方法。
用法
browser.elementClear(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
範例
loading...
elementSendKeys
「元素發送按鍵」指令會將表單控制項元素捲動至檢視畫面，然後將提供的按鍵發送到該元素。如果元素無法進行鍵盤互動，則會回傳元素不可互動錯誤。
用於輸入的按鍵輸入狀態可能會在「輸入」過程中，透過發送空按鍵 (U+E000 (NULL)) 來清除。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.elementSendKeys(elementId, text)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
text | 字串 | 要傳送至元素的按鍵字串 |
範例
loading...
getPageSource
Get Page Source 命令會傳回目前瀏覽內容活動文件的 DOM 字串序列化。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getPageSource()
範例
loading...
傳回值
- <string>
pageSource: 目前瀏覽內容活動文件的 DOM
executeScript
Execute Script 命令會在目前瀏覽內容的環境中執行 JavaScript 函數，並傳回該函數的傳回值。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
此協定命令已嵌入以下便捷方法中：execute。建議改用此命令。
用法
browser.executeScript(script, args)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
script | 字串 | 一個字串，您要執行的 Javascript 函數主體 |
args | 字串、物件、數字、布林值、null、undefined[] | JSON 值的陣列，這些值將被反序列化並作為引數傳遞給您的函數 |
範例
loading...
傳回值
- <*>
result: 要不是您腳本的傳回值，就是您腳本傳回的 Promise 的實現，或是導致您腳本傳回的 Promise 被拒絕的錯誤。
executeAsyncScript
Execute Async Script 命令會導致 JavaScript 以匿名函數執行。與 Execute Script 命令不同，此函數的結果會被忽略。相反地，會提供一個額外的引數作為函數的最後一個引數。這是一個函數，當被呼叫時，會將其第一個引數作為回應傳回。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
此協定命令已嵌入以下便捷方法中：executeAsync。建議改用此命令。
用法
browser.executeAsyncScript(script, args)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
script | 字串 | 一個字串，您要執行的 Javascript 函數主體 |
args | 字串、物件、數字、布林值、null、undefined[] | JSON 值的陣列，這些值將被反序列化並作為引數傳遞給您的函數 |
範例
loading...
傳回值
- <*>
result: 要不是您腳本的傳回值，就是您腳本傳回的 Promise 的實現，或是導致您腳本傳回的 Promise 被拒絕的錯誤。
getAllCookies
Get All Cookies 命令會傳回與目前瀏覽內容活動文件的位址相關聯的所有 Cookie。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getAllCookies()
範例
loading...
傳回值
- <Object[]>
cookies: 已序列化的 Cookie 清單。每個已序列化的 Cookie 都有一些可選欄位，除了name和value之外，這些欄位可能會或可能不會傳回。
addCookie
Add Cookie 命令會將單一 Cookie 新增至與活動文件位址相關聯的 Cookie 儲存區。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.addCookie(cookie)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
cookie | 物件 | 代表 Cookie 的 JSON 物件。它必須至少具有 name 和 value 欄位，並且可以有更多欄位，包括到期時間等等 |
範例
loading...
deleteAllCookies
Delete All Cookies 命令允許刪除與活動文件位址相關聯的所有 Cookie。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.deleteAllCookies()
範例
loading...
getNamedCookie
Get Named Cookie 命令會從目前瀏覽內容活動文件的 Cookie 儲存區中的相關 Cookie 傳回具有要求名稱的 Cookie。如果找不到 Cookie，則會傳回「找不到此 Cookie」錯誤。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getNamedCookie(name)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
name | 字串 | 要擷取的 Cookie 名稱 |
範例
loading...
傳回值
- <Object>
cookie: 已序列化的 Cookie，具有 name 和 value 欄位。還有一些可選欄位，如path、domain和expiry-time也可能會存在。
deleteCookie
Delete Cookie 命令允許您依參數名稱刪除單一 Cookie，如果未定義名稱，則會刪除與活動文件位址相關聯的所有 Cookie。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.deleteCookie(name)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
name | 字串 | 要刪除的 Cookie 名稱 |
範例
loading...
performActions
Perform Actions 命令用於執行複雜的使用者動作。請參閱規格以取得更多詳細資訊。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.performActions(actions)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
actions | 物件 [] | 物件清單，每個物件都代表一個輸入來源及其相關聯的動作 |
releaseActions
Release Actions 命令用於釋放目前被按下的所有按鍵和指標按鈕。這會觸發事件，就像此狀態是由一連串明確的動作所釋放的一樣。它也會清除虛擬裝置的所有內部狀態。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.releaseActions()
dismissAlert
Dismiss Alert 命令會關閉簡易對話方塊 (如果存在)，否則會發生錯誤。要求關閉警示使用者提示 (可能不一定有關閉按鈕) 的效果與接受提示相同。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.dismissAlert()
範例
loading...
acceptAlert
如果存在簡單的對話框，Accept Alert 命令會接受它，否則會產生錯誤。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.acceptAlert()
getAlertText
Get Alert Text 命令會傳回目前使用者提示的訊息。如果目前沒有使用者提示，則會傳回錯誤。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getAlertText()
範例
loading...
傳回值
- <string>
alertText: 使用者提示的訊息。
sendAlertText
Send Alert Text 命令會將 window.prompt 使用者提示的文字欄位設定為給定的值。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.sendAlertText(text)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
text | 字串 | 要設定提示的字串 |
takeScreenshot
Take Screenshot 命令會擷取最上層瀏覽內容可視區域的螢幕截圖。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.takeScreenshot()
傳回值
- <string>
screenshot: 包含初始可視區域螢幕截圖的 Base64 編碼 PNG 影像資料。
takeElementScreenshot
Take Element Screenshot 命令會擷取元素邊界矩形所包含的可見區域的螢幕截圖。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.takeElementScreenshot(elementId, scroll)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
捲動可選 | 布林值 | 將元素捲動至可視範圍。預設值：true |
傳回值
- <string>
screenshot: 包含元素邊界矩形的可見區域（在捲動至可視範圍後）螢幕截圖的 Base64 編碼 PNG 影像資料。
getElementComputedRole
取得元素的計算 WAI-ARIA 角色。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getElementComputedRole(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
傳回值
- <string>
role: 計算元素 WAI-ARIA 角色的結果。
getElementComputedLabel
取得元素的可存取名稱。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getElementComputedLabel(elementId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
elementId | 字串 | 先前呼叫 Find Element(s) 時所回傳的元素 ID |
傳回值
- <string>
label: 元素可存取名稱的可存取名稱和說明計算結果。
setPermissions
模擬使用者修改 PermissionDescriptor 的權限狀態。注意：此功能尚未在所有瀏覽器中實作。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.setPermissions(descriptor, state, oneRealm)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
描述符 | 物件 | 每個強大功能都具有一個或多個網站可以請求權限來存取的層面。為了描述這些層面，每個功能都會定義一個 PermissionDescriptor 子類型作為其權限描述符類型。注意：此功能尚未在所有瀏覽器中實作。 |
狀態 | 字串 | 決定是否授予、拒絕或提示權限。 |
oneRealm可選 | 布林值 | 是否將權限套用至所有執行環境。 |
範例
// set midi permissions
browser.setPermissions(
{ name: 'midi', sysex: true },
'granted' // can be also "denied" or "prompt"
);
// set clipboard permissions
browser.setPermissions({ name: 'clipboard-read' }, 'granted');
// now you can read the clipboard via, e.g.
const clipboardText = await browser.execute(() => navigator.clipboard.readText());
generateTestReport
產生測試報告。 Reporting API 的擴充功能。注意：此功能尚未在所有瀏覽器中實作。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.generateTestReport(message, group)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
訊息 | 字串 | 要顯示在報告中的訊息。 |
群組可選 | 字串 | 指定將報告傳送到的端點群組。 |
createMockSensor
建立模擬感應器以模擬環境光感應器等感應器。注意：此功能尚未在所有瀏覽器中實作。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.createMockSensor(mockSensorType, maxSamplingFrequency, minSamplingFrequency)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
mockSensorType | 字串 | 要模擬的感應器 API 類型，例如 'ambient-light' |
maxSamplingFrequency可選 | 數字 | 一個雙精度浮點數，表示以 Hz 為單位的頻率，用於設定相關模擬感應器支援的最大取樣頻率。 |
minSamplingFrequency可選 | 數字 | 一個雙精度浮點數，表示以 Hz 為單位的頻率，用於設定相關模擬感應器支援的最小取樣頻率。 |
getMockSensor
擷取有關給定類型模擬感應器的資訊。注意：此功能尚未在所有瀏覽器中實作。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.getMockSensor(type)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
type | 字串 | 要從中擷取資訊的模擬感應器類型。 |
傳回值
- <object>
sensorReading: 模擬感應器讀取的值。
updateMockSensor
更新模擬感應器類型。注意：此功能尚未在所有瀏覽器中實作。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.updateMockSensor(type, mockSensorType, maxSamplingFrequency, minSamplingFrequency)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
type | 字串 | 要更新資訊的模擬感應器類型。 |
mockSensorType | 字串 | 要模擬的感應器 API 類型，例如 'ambient-light' |
maxSamplingFrequency可選 | 數字 | 一個雙精度浮點數，表示以 Hz 為單位的頻率，用於設定相關模擬感應器支援的最大取樣頻率。 |
minSamplingFrequency可選 | 數字 | 一個雙精度浮點數，表示以 Hz 為單位的頻率，用於設定相關模擬感應器支援的最小取樣頻率。 |
deleteMockSensor
Delete Session 命令會關閉與目前會話相關聯的所有最上層瀏覽內容、終止連線，最後關閉目前的會話。注意：此功能尚未在所有瀏覽器中實作。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.deleteMockSensor(type)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
type | 字串 | 要刪除的模擬感應器類型。 |
setTimeZone
模擬為了測試而變更時區。注意：此功能尚未在所有瀏覽器中實作。
WebDriver 協定命令。更多詳細資訊請參閱官方協定文件。
用法
browser.setTimeZone(time_zone)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
time_zone | 字串 | 時區名稱，例如 Asia/Tokyo |
addVirtualAuthenticator
建立一個軟體 虛擬驗證器。
WebDriver 協定指令。更多詳細資訊請參閱官方協定文件。
用法
browser.addVirtualAuthenticator(protocol, transport, hasResidentKey, hasUserVerification, isUserConsenting, isUserVerified, extensions, uvm)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
protocol可選 | 字串 | 有效值：'ctap1/u2f'、'ctap2'、'ctap2_1'。 |
transport可選 | 字串 | 有效值：'usb'、'nfc'、'ble' 或 'internal'。 |
hasResidentKey可選 | 布林值 | 有效值：true、false。 |
hasUserVerification可選 | 布林值 | 有效值：true、false。 |
isUserConsenting可選 | 布林值 | 有效值：true、false。 |
isUserVerified可選 | 布林值 | 有效值：包含擴充識別碼的陣列。 |
extensions可選 | string[] | 有效值：最多 3 個使用者驗證方法項目。 |
uvm可選 | 物件 [] |
回傳值
- <string>
authenticatorId： 回傳驗證器的字串 ID。
removeVirtualAuthenticator
移除先前建立的虛擬驗證器。
WebDriver 協定指令。更多詳細資訊請參閱官方協定文件。
用法
browser.removeVirtualAuthenticator(authenticatorId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
authenticatorId | 字串 | 驗證器的 ID |
addCredential
將公鑰憑證來源注入現有的虛擬驗證器。
WebDriver 協定指令。更多詳細資訊請參閱官方協定文件。
用法
browser.addCredential(authenticatorId, credentialId, isResidentCredential, rpId, privateKey, userHandle, signCount, largeBlob)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
authenticatorId | 字串 | 驗證器的 ID |
credentialId | 字串 | 使用 Base64url 編碼的憑證 ID。 |
isResidentCredential | 布林值 | 如果設定為 true，則會建立用戶端可探索的憑證。如果設定為 false，則會建立伺服器端憑證。 |
rpId | 字串 | 憑證的範圍所屬的依賴方 ID。 |
privateKey | 字串 | 包含每個 [RFC5958] 單個私鑰的非對稱金鑰套件，使用 Base64url 編碼。 |
userHandle | 字串 | 與使用 Base64url 編碼的憑證相關聯的 userHandle。此屬性可能未定義。 |
signCount | 數字 | 與公鑰憑證來源相關聯的簽名計數器的初始值。 |
largeBlob可選 | 字串 | 與公鑰憑證來源相關聯的每個憑證大型 Blob，使用 Base64url 編碼。此屬性可能未定義。 |
getCredentials
針對儲存在虛擬驗證器中的每個公鑰憑證來源，回傳一個憑證參數物件，無論它們是使用「新增憑證」或 navigator.credentials.create() 儲存的。
WebDriver 協定指令。更多詳細資訊請參閱官方協定文件。
用法
browser.getCredentials(authenticatorId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
authenticatorId | 字串 | 驗證器的 ID |
回傳值
- <object[]>
credentials： 回傳憑證的陣列。
removeAllCredentials
移除儲存在虛擬驗證器上的所有公鑰憑證來源。
WebDriver 協定指令。更多詳細資訊請參閱官方協定文件。
用法
browser.removeAllCredentials(authenticatorId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
authenticatorId | 字串 | 驗證器的 ID |
removeCredential
移除儲存在虛擬驗證器上的公鑰憑證來源。
WebDriver 協定指令。更多詳細資訊請參閱官方協定文件。
用法
browser.removeCredential(authenticatorId, credentialId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
authenticatorId | 字串 | 驗證器的 ID |
credentialId | 字串 | 憑證的 ID |
setUserVerified
「設定使用者已驗證」擴充指令會設定虛擬驗證器上的 isUserVerified 屬性。
WebDriver 協定指令。更多詳細資訊請參閱官方協定文件。
用法
browser.setUserVerified(authenticatorId)
參數
| 名稱 | 類型 | 詳細資訊 |
|---|---|---|
authenticatorId | 字串 | 驗證器的 ID |
