アクション

概要

Playwright は、テキスト入力、チェックボックス、ラジオボタン、セレクトオプション、マウスクリック、文字入力、キーとショートカット、ファイルのアップロード、要素へのフォーカスなどの HTML 入力要素を操作できます。

テキスト入力

Locator.FillAsync() を使用すると、フォームフィールドへの入力を最も簡単に行えます。要素をフォーカスし、入力されたテキストで input イベントをトリガーします。<input>、<textarea>、および [contenteditable] 要素で動作します。

// Text input
await page.GetByRole(AriaRole.Textbox).FillAsync("Peter");

// Date input
await page.GetByLabel("Birth date").FillAsync("2020-02-02");

// Time input
await page.GetByLabel("Appointment time").FillAsync("13-15");

// Local datetime input
await page.GetByLabel("Local time").FillAsync("2020-03-02T05:15");

チェックボックスとラジオボタン

Locator.SetCheckedAsync() を使用すると、チェックボックスまたはラジオボタンのチェックとチェック解除を最も簡単に行えます。このメソッドは、input[type=checkbox]、input[type=radio]、および [role=checkbox] 要素で使用できます。

// Check the checkbox
await page.GetByLabel("I agree to the terms above").CheckAsync();

// Assert the checked state
await Expect(page.GetByLabel("Subscribe to newsletter")).ToBeCheckedAsync();

// Select the radio button
await page.GetByLabel("XL").CheckAsync();

セレクトオプション

Locator.SelectOptionAsync() を使用して、<select> 要素で 1 つまたは複数のオプションを選択します。選択するオプションの value または label を指定できます。複数のオプションを選択できます。

// Single selection matching the value or label
await page.GetByLabel("Choose a color").SelectOptionAsync("blue");

// Single selection matching the label
await page.GetByLabel("Choose a color").SelectOptionAsync(new SelectOptionValue { Label = "blue" });

// Multiple selected items
await page.GetByLabel("Choose multiple colors").SelectOptionAsync(new[] { "blue", "green", "red" });

マウスクリック

単純な人間のクリックを実行します。

// Generic click
await page.GetByRole(AriaRole.Button).ClickAsync();

// Double click
await page.GetByText("Item").DblClickAsync();

// Right click
await page.GetByText("Item").ClickAsync(new() { Button = MouseButton.Right });

// Shift + click
await page.GetByText("Item").ClickAsync(new() { Modifiers = new[] { KeyboardModifier.Shift } });

// Ctrl + click on Windows and Linux
// Meta + click on macOS
await page.GetByText("Item").ClickAsync(new() { Modifiers = new[] { KeyboardModifier.ControlOrMeta } });

// Hover over element
await page.GetByText("Item").HoverAsync();

// Click the top left corner
await page.GetByText("Item").ClickAsync(new() { position = new Position { X = 0, Y = 0 } });

内部的には、このメソッドと他のポインター関連のメソッドは、次のことを行います。

• 指定されたセレクターを持つ要素が DOM 内にあるのを待ちます
• 表示されるようになるのを待ちます。つまり、空ではなく、display:none ではなく、visibility:hidden ではない状態です
• 移動が停止するのを待ちます。たとえば、CSS トランジションが完了するまで待ちます
• 要素をビューにスクロールします
• アクションポイントでポインターイベントを受信するのを待ちます。たとえば、要素が他の要素によって遮られていない状態になるまで待ちます
• 上記のチェックのいずれかで要素がデタッチされた場合に再試行します

クリックの強制

アプリによっては、要素をホバーすると、クリックをインターセプトする別の要素でオーバーレイされるという、自明ではないロジックを使用している場合があります。この動作は、要素が覆われてクリックが別の場所にディスパッチされるバグと区別がつきません。これが発生していることがわかっている場合は、アクション可能性のチェックをバイパスして、クリックを強制できます。

await page.GetByRole(AriaRole.Button).ClickAsync(new() { Force = true });

プログラムによるクリック

実際の条件下でアプリをテストすることに関心がなく、可能な限りあらゆる手段でクリックをシミュレートしたい場合は、HTMLElement.click() の動作を、Locator.DispatchEventAsync() を使用して要素にクリックイベントをディスパッチするだけでトリガーできます。

await page.GetByRole(AriaRole.Button).DispatchEventAsync("click");

文字入力

注意

ほとんどの場合、Locator.FillAsync() でテキストを入力する必要があります。上記の「テキスト入力」セクションを参照してください。ページに特別なキーボード処理がある場合にのみ、文字を入力する必要があります。

Locator.PressSequentiallyAsync() を使用して、実際のキーボードを持つユーザーのように、フィールドに文字を 1 文字ずつ入力します。

// Press keys one by one
await Page.Locator("#area").PressSequentiallyAsync("Hello World!");

このメソッドは、必要なすべてのキーボードイベントを、すべての keydown、keyup、keypress イベントとともに発行します。キーを押す間のオプションの delay を指定して、実際のユーザーの動作をシミュレートすることもできます。

キーとショートカット

// Hit Enter
await page.GetByText("Submit").PressAsync("Enter");

// Dispatch Control+Right
await page.GetByRole(AriaRole.Textbox).PressAsync("Control+ArrowRight");

// Press $ sign on keyboard
await page.GetByRole(AriaRole.Textbox).PressAsync("$");

Locator.PressAsync() メソッドは、選択された要素をフォーカスし、単一のキーストロークを生成します。これは、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").PressAsync("Shift+A");

// <input id=name>
await page.Locator("#name").PressAsync("Shift+ArrowLeft");

"Control+o" や "Control+Shift+T" などのショートカットもサポートされています。修飾子を指定すると、修飾子が押されたままになり、後続のキーが押されます。

大文字を生成するには、Shift-A で大文字の A を指定する必要があることに注意してください。Shift-a は、CapsLock がオンになっているかのように小文字を生成します。

ファイルのアップロード

Locator.SetInputFilesAsync() メソッドを使用して、アップロードする入力ファイルを選択できます。最初の引数は、タイプが "file" の input 要素 を指すことが期待されます。複数のファイルを配列で渡すことができます。ファイルパスの一部が相対パスである場合、それらは現在の作業ディレクトリからの相対パスとして解決されます。空の配列は、選択されたファイルをクリアします。

// Select one file
await page.GetByLabel("Upload file").SetInputFilesAsync("myfile.pdf");

// Select multiple files
await page.GetByLabel("Upload files").SetInputFilesAsync(new[] { "file1.txt", "file12.txt" });

// Select a directory
await page.GetByLabel("Upload directory").SetInputFilesAsync("mydir");

// Remove all the selected files
await page.GetByLabel("Upload file").SetInputFilesAsync(new[] {});

// Upload buffer from memory
await page.GetByLabel("Upload file").SetInputFilesAsync(new FilePayload
{
    Name = "file.txt",
    MimeType = "text/plain",
    Buffer = System.Text.Encoding.UTF8.GetBytes("this is a test"),
});

入力要素を手元にない場合 (動的に作成される場合)、Page.FileChooser イベントを処理するか、アクション時に対応する待機メソッドを使用できます

var fileChooser = page.RunAndWaitForFileChooserAsync(async () =>
{
    await page.GetByLabel("Upload file").ClickAsync();
});
await fileChooser.SetFilesAsync("myfile.pdf");

要素へのフォーカス

フォーカスイベントを処理する動的なページの場合、Locator.FocusAsync() を使用して、指定された要素にフォーカスできます。

await page.GetByLabel("Password").FocusAsync();

ドラッグアンドドロップ

Locator.DragToAsync() を使用して、ドラッグ&ドロップ操作を実行できます。このメソッドは、次のことを行います。

• ドラッグする要素をホバーします。
• 左マウスボタンを押します。
• ドロップを受け取る要素にマウスを移動します。
• 左マウスボタンを離します。

await page.Locator("#item-to-be-dragged").DragToAsync(page.Locator("#item-to-drop-at"));

手動でのドラッグ

ドラッグ操作を正確に制御したい場合は、Locator.HoverAsync()、Mouse.DownAsync()、Mouse.MoveAsync()、Mouse.UpAsync() などの低レベルのメソッドを使用します。

await page.Locator("#item-to-be-dragged").HoverAsync();
await page.Mouse.DownAsync();
await page.Locator("#item-to-drop-at").HoverAsync();
await page.Mouse.UpAsync();

注記

ページが dragover イベントのディスパッチに依存している場合、すべてのブラウザーでそれをトリガーするには、少なくとも 2 回のマウス移動が必要です。2 回目のマウス移動を確実に行うには、Mouse.MoveAsync() または Locator.HoverAsync() を 2 回繰り返します。操作のシーケンスは、ドラッグ要素をホバー、マウスダウン、ドロップ要素をホバー、ドロップ要素を 2 回目にホバー、マウスアップとなります。

スクロール

ほとんどの場合、Playwright はアクションを実行する前に自動的にスクロールします。したがって、明示的にスクロールする必要はありません。

// Scrolls automatically so that button is visible
await page.GetByRole(AriaRole.Button).ClickAsync();

ただし、まれに手動でスクロールする必要がある場合があります。たとえば、「無限リスト」にさらに多くの要素をロードさせたり、特定のスクリーンショットのためにページを配置したりする場合などです。そのような場合、最も確実な方法は、下部に表示したい要素を見つけて、ビューにスクロールすることです。

// Scroll the footer into view, forcing an "infinite list" to load more content
await page.GetByText("Footer text").ScrollIntoViewIfNeededAsync();

スクロールをより正確に制御したい場合は、Mouse.WheelAsync() または Locator.EvaluateAsync() を使用してください

// Position the mouse and scroll with the mouse wheel
await page.GetByTestId("scrolling-container").HoverAsync();
await page.Mouse.WheelAsync(0, 10);

// Alternatively, programmatically scroll a specific element
await page.GetByTestId("scrolling-container").EvaluateAsync("e => e.scrollTop += 100");