ユーザーアクションAPI

概要

Selenium の Actions API は、Nightwatch で既存の .perform() コマンドを通じて使用できます。

利用可能なアクション

.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 押すキー。このキーは、キーの値、特定の Unicode コードポイント、または単一の Unicode コードポイントを含む文字列として指定できます。

.keyUp(key)

単一のキーを離すアクションを挿入します。

パラメータ
名前 タイプ 説明
key string|number 離すキー。このキーは、キーの値、特定の Unicode コードポイント、または単一の Unicode コードポイントを含む文字列として指定できます。

.keyboard()

パラメータ

なし

戻り値
タイプ 説明
Keyboard キーボードデバイスハンドル。

.mouse()

パラメータ

なし

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

.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 を使用して) 一時停止アクションが作成されます。

パラメータ
名前 タイプ 説明
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 つのデバイスのみがアクションを定義します。次のコードサンプルを考えてみましょう。

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.dokyumento.jp'));
  

  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)
    });
  });
});