使用者動作 API

概述

Selenium 的 Actions API 可透過現有的 .perform() 指令在 Nightwatch 中使用。

可用的動作

.clear()

釋放所有按鍵、指標，並清除內部狀態。

參數

無

.click([element])

執行簡單的滑鼠左鍵點擊（按下/放開）的簡寫。

參數
名稱 類型 描述
element
選填		 WebElement 如果指定，滑鼠將先移動到元素的中心，然後再執行點擊。

.contextClick([element])

執行簡單的滑鼠右鍵點擊（按下/放開）的簡寫。

參數
名稱 類型 描述
element
選填		 WebElement 如果指定，滑鼠將先移動到元素的中心，然後再執行點擊。

.doubleClick([element])

執行滑鼠左鍵雙擊的簡寫。

參數
名稱 類型 描述
element
選填		 WebElement 如果指定，滑鼠將先移動到元素的中心，然後再執行點擊。

.dragAndDrop(from, to)

設定一個包含以下步驟的拖放動作
  1. 移動到 from 元素的中心（要拖曳的元素）。
  2. 按下滑鼠左鍵。
  3. 如果 to 目標是 WebElement，則將滑鼠移動到其中心。否則，將滑鼠移動指定的偏移量。
  4. 放開滑鼠左鍵。
參數
名稱 類型 描述
from WebElement 按下滑鼠左鍵開始拖曳的元素
to WebElement 或
{x: number, y: number}		 另一個要拖曳到的元素（將拖曳到元素的中心），或指定拖曳偏移量（以像素為單位）的物件。

.insert(device, ...actions)

將動作附加到給定 device 的目前序列的末尾。如果啟用裝置同步，在插入動作後，會為所有其他裝置插入暫停，以確保所有動作序列的長度相同。

參數
名稱 類型 描述
device 裝置 要更新的裝置
actions ...Action 要插入的動作。

.keyDown(key)

插入按下單一按鍵的動作。

參數
名稱 類型 描述
key string|number 要按下的按鍵。此按鍵可以指定為 Key 值、特定 unicode 程式碼點，或包含單一 unicode 程式碼點的字串。

.keyUp(key)

插入釋放單一按鍵的動作。

參數
名稱 類型 描述
key string|number 要釋放的按鍵。此按鍵可以指定為 Key 值、特定 unicode 程式碼點，或包含單一 unicode 程式碼點的字串。

.keyboard()

參數

無

返回
類型 描述
Keyboard 鍵盤裝置控制代碼。

.mouse()

參數

無

返回
類型 描述
指標 滑鼠指標裝置控制代碼。

.move([options])

插入一個動作，使滑鼠相對於指定的 origin 移動 x 和 y 像素。原點可以定義為滑鼠的目前位置、視窗，或特定 WebElement 的中心。

可以使用 duration 參數（預設為 100 毫秒）調整瀏覽器驅動程式執行移動所需的時間（以毫秒為單位）。

參數
名稱 類型 描述
options
選填 		Object 移動選項。預設為在 100 毫秒內將滑鼠移動到視窗的左上角。

可用的值為
{
  duration: {Number|undefined}, 
  origin: (Origin|WebElement|undefined), 
  x: {Number|undefined}, 
  y: {Number|undefined}
}

.pause(duration, ...devices)

為指定的裝置插入暫停動作，確保每個裝置在一個刻度內處於閒置狀態。暫停的長度（以毫秒為單位）可以指定為此方法的第一個參數（預設為 0）。或者，您也可以只指定應暫停的個別裝置。

如果未指定任何裝置，則會為每個裝置建立一個暫停動作（使用相同的持續時間）。

參數
名稱 類型 描述
duration
選填 		Number|Device 要插入的暫停長度（以毫秒為單位）。或者，可以省略持續時間（產生預設 0 毫秒的暫停），並指定第一個要暫停的裝置。
devices ...Device 要插入暫停的裝置。如果未指定任何裝置，則會為所有裝置插入暫停。

.press([button])

插入一個動作，在滑鼠的目前位置按下滑鼠按鈕。

參數
名稱 類型 描述
button
選填 		Button 要按下的按鈕；預設為 LEFT。

.release([button])

插入一個動作，在滑鼠的目前位置釋放滑鼠按鈕。

參數
名稱 類型 描述
button
選填 		Button 要釋放的按鈕；預設為 LEFT。

.sendKeys(...keys)

插入一系列動作以輸入提供的按鍵序列。對於每個按鍵，這將記錄一對 keyDown 和 keyUp 動作。

參數
名稱 類型 描述
keys ...String|Number 要輸入的按鍵。

.synchronize(...devices)

確保此動作序列中引用的每個裝置的動作序列長度相同。對於序列太短的裝置，這將插入暫停，以便每個裝置在每個刻度都有明確定義的動作。

參數
名稱 類型 描述
devices ...Device 要同步的特定裝置。如果未指定，則會同步每個裝置的動作序列。

使用動作刻度

動作序列分為一系列「刻度」。在每個刻度，瀏覽器驅動程式將為動作序列中包含的每個裝置執行單一動作。在刻度 0 時，驅動程式將執行為每個裝置定義的第一個動作，在刻度 1 時執行每個裝置的第二個動作，依此類推，直到所有動作都已執行。如果個別裝置在特定刻度沒有定義動作，它將自動暫停。

預設情況下，動作序列會同步，因此每個刻度只有一個裝置有定義的動作。請考慮以下程式碼範例

describe('user actions api', function() {
  

  it('demo test', function() {
    browser
      .perform(function() {
        const actions = this.actions({async: true});
        

        return actions
          .keyDown(Keys.SHIFT)
          .move({origin: el})
          .press()
          .release()
          .keyUp(Keys.SHIFT);
      });
    })
})

這會產生以下刻度序列

裝置 刻度 1 刻度 2 刻度 3 刻度 4 刻度 5
Keyboard keyDown(SHIFT) pause() pause() pause() keyUp(SHIFT)
滑鼠 pause() move({origin: el}) press() release() pause()

有關動作刻度的更多資訊，請參閱Selenium 文件。

工作範例

tests/sampleTest.js 
describe('example with user actions api', function () {
  

  before(browser => browser.navigateTo('https://nightwatch.dev.org.tw'));
  

  it('demo test', async function (browser) {
    // retrieve the element; the actions api requires Selenium WebElement objects,
    //  which can be retrieved using the global element() utility
    const btnElement = await element('a.btn-github').findElement();
    

    await browser.perform(function() {
      // initiate the actions chain
      const actions = this.actions({async: true});
      

      return actions
        .dragAndDrop(btnElement, {x: 100, y: 100})
        .pause(500)
        .contextClick(btnElement)
        .pause(500)
        .doubleClick(btnElement)
        .pause(500)
    });
  });
});