アクション
はじめに
Playwrightは、テキスト入力、チェックボックス、ラジオボタン、選択オプション、マウスクリック、文字入力、キー、ショートカットなど、HTML入力要素と対話できるほか、ファイルのアップロードや要素のフォーカスも可能です。
テキスト入力
Locator.fill()を使用するのが、フォームフィールドに入力する最も簡単な方法です。要素をフォーカスし、入力されたテキストでinput
イベントをトリガーします。これは<input>
、<textarea>
、および[contenteditable]
要素で機能します。
// Text input
page.getByRole(AriaRole.TEXTBOX).fill("Peter");
// Date input
page.getByLabel("Birth date").fill("2020-02-02");
// Time input
page.getByLabel("Appointment time").fill("13-15");
// Local datetime input
page.getByLabel("Local time").fill("2020-03-02T05:15");
チェックボックスとラジオボタン
Locator.setChecked()を使用するのが、チェックボックスまたはラジオボタンをチェック/アンチェックする最も簡単な方法です。このメソッドは、input[type=checkbox]
、input[type=radio]
、および[role=checkbox]
要素で使用できます。
// Check the checkbox
page.getByLabel("I agree to the terms above").check();
// Assert the checked state
assertTrue(page.getByLabel("Subscribe to newsletter")).isChecked();
// Select the radio button
page.getByLabel("XL").check();
選択オプション
Locator.selectOption()を使用して、<select>
要素で1つまたは複数のオプションを選択します。選択するにはオプションのvalue
またはlabel
を指定できます。複数のオプションを選択することもできます。
// Single selection matching the value or label
page.getByLabel("Choose a color").selectOption("blue");
// Single selection matching the label
page.getByLabel("Choose a color").selectOption(new SelectOption().setLabel("Blue"));
// Multiple selected items
page.getByLabel("Choose multiple colors").selectOption(new String[] {"red", "green", "blue"});
マウスクリック
単純な人間によるクリックを実行します。
// Generic click
page.getByRole(AriaRole.BUTTON).click();
// Double click
page.getByText("Item").dblclick();
// Right click
page.getByText("Item").click(new Locator.ClickOptions().setButton(MouseButton.RIGHT));
// Shift + click
page.getByText("Item").click(new Locator.ClickOptions().setModifiers(Arrays.asList(KeyboardModifier.SHIFT)));
// Ctrl + click on Windows and Linux
// Meta + click on macOS
page.getByText("Item").click(new Locator.ClickOptions().setModifiers(Arrays.asList(KeyboardModifier.CONTROL_OR_META)));
// Hover over element
page.getByText("Item").hover();
// Click the top left corner
page.getByText("Item").click(new Locator.ClickOptions().setPosition(0, 0));
内部的には、このメソッドおよびその他のポインター関連のメソッドは次の処理を行います。
- 指定されたセレクターを持つ要素がDOMに存在するかを待機する
- 表示されるようになるまで待機する(つまり、空ではない、
display:none
ではない、visibility:hidden
ではない) - 移動が停止するまで待機する(例えば、CSSトランジションが終了するまで)
- 要素をビューにスクロールする
- アクションポイントでポインターイベントを受け取るまで待機する(例えば、要素が他の要素によって隠されなくなるまで待機する)
- 上記のチェック中に要素がデタッチされた場合、リトライする
クリックの強制
アプリケーションによっては、要素にホバーすると、クリックをインターセプトする別の要素がオーバーレイされるという複雑なロジックを使用する場合があります。この動作は、要素が隠されてクリックが別の場所にディスパッチされるバグと区別できません。この状況が発生していることが分かっている場合は、動作可能性のチェックをバイパスしてクリックを強制できます。
page.getByRole(AriaRole.BUTTON).click(new Locator.ClickOptions().setForce(true));
プログラムによるクリック
実際の条件下でアプリケーションをテストすることに興味がなく、可能な限りクリックをシミュレートしたい場合は、Locator.dispatchEvent()を使用して要素にクリックイベントをディスパッチするだけで、HTMLElement.click()
の動作をトリガーできます。
page.getByRole(AriaRole.BUTTON).dispatchEvent("click");
文字入力
ほとんどの場合、Locator.fill()でテキストを入力する必要があります。上記のテキスト入力セクションを参照してください。ページに特別なキーボード処理がある場合にのみ、文字を入力する必要があります。
Locator.pressSequentially()を使用すると、実際のキーボードを持つユーザーのように、文字ごとにフィールドに入力できます。
// Press keys one by one
page.locator("#area").pressSequentially("Hello World!");
このメソッドは、必要なキーボードイベントすべて(keydown
、keyup
、keypress
イベント)を適切に発行します。キー押下間のオプションのdelay
を指定して、実際のユーザーの動作をシミュレートすることもできます。
キーとショートカット
// Hit Enter
page.getByText("Submit").press("Enter");
// Dispatch Control+Right
page.getByRole(AriaRole.TEXTBOX).press("Control+ArrowRight");
// Press $ sign on keyboard
page.getByRole(AriaRole.TEXTBOX).press("$");
Locator.press()メソッドは、選択された要素をフォーカスし、単一のキーストロークを生成します。これは、キーボードイベントのkeyboardEvent.key
プロパティで発行される論理的なキー名を受け入れます。
Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape,
ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight,
ArrowUp, F1 - F12, Digit0 - Digit9, KeyA - KeyZ, etc.
- 代わりに、
"a"
や"#"
のような生成したい単一の文字を指定することもできます。 - 以下の修飾ショートカットもサポートされています:
Shift, Control, Alt, Meta
。
シンプルなバージョンは単一の文字を生成します。この文字は大文字と小文字が区別されるため、"a"
と"A"
では異なる結果になります。
// <input id=name>
page.locator("#name").press("Shift+A");
// <input id=name>
page.locator("#name").press("Shift+ArrowLeft");
"Control+o"
や "Control+Shift+T"
といったショートカットもサポートされています。修飾子と共に指定された場合、修飾子が押されたまま、後続のキーが押されます。
大文字を生成するには、Shift-A
で大文字のA
を指定する必要があることに注意してください。Shift-a
は、CapsLock
がオンになっているかのように小文字を生成します。
ファイルのアップロード
Locator.setInputFiles()メソッドを使用して、アップロードする入力ファイルを選択できます。最初の引数は、タイプが"file"
のinput要素を指すことを期待しています。複数のファイルを配列で渡すことができます。ファイルパスの一部が相対パスの場合、それらは現在の作業ディレクトリを基準に解決されます。空の配列は選択されたファイルをクリアします。
// Select one file
page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));
// Select multiple files
page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});
// Select a directory
page.getByLabel("Upload directory").setInputFiles(Paths.get("mydir"));
// Remove all the selected files
page.getByLabel("Upload file").setInputFiles(new Path[0]);
// Upload buffer from memory
page.getByLabel("Upload file").setInputFiles(new FilePayload(
"file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));
input要素が手元にない場合(動的に作成される場合)、Page.onFileChooser(handler)イベントを処理するか、アクションに対応する待機メソッドを使用できます。
FileChooser fileChooser = page.waitForFileChooser(() -> {
page.getByLabel("Upload file").click();
});
fileChooser.setFiles(Paths.get("myfile.pdf"));
要素のフォーカス
フォーカスイベントを処理する動的なページの場合、Locator.focus()で指定された要素にフォーカスを当てることができます。
page.getByLabel("Password").focus();
ドラッグ&ドロップ
Locator.dragTo()でドラッグ&ドロップ操作を実行できます。このメソッドは次のことを行います。
- ドラッグされる要素にホバーします。
- 左マウスボタンを押します。
- ドロップを受け取る要素にマウスを移動します。
- 左マウスボタンを離します。
page.locator("#item-to-be-dragged").dragTo(page.locator("#item-to-drop-at"));
手動によるドラッグ
ドラッグ操作をより正確に制御したい場合は、Locator.hover()、Mouse.down()、Mouse.move()、Mouse.up()のような低レベルのメソッドを使用してください。
page.locator("#item-to-be-dragged").hover();
page.mouse().down();
page.locator("#item-to-drop-at").hover();
page.mouse().up();
ページがdragover
イベントのディスパッチに依存している場合、すべてのブラウザでそれをトリガーするには少なくとも2回のマウス移動が必要です。2回目のマウス移動を確実に実行するには、Mouse.move()またはLocator.hover()を2回繰り返してください。操作のシーケンスは次のようになります: ドラッグ要素にホバー、マウスダウン、ドロップ要素にホバー、ドロップ要素に2回目のホバー、マウスアップ。
スクロール
ほとんどの場合、Playwrightはアクションを実行する前に自動的にスクロールを行います。そのため、明示的にスクロールする必要はありません。
// Scrolls automatically so that button is visible
page.getByRole(AriaRole.BUTTON).click();
しかし、稀に手動でスクロールする必要がある場合があります。例えば、「無限リスト」にさらに要素をロードさせたい場合や、特定のスクリーンショットのためにページを配置したい場合です。そのような場合、最も信頼性の高い方法は、下部に表示させたい要素を見つけて、それをビューにスクロールすることです。
// Scroll the footer into view, forcing an "infinite list" to load more content
page.getByText("Footer text").scrollIntoViewIfNeeded();
スクロールをより正確に制御したい場合は、Mouse.wheel()またはLocator.evaluate()を使用してください。
// Position the mouse and scroll with the mouse wheel
page.getByTestId("scrolling-container").hover();
page.mouse.wheel(0, 10);
// Alternatively, programmatically scroll a specific element
page.getByTestId("scrolling-container").evaluate("e => e.scrollTop += 100");