複雑なユーザーアクションの作成

概要

Nightwatch 2は、複雑なユーザージェスチャを実行するためのSelenium WebDriverの新しいActions APIのサポートを提供します。

Actions APIは、指定された入力デバイスが正確に何ができるかを細かく制御できます。Seleniumは3種類の入力ソースのインターフェースを提供します。

  • キーボードデバイス用のキー入力
  • マウス、ペン、またはタッチデバイス用のポインター入力
  • スクロールホイールデバイス用のホイール入力（Selenium 4.2で導入）

詳細については、W3C Webdriver仕様ページをご覧ください。

例

新しいAPIは、既存の.perform()コマンドを介してNightwatchで使用できます。perform()コマンドの以前の機能は、以前と同じように動作しています。

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

  it('demo test', function() {
    browser
      .navigateTo('https://nightwatch.dokyumento.jp')
      .perform(function() {
        const actions = this.actions({async: true});
        

        return actions
         .keyDown(Keys.SHIFT)
         .keyUp(Keys.SHIFT);
      });
  })
})

使用可能なアクション

.clear()

すべてのキーとポインターを解放し、内部状態をクリアします。

パラメーター

なし

.click([element])

マウスで単純な左クリック（ダウン/アップ）を実行するためのショートハンドです。

パラメーター
名前 タイプ 説明
要素
オプション		 WebElement 指定されている場合、マウスはクリックを実行する前に要素の中央に移動します。

.contextClick([element])

マウスで単純な右クリック（ダウン/アップ）を実行するためのショートハンドです。

パラメーター
名前 タイプ 説明
要素
オプション		 WebElement 指定されている場合、マウスはクリックを実行する前に要素の中央に移動します。

.doubleClick([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()

パラメーター

なし

戻り値
タイプ 説明
Pointer マウスポインターデバイスハンドル。

.move([options])

指定されたoriginに対してマウスをxおよびyピクセル相対的に移動するアクションを挿入します。originは、マウスの現在の位置、ビューポート、または特定のWebElementの中央として定義できます。

durationパラメーターを使用して、ブラウザドライバが移動を実行するのにかかる時間をミリ秒単位で調整できます（デフォルトは100ミリ秒）。

パラメーター
名前 タイプ 説明
options
オプション 		オブジェクト 移動オプション。デフォルトでは、100ミリ秒でビューポートの左上にマウスを移動します。

使用可能な値は
{
  duration: {Number|undefined}, 
  origin: (Origin|WebElement|undefined), 
  x: {Number|undefined}, 
  y: {Number|undefined}
}

.pause(duration, ...devices)

指定されたデバイスに対してポーズアクションを挿入し、各デバイスがティックごとにアイドル状態になるようにします。ポーズの長さ（ミリ秒単位）は、このメソッドの最初のパラメーターとして指定できます（デフォルトは0）。それ以外の場合は、ポーズする個々のデバイスを指定できます。

デバイスが指定されていない場合、すべてのデバイスに対してポーズアクション（同じ期間を使用）が作成されます。

パラメーター
名前 タイプ 説明
duration
オプション 		Number|Device 挿入するポーズの長さ（ミリ秒単位）。または、durationを省略し（デフォルトの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では各デバイスの2番目のアクションを実行し、すべてのアクションが実行されるまで続きます。特定のティックで個々のデバイスにアクションが定義されていない場合、自動的にポーズします。

デフォルトでは、アクションシーケンスは同期されるため、各ティックで1つのデバイスのみがアクションを定義します。次のコードサンプルを考えてみましょう。

tests/sampleTest.js 
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()

推奨コンテンツ