アクション
はじめに
Playwrightは、テキスト入力、チェックボックス、ラジオボタン、選択オプション、マウスクリック、文字入力、キーボードショートカットなど、HTMLのInput要素と対話でき、ファイルのアップロードや要素へのフォーカスも可能です。
テキスト入力
locator.fill()を使用するのが、フォームフィールドに入力する最も簡単な方法です。これにより要素にフォーカスが当たり、入力されたテキストでinputイベントがトリガーされます。これは<input>、<textarea>、[contenteditable]要素で機能します。
// Text input
await page.getByRole('textbox').fill('Peter');
// Date input
await page.getByLabel('Birth date').fill('2020-02-02');
// Time input
await page.getByLabel('Appointment time').fill('13:15');
// Local datetime input
await page.getByLabel('Local time').fill('2020-03-02T05:15');
チェックボックスとラジオボタン
locator.setChecked()を使用するのが、チェックボックスやラジオボタンをチェック/アンチェックする最も簡単な方法です。このメソッドはinput[type=checkbox]、input[type=radio]、[role=checkbox]要素で使用できます。
// Check the checkbox
await page.getByLabel('I agree to the terms above').check();
// Assert the checked state
expect(page.getByLabel('Subscribe to newsletter')).toBeChecked();
// Select the radio button
await page.getByLabel('XL').check();
オプションの選択
locator.selectOption()を使用して、<select>要素で1つまたは複数のオプションを選択します。オプションのvalueまたはlabelを指定して選択できます。複数のオプションを選択することが可能です。
// Single selection matching the value or label
await page.getByLabel('Choose a color').selectOption('blue');
// Single selection matching the label
await page.getByLabel('Choose a color').selectOption({ label: 'Blue' });
// Multiple selected items
await page.getByLabel('Choose multiple colors').selectOption(['red', 'green', 'blue']);
マウスクリック
シンプルな人間によるクリックを実行します。
// Generic click
await page.getByRole('button').click();
// Double click
await page.getByText('Item').dblclick();
// Right click
await page.getByText('Item').click({ button: 'right' });
// Shift + click
await page.getByText('Item').click({ modifiers: ['Shift'] });
// Ctrl + click on Windows and Linux
// Meta + click on macOS
await page.getByText('Item').click({ modifiers: ['ControlOrMeta'] });
// Hover over element
await page.getByText('Item').hover();
// Click the top left corner
await page.getByText('Item').click({ position: { x: 0, y: 0 } });
内部では、このメソッドおよびその他のポインター関連メソッドは次の処理を行います。
- 指定されたセレクターを持つ要素がDOMに存在することを待機します。
- 要素が表示されるまで待機します（つまり、空ではなく、
display:none、visibility:hiddenが適用されていない状態）。 - 要素が動きを止めるまで待機します（例: CSSトランジションが終了するまで）。
- 要素をビュー内にスクロールします。
- 要素がアクションポイントでポインターイベントを受信するまで待機します（例: 他の要素によって隠されなくなるまで待機します）。
- 上記のいずれかのチェック中に要素がデタッチされた場合、再試行します。
クリックの強制
場合によっては、要素にホバーすると、クリックをインターセプトする別の要素がその上に重なるという、複雑なロジックを使用するアプリがあります。この動作は、要素が隠れてしまい、クリックが別の場所にディスパッチされるバグと区別できません。このような状況が発生していることがわかっている場合、アクション可能性のチェックをバイパスしてクリックを強制できます。
await page.getByRole('button').click({ force: true });
プログラムによるクリック
実際の条件下でアプリをテストすることに興味がなく、可能な限りクリックをシミュレートしたい場合は、locator.dispatchEvent()を使用して要素にクリックイベントをディスパッチするだけで、HTMLElement.click()の動作をトリガーできます。
await page.getByRole('button').dispatchEvent('click');
文字の入力
ほとんどの場合、テキスト入力にはlocator.fill()を使用すべきです。上記の「テキスト入力」セクションを参照してください。ページで特別なキーボード処理が行われている場合にのみ、文字をタイプする必要があります。
locator.pressSequentially()を使用すると、実際のキーボードを持つユーザーであるかのように、フィールドに1文字ずつタイプできます。
// Press keys one by one
await page.locator('#area').pressSequentially('Hello World!');
このメソッドは、必要なすべてのキーボードイベント（keydown、keyup、keypressイベントを含む）を発生させます。実際のユーザーの行動をシミュレートするために、キー押下間のオプションのdelayを指定することもできます。
キーとショートカット
// Hit Enter
await page.getByText('Submit').press('Enter');
// Dispatch Control+Right
await page.getByRole('textbox').press('Control+ArrowRight');
// Press $ sign on keyboard
await page.getByRole('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>
await page.locator('#name').press('Shift+A');
// <input id=name>
await page.locator('#name').press('Shift+ArrowLeft');
"Control+o"や"Control+Shift+T"のようなショートカットもサポートされています。修飾子を指定すると、修飾子が押され、次のキーが押されている間保持されます。
Shift-Aで大文字を生成するには、依然として大文字のAを指定する必要があることに注意してください。Shift-aは、CapsLockがオンになっているかのように小文字を生成します。
ファイルのアップロード
locator.setInputFiles()メソッドを使用して、アップロードする入力ファイルを選択できます。最初の引数は、タイプが"file"であるinput要素を指す必要があります。複数のファイルを配列で渡すことができます。ファイルパスの一部が相対パスである場合、それらは現在の作業ディレクトリからの相対パスとして解決されます。空の配列は選択されたファイルをクリアします。
// Select one file
await page.getByLabel('Upload file').setInputFiles(path.join(__dirname, 'myfile.pdf'));
// Select multiple files
await page.getByLabel('Upload files').setInputFiles([
path.join(__dirname, 'file1.txt'),
path.join(__dirname, 'file2.txt'),
]);
// Select a directory
await page.getByLabel('Upload directory').setInputFiles(path.join(__dirname, 'mydir'));
// Remove all the selected files
await page.getByLabel('Upload file').setInputFiles([]);
// Upload buffer from memory
await page.getByLabel('Upload file').setInputFiles({
name: 'file.txt',
mimeType: 'text/plain',
buffer: Buffer.from('this is test')
});
もしinput要素が手元にない場合（動的に作成される場合）、page.on('filechooser')イベントを処理するか、アクションに応じて対応する待機メソッドを使用できます。
// Start waiting for file chooser before clicking. Note no await.
const fileChooserPromise = page.waitForEvent('filechooser');
await page.getByLabel('Upload file').click();
const fileChooser = await fileChooserPromise;
await fileChooser.setFiles(path.join(__dirname, 'myfile.pdf'));
要素にフォーカス
フォーカスイベントを処理する動的なページの場合、locator.focus()を使用して指定された要素にフォーカスを当てることができます。
await page.getByLabel('Password').focus();
ドラッグアンドドロップ
locator.dragTo()を使用してドラッグ＆ドロップ操作を実行できます。このメソッドは、次の動作をします。
- ドラッグする要素にホバーします。
- マウスの左ボタンを押します。
- ドロップ先となる要素にマウスを移動します。
- マウスの左ボタンを離します。
await page.locator('#item-to-be-dragged').dragTo(page.locator('#item-to-drop-at'));
手動でのドラッグ
ドラッグ操作をより細かく制御したい場合は、locator.hover()、mouse.down()、mouse.move()、mouse.up()のような低レベルのメソッドを使用してください。
await page.locator('#item-to-be-dragged').hover();
await page.mouse.down();
await page.locator('#item-to-drop-at').hover();
await page.mouse.up();
もしページがdragoverイベントのディスパッチに依存している場合、すべてのブラウザでそれをトリガーするには少なくとも2回のマウス移動が必要です。確実に2回目のマウス移動を行うには、mouse.move()またはlocator.hover()を2回繰り返してください。操作の順序は、ドラッグ要素にホバー、マウスダウン、ドロップ要素にホバー、ドロップ要素に再度ホバー、マウスアップとなります。
スクロール
ほとんどの場合、Playwrightはアクションを実行する前に自動的にスクロールを行います。そのため、明示的にスクロールする必要はありません。
// Scrolls automatically so that button is visible
await page.getByRole('button').click();
ただし、まれに手動でスクロールする必要がある場合があります。例えば、「無限リスト」にさらに要素を読み込ませるために強制したり、特定のスクリーンショットのためにページを配置したりする場合です。そのような場合、最も確実な方法は、下部に表示させたい要素を見つけて、それをビュー内にスクロールすることです。
// Scroll the footer into view, forcing an "infinite list" to load more content
await page.getByText('Footer text').scrollIntoViewIfNeeded();
スクロールをより正確に制御したい場合は、mouse.wheel()またはlocator.evaluate()を使用してください。
// Position the mouse and scroll with the mouse wheel
await page.getByTestId('scrolling-container').hover();
await page.mouse.wheel(0, 10);
// Alternatively, programmatically scroll a specific element
await page.getByTestId('scrolling-container').evaluate(e => e.scrollTop += 100);