Locator

Locatorは、Playwrightの自動ウェイトとリトライ機能の中核となるものです。Locatorは、ページ上の要素を任意のタイミングで検索する方法を表します。Locatorは、page.locator()メソッドで作成できます。

Locatorの詳細はこちら.

---

メソッド

all

バージョン 1.29 で追加 locator.all

locatorが要素のリストを指している場合、これはそれらの各要素を指すlocatorの配列を返します。

注記

locator.all() は、locatorに一致する要素を待機せず、ページに存在するものをすぐに返します。

要素のリストが動的に変化する場合、locator.all() は予測不可能で不安定な結果を生成します。

要素のリストが安定しているが、動的にロードされる場合は、locator.all() を呼び出す前に、リスト全体のロードが完了するのを待ちます。

使用例

for (const li of await page.getByRole('listitem').all())
  await li.click();

戻り値

• Promise<Array<Locator>>#

---

allInnerTexts

バージョン 1.14 で追加 locator.allInnerTexts

一致するすべてのノードの node.innerText 値の配列を返します。

テキストのアサート

ページ上のテキストをアサートする必要がある場合は、不安定さを避けるために、expect(locator).toHaveText() を useInnerText オプション付きで使用することを推奨します。詳細については、アサーションガイドを参照してください。

使用例

const texts = await page.getByRole('link').allInnerTexts();

戻り値

• Promise<Array<string>>#

---

allTextContents

バージョン 1.14 で追加 locator.allTextContents

一致するすべてのノードの node.textContent 値の配列を返します。

テキストのアサート

ページ上のテキストをアサートする必要がある場合は、不安定さを避けるために、expect(locator).toHaveText() を推奨します。詳細については、アサーションガイドを参照してください。

使用例

const texts = await page.getByRole('link').allTextContents();

戻り値

• Promise<Array<string>>#

---

and

バージョン 1.34 で追加 locator.and

このlocatorと引数locatorの両方に一致するlocatorを作成します。

使用例

次の例では、特定のタイトルのボタンを検索します。

const button = page.getByRole('button').and(page.getByTitle('Subscribe'));

引数

• locator Locator#

  一致させる追加のlocator。

戻り値

• Locator#

---

ariaSnapshot

バージョン 1.49 で追加 locator.ariaSnapshot

指定された要素のARIAスナップショットをキャプチャします。ARIAスナップショットと、対応するアサーションであるexpect(locator).toMatchAriaSnapshot()の詳細をご覧ください。

使用例

await page.getByRole('link').ariaSnapshot();

引数

• options Object (オプション)

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<string>#

詳細

このメソッドは、指定された要素のARIAスナップショットをキャプチャします。スナップショットは、要素とその子要素の状態を表す文字列です。スナップショットは、テストで要素の状態をアサートしたり、将来の状態と比較するために使用できます。

ARIAスナップショットは、YAMLマークアップ言語を使用して表現されます。

• オブジェクトのキーは、要素のロールとオプションのアクセシブル名です。
• 値は、テキストコンテンツまたは子要素の配列のいずれかです。
• 一般的な静的テキストは、text キーで表すことができます。

以下は、HTMLマークアップと対応するARIAスナップショットです。

<ul aria-label="Links">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
<ul>

- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

---

blur

バージョン 1.28 で追加 locator.blur

要素に対して blur を呼び出します。

使用例

await locator.blur();
await locator.blur(options);

引数

• options Object (オプション)

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

---

boundingBox

バージョン 1.14 で追加 locator.boundingBox

このメソッドは、locatorに一致する要素のバウンディングボックスを返します。要素が表示されていない場合は null を返します。バウンディングボックスは、メインフレームのビューポート (通常はブラウザウィンドウと同じ) を基準に計算されます。

使用例

const box = await page.getByRole('button').boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);

引数

• options Object (オプション)

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<null | Object>#

  • x number

    要素のx座標 (ピクセル単位)。

  • y number

    要素のy座標 (ピクセル単位)。

  • width number

    要素の幅 (ピクセル単位)。

  • height number

    要素の高さ (ピクセル単位)。

詳細

スクロールは、Element.getBoundingClientRect と同様に、返されるバウンディングボックスに影響を与えます。つまり、x および/または y が負の数になる可能性があります。

子フレームの要素は、Element.getBoundingClientRect とは異なり、メインフレームを基準としたバウンディングボックスを返します。

ページが静的であると仮定すると、バウンディングボックスの座標を入力の実行に使用しても安全です。たとえば、次のスニペットは要素の中央をクリックします。

---

check

バージョン 1.14 で追加 locator.check

チェックボックスまたはラジオ要素がチェックされていることを確認します。

使用例

await page.getByRole('checkbox').check();

引数

• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の可視ポイントの一部を使用します。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (オプション)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

• Promise<void>#

詳細

次のステップを実行します。

1. 要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドは例外をスローします。要素がすでにチェックされている場合、このメソッドはすぐに返ります。
2. アクション実行可能性チェックを要素に対して待機します。ただし、force オプションが設定されている場合は除きます。
3. 必要に応じて、要素をビューにスクロールします。
4. page.mouse を使用して、要素の中央をクリックします。
5. 要素がチェックされたことを確認します。そうでない場合、このメソッドは例外をスローします。

アクション中に要素がDOMから切り離された場合、このメソッドは例外をスローします。

指定された timeout 時間内にすべてのステップが完了しなかった場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロにすると、これは無効になります。

---

clear

バージョン 1.28 で追加 locator.clear

入力フィールドをクリアします。

使用例

await page.getByRole('textbox').clear();

引数

• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

詳細

このメソッドは、アクション実行可能性チェックを待機し、要素にフォーカスを当て、クリアしてから、クリア後に input イベントをトリガーします。

ターゲット要素が <input>、<textarea>、または [contenteditable] 要素でない場合、このメソッドはエラーをスローします。ただし、要素が、関連付けられた control を持つ <label> 要素内にある場合、代わりにコントロールがクリアされます。

---

click

バージョン 1.14 で追加 locator.click

要素をクリックします。

使用例

ボタンをクリック

await page.getByRole('button').click();

キャンバス上の特定の場所をShift+右クリック

await page.locator('canvas').click({
  button: 'right',
  modifiers: ['Shift'],
  position: { x: 23, y: 32 },
});

引数

• options Object (オプション)

  • button "left" | "right" | "middle" (オプション)#

    デフォルトは left です。

  • clickCount number (オプション)#

    デフォルトは 1 です。UIEvent.detail を参照してください。

  • delay number (オプション)#

    mousedown と mouseup の間の待機時間 (ミリ秒単位)。デフォルトは 0 です。

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを確認し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows および Linux では "Control" に、macOS では "Meta" に解決されます。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは、将来デフォルトで true になります。

    ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機しています。このフラグを設定すると、待機をオプトアウトできます。このオプションが必要になるのは、アクセスできないページに移動するなど、例外的なケースのみです。デフォルトは false です。

  • position Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の可視ポイントの一部を使用します。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (オプション)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。キーボード modifiers は、trial に関係なく押され、これらのキーが押されたときにのみ表示される要素のテストを可能にすることに注意してください。

戻り値

• Promise<void>#

詳細

このメソッドは、次の手順を実行して要素をクリックします。

1. アクション実行可能性チェックを要素に対して待機します。ただし、force オプションが設定されている場合は除きます。
2. 必要に応じて、要素をビューにスクロールします。
3. page.mouse を使用して、要素の中央、または指定された position をクリックします。
4. 開始されたナビゲーションが成功または失敗するのを待ちます。ただし、noWaitAfter オプションが設定されている場合は除きます。

アクション中に要素がDOMから切り離された場合、このメソッドは例外をスローします。

指定された timeout 時間内にすべてのステップが完了しなかった場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロにすると、これは無効になります。

---

contentFrame

バージョン 1.43 で追加 locator.contentFrame

このlocatorと同じ iframe を指す FrameLocator オブジェクトを返します。

どこかで取得した Locator オブジェクトがあり、後でフレーム内のコンテンツを操作したい場合に便利です。

逆の操作には、frameLocator.owner() を使用します。

使用例

const locator = page.locator('iframe[name="embedded"]');
// ...
const frameLocator = locator.contentFrame();
await frameLocator.getByRole('button').click();

戻り値

• FrameLocator#

---

count

バージョン 1.14 で追加 locator.count

locatorに一致する要素の数を返します。

countのアサート

ページ上の要素の数をアサートする必要がある場合は、不安定さを避けるために、expect(locator).toHaveCount() を推奨します。詳細については、アサーションガイドを参照してください。

使用例

const count = await page.getByRole('listitem').count();

戻り値

• Promise<number>#

---

dblclick

バージョン 1.14 で追加 locator.dblclick

要素をダブルクリックします。

使用例

await locator.dblclick();
await locator.dblclick(options);

引数

• options Object (オプション)

  • button "left" | "right" | "middle" (オプション)#

    デフォルトは left です。

  • delay number (オプション)#

    mousedown と mouseup の間の待機時間 (ミリ秒単位)。デフォルトは 0 です。

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを確認し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows および Linux では "Control" に、macOS では "Meta" に解決されます。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の可視ポイントの一部を使用します。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (オプション)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。キーボード modifiers は、trial に関係なく押され、これらのキーが押されたときにのみ表示される要素のテストを可能にすることに注意してください。

戻り値

• Promise<void>#

詳細

このメソッドは、次の手順を実行して要素をダブルクリックします。

1. アクション実行可能性チェックを要素に対して待機します。ただし、force オプションが設定されている場合は除きます。
2. 必要に応じて、要素をビューにスクロールします。
3. page.mouse を使用して、要素の中央、または指定された position をダブルクリックします。

アクション中に要素がDOMから切り離された場合、このメソッドは例外をスローします。

指定された timeout 時間内にすべてのステップが完了しなかった場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロにすると、これは無効になります。

注記

element.dblclick() は、2つの click イベントと1つの dblclick イベントをディスパッチします。

---

dispatchEvent

バージョン 1.14 で追加 locator.dispatchEvent

一致する要素に対してプログラムでイベントをディスパッチします。

使用例

await locator.dispatchEvent('click');

引数

• type string#

  DOMイベントタイプ: "click", "dragstart" など。

• eventInit EvaluationArgument (オプション)#

  オプションのイベント固有の初期化プロパティ。

• options Object (オプション)

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

詳細

上記のスニペットは、要素に対して click イベントをディスパッチします。要素の表示状態に関係なく、click がディスパッチされます。これは、element.click() を呼び出すことと同等です。

内部的には、指定された type に基づいてイベントのインスタンスを作成し、eventInit プロパティで初期化し、要素にディスパッチします。イベントは、デフォルトで composed、cancelable、およびバブルです。

eventInit はイベント固有であるため、初期プロパティのリストについては、イベントのドキュメントを参照してください。

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• Event
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

ライブオブジェクトをイベントに渡したい場合は、JSHandle をプロパティ値として指定することもできます。

const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await locator.dispatchEvent('dragstart', { dataTransfer });

---

dragTo

バージョン 1.18 で追加 locator.dragTo

ソース要素をターゲット要素に向かってドラッグし、ドロップします。

使用例

const source = page.locator('#source');
const target = page.locator('#target');

await source.dragTo(target);
// or specify exact positions relative to the top-left corners of the elements:
await source.dragTo(target, {
  sourcePosition: { x: 34, y: 7 },
  targetPosition: { x: 10, y: 20 },
});

引数

• target Locator#

  ドラッグ先の要素のlocator。

• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • sourcePosition Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準としたこのポイントでソース要素をクリックします。指定しない場合は、要素の可視ポイントの一部が使用されます。

  • targetPosition Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準としたこのポイントでターゲット要素にドロップします。指定しない場合は、要素の可視ポイントの一部が使用されます。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (オプション)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

• Promise<void>#

詳細

このメソッドは、locatorを別のターゲットlocatorまたはターゲット位置にドラッグします。最初にソース要素に移動し、mousedown を実行してから、ターゲット要素または位置に移動して mouseup を実行します。

---

evaluate

バージョン 1.14 で追加 locator.evaluate

一致する要素を引数として、ページ内でJavaScriptコードを実行します。

使用例

引数

• pageFunction function | string#

  ページコンテキストで評価される関数。

• arg EvaluationArgument (オプション)#

  pageFunction に渡すオプションの引数。

• options Object (オプション)

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<Serializable>#

詳細

指定された要素を第一引数、argを第二引数として呼び出されたpageFunctionの戻り値を返します。

もしpageFunctionがPromiseを返した場合、このメソッドはPromiseが解決されるのを待ってその値を返します。

pageFunctionが例外をスローまたはリジェクトした場合、このメソッドは例外をスローします。

---

evaluateAll

バージョン 1.14 で追加 locator.evaluateAll

ページ内でJavaScriptコードを実行し、一致するすべての要素を引数として受け取ります。

使用例

const locator = page.locator('div');
const moreThanTen = await locator.evaluateAll((divs, min) => divs.length > min, 10);

引数

• pageFunction function | string#

  ページコンテキストで評価される関数。

• arg EvaluationArgument (任意)#

  pageFunctionに渡すオプションの引数です。

戻り値

• Promise<Serializable>#

詳細

一致するすべての要素の配列を第一引数、argを第二引数として呼び出されたpageFunctionの戻り値を返します。

もしpageFunctionがPromiseを返した場合、このメソッドはPromiseが解決されるのを待ってその値を返します。

pageFunctionが例外をスローまたはリジェクトした場合、このメソッドは例外をスローします。

---

evaluateHandle

バージョン 1.14 で追加 locator.evaluateHandle

ページ内でJavaScriptコードを実行し、一致する要素を引数として受け取り、結果とともにJSHandleを返します。

使用例

await locator.evaluateHandle(pageFunction);
await locator.evaluateHandle(pageFunction, arg, options);

引数

• pageFunction function | string#

  ページコンテキストで評価される関数。

• arg EvaluationArgument (任意)#

  pageFunctionに渡すオプションの引数です。

• options Object (オプション)

  • timeout number (任意)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<JSHandle>#

詳細

指定された要素を第一引数、argを第二引数として呼び出されたpageFunctionの戻り値をJSHandleとして返します。

locator.evaluate()とlocator.evaluateHandle()の唯一の違いは、locator.evaluateHandle()がJSHandleを返すことです。

もしpageFunctionがPromiseを返した場合、このメソッドはPromiseが解決されるのを待ってその値を返します。

pageFunctionが例外をスローまたはリジェクトした場合、このメソッドは例外をスローします。

詳細については、page.evaluateHandle()を参照してください。

---

fill

バージョン 1.14 で追加 locator.fill

入力フィールドに値を設定します。

使用例

await page.getByRole('textbox').fill('example value');

引数

• value string#

  <input>、<textarea>、または[contenteditable]要素に設定する値です。

• options Object (オプション)

  • force boolean (任意)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • noWaitAfter boolean (任意)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout number (任意)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

詳細

このメソッドは、操作可能性のチェックを待ち、要素にフォーカスし、入力し、入力後にinputイベントを発生させます。入力フィールドをクリアするために空の文字列を渡すことができることに注意してください。

ターゲット要素が<input>、<textarea>、または[contenteditable]要素でない場合、このメソッドはエラーをスローします。ただし、要素が、関連付けられたcontrolを持つ<label>要素内にある場合、代わりにコントロールが入力されます。

きめ細かいキーボードイベントを送信するには、locator.pressSequentially()を使用してください。

---

filter

バージョン 1.22 で追加 locator.filter

このメソッドは、オプションに従って既存のlocatorを絞り込みます。たとえば、テキストでフィルタリングします。複数回フィルタリングするためにチェーンできます。

使用例

const rowLocator = page.locator('tr');
// ...
await rowLocator
    .filter({ hasText: 'text in column 1' })
    .filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
    .screenshot();

引数

• options Object (オプション)

  • has Locator (任意)#

    この相対locatorに一致する要素を含む結果にメソッドの結果を絞り込みます。たとえば、text=Playwrightを持つarticleは、<article><div>Playwright</div></article>に一致します。

    内部locatorは、外部locatorに対する**相対的である必要**があり、ドキュメントルートではなく、外部locatorの一致からクエリが開始されます。たとえば、<article><content><div>Playwright</div></content></article>内のdivを持つcontentを見つけることができます。ただし、article divを持つcontentを探すことは失敗します。内部locatorは相対的でなければならず、contentの外側の要素を使用すべきではないためです。

    外部locatorと内部locatorは同じフレームに属している必要があることに注意してください。内部locatorはFrameLocatorを含んではいけません。

  • hasNot Locator (任意)バージョン 1.33 で追加#

    内部locatorに一致する要素を含まない要素に一致します。内部locatorは外部locatorに対してクエリされます。たとえば、divを持たないarticleは、<article><span>Playwright</span></article>に一致します。

    外部locatorと内部locatorは同じフレームに属している必要があることに注意してください。内部locatorはFrameLocatorを含んではいけません。

  • hasNotText string | RegExp (任意)バージョン 1.33 で追加#

    指定されたテキストを子要素または子孫要素のどこかに含まない要素に一致します。stringが渡されると、マッチングは大文字と小文字を区別せず、部分文字列を検索します。

  • hasText string | RegExp (任意)#

    指定されたテキストを子要素または子孫要素のどこかに含む要素に一致します。stringが渡されると、マッチングは大文字と小文字を区別せず、部分文字列を検索します。たとえば、"Playwright"は<article><div>Playwright</div></article>に一致します。

  • visible boolean (任意)バージョン 1.51 で追加#

    可視または不可視の要素のみに一致します。

戻り値

• Locator#

---

first

バージョン 1.14 で追加 locator.first

最初に見つかった要素へのlocatorを返します。

使用例

locator.first();

戻り値

• Locator#

---

focus

バージョン 1.14 で追加 locator.focus

一致する要素でfocusを呼び出します。

使用例

await locator.focus();
await locator.focus(options);

引数

• options Object (オプション)

  • timeout number (任意)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

---

frameLocator

バージョン 1.17 で追加 locator.frameLocator

iframeを操作する場合、iframeに入り、そのiframe内の要素を特定できるフレームlocatorを作成できます。

使用例

const locator = page.frameLocator('iframe').getByText('Submit');
await locator.click();

引数

• selector string#

  DOM要素を解決するときに使用するセレクター。

戻り値

• FrameLocator#

---

getAttribute

バージョン 1.14 で追加 locator.getAttribute

一致する要素の属性値を返します。

属性のアサーション

要素の属性をアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toHaveAttribute()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

使用例

await locator.getAttribute(name);
await locator.getAttribute(name, options);

引数

• name string#

  値を取得する属性名。

• options Object (オプション)

  • timeout number (任意)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<null | string>#

---

getByAltText

バージョン 1.27 で追加 locator.getByAltText

altテキストで要素を特定できます。

使用例

たとえば、このメソッドはaltテキスト"Playwright logo"で画像を見つけます。

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

引数

• text string | RegExp#

  要素を特定するためのテキスト。

• options Object (オプション)

  • exact boolean (任意)#

    完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体を比較します。デフォルトはfalseです。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

• Locator#

---

getByLabel

バージョン 1.27 で追加 locator.getByLabel

関連付けられた<label>またはaria-labelledby要素のテキスト、またはaria-label属性によって入力要素を特定できます。

使用例

たとえば、このメソッドは次のDOMでラベル"Username"と"Password"で入力を検索します。

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

引数

• text string | RegExp#

  要素を特定するためのテキスト。

• options Object (オプション)

  • exact boolean (任意)#

    完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体を比較します。デフォルトはfalseです。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

• Locator#

---

getByPlaceholder

バージョン 1.27 で追加 locator.getByPlaceholder

プレースホルダーテキストで入力要素を特定できます。

使用例

たとえば、次のDOM構造を考えてみましょう。

<input type="email" placeholder="name@example.com" />

プレースホルダーテキストで特定した後、入力を入力できます。

await page
    .getByPlaceholder('name@example.com')
    .fill('playwright@microsoft.com');

引数

• text string | RegExp#

  要素を特定するためのテキスト。

• options Object (オプション)

  • exact boolean (任意)#

    完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体を比較します。デフォルトはfalseです。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

• Locator#

---

getByRole

バージョン 1.27 で追加 locator.getByRole

ARIA role、ARIA属性、およびアクセシブルネームによって要素を特定できます。

使用例

次のDOM構造を考えてみましょう。

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

各要素を暗黙のロールで特定できます。

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).click();

引数

• role "alert" | "alertdialog" | "application" | "article" | "banner" | "blockquote" | "button" | "caption" | "cell" | "checkbox" | "code" | "columnheader" | "combobox" | "complementary" | "contentinfo" | "definition" | "deletion" | "dialog" | "directory" | "document" | "emphasis" | "feed" | "figure" | "form" | "generic" | "grid" | "gridcell" | "group" | "heading" | "img" | "insertion" | "link" | "list" | "listbox" | "listitem" | "log" | "main" | "marquee" | "math" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "navigation" | "none" | "note" | "option" | "paragraph" | "presentation" | "progressbar" | "radio" | "radiogroup" | "region" | "row" | "rowgroup" | "rowheader" | "scrollbar" | "search" | "searchbox" | "separator" | "slider" | "spinbutton" | "status" | "strong" | "subscript" | "superscript" | "switch" | "tab" | "table" | "tablist" | "tabpanel" | "term" | "textbox" | "time" | "timer" | "toolbar" | "tooltip" | "tree" | "treegrid" | "treeitem"#

  必須のariaロール。

• options Object (オプション)

  • checked boolean (任意)#

    通常aria-checkedまたはネイティブ<input type=checkbox>コントロールによって設定される属性。

    aria-checkedの詳細をご覧ください。

  • disabled boolean (任意)#

    通常aria-disabledまたはdisabledによって設定される属性。

    注記

    他のほとんどの属性とは異なり、disabledはDOM階層を介して継承されます。aria-disabledの詳細をご覧ください。

  • exact boolean (任意)バージョン 1.28 で追加#

    nameが完全に一致するかどうか：大文字と小文字を区別し、文字列全体を比較します。デフォルトはfalseです。nameが正規表現の場合は無視されます。完全一致でも空白はトリムされることに注意してください。

  • expanded boolean (任意)#

    通常aria-expandedによって設定される属性。

    aria-expandedの詳細をご覧ください。

  • includeHidden boolean (任意)#

    非表示要素を一致させるかどうかを制御するオプション。デフォルトでは、ARIAで定義されているように、非表示でない要素のみがロールセレクターによって一致します。

    aria-hiddenの詳細をご覧ください。

  • level number (任意)#

    通常、heading、listitem、row、treeitemロールに存在する数値属性で、<h1>-<h6>要素のデフォルト値があります。

    aria-levelの詳細をご覧ください。

  • name string | RegExp (任意)#

    アクセシブルネームに一致させるためのオプション。デフォルトでは、マッチングは大文字と小文字を区別せず、部分文字列を検索します。この動作を制御するにはexactを使用してください。

    アクセシブルネームの詳細をご覧ください。

  • pressed boolean (任意)#

    通常aria-pressedによって設定される属性。

    aria-pressedの詳細をご覧ください。

  • selected boolean (任意)#

    通常aria-selectedによって設定される属性。

    aria-selectedの詳細をご覧ください。

戻り値

• Locator#

詳細

ロールセレクターは、アクセシビリティ監査および適合性テストを**置き換えるものではありません**が、ARIAガイドラインに関する早期のフィードバックを提供します。

多くのhtml要素には、ロールセレクターによって認識される暗黙的に定義されたロールがあります。すべてのサポートされているロールはこちらにあります。ARIAガイドラインは、デフォルト値にroleやaria-*属性を設定して、暗黙的なロールと属性を複製することを**推奨していません**。

---

getByTestId

バージョン 1.27 で追加 locator.getByTestId

テストIDで要素を特定します。

使用例

次のDOM構造を考えてみましょう。

<button data-testid="directions">Itinéraire</button>

要素をテストIDで特定できます。

await page.getByTestId('directions').click();

引数

• testId string | RegExp#

  要素を特定するためのID。

戻り値

• Locator#

詳細

デフォルトでは、data-testid属性がテストIDとして使用されます。必要に応じて別のテストID属性を設定するには、selectors.setTestIdAttribute()を使用してください。

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

---

getByText

バージョン 1.27 で追加 locator.getByText

指定されたテキストを含む要素を特定できます。

アクセシブルロールなどの別の基準で一致させ、テキストコンテンツでフィルタリングできるlocator.filter()も参照してください。

使用例

次のDOM構造を考えてみましょう。

<div>Hello <span>world</span></div>
<div>Hello</div>

テキスト部分文字列、完全な文字列、または正規表現で特定できます。

// Matches <span>
page.getByText('world');

// Matches first <div>
page.getByText('Hello world');

// Matches second <div>
page.getByText('Hello', { exact: true });

// Matches both <div>s
page.getByText(/Hello/);

// Matches second <div>
page.getByText(/^hello$/i);

引数

• text string | RegExp#

  要素を特定するためのテキスト。

• options Object (オプション)

  • exact boolean (任意)#

    完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体を比較します。デフォルトはfalseです。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

• Locator#

詳細

テキストによるマッチングは、完全一致であっても常に空白を正規化します。たとえば、複数のスペースを1つにし、改行をスペースに変え、先頭と末尾の空白を無視します。

buttonおよびsubmitタイプの入力要素は、テキストコンテンツの代わりにvalueによって一致します。たとえば、テキスト"Log in"で特定すると、<input type=button value="Log in">に一致します。

---

getByTitle

バージョン 1.27 で追加 locator.getByTitle

title属性で要素を特定できます。

使用例

次のDOM構造を考えてみましょう。

<span title='Issues count'>25 issues</span>

タイトルテキストで特定した後、issue数を確認できます。

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

引数

• text string | RegExp#

  要素を特定するためのテキスト。

• options Object (オプション)

  • exact boolean (任意)#

    完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体を比較します。デフォルトはfalseです。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

• Locator#

---

highlight

バージョン 1.20 で追加 locator.highlight

画面上の対応する要素を強調表示します。デバッグに役立ちます。locator.highlight()を使用するコードをコミットしないでください。

使用例

await locator.highlight();

戻り値

• Promise<void>#

---

hover

バージョン 1.14 で追加 locator.hover

一致する要素にホバーします。

使用例

await page.getByRole('link').hover();

引数

• options Object (オプション)

  • force boolean (任意)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (任意)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを確認し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows および Linux では "Control" に、macOS では "Meta" に解決されます。

  • noWaitAfter boolean (任意)バージョン 1.28 で追加#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Object (任意)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の可視ポイントの一部を使用します。

  • timeout number (任意)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (任意)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。キーボード modifiers は、trial に関係なく押され、これらのキーが押されたときにのみ表示される要素のテストを可能にすることに注意してください。

戻り値

• Promise<void>#

詳細

このメソッドは、次の手順を実行して要素にホバーします。

1. Wait for actionability checks on the element, unless force option is set。
2. 必要に応じて、要素をビューにスクロールします。
3. 要素の操作性チェックを待機します。forceオプションが設定されている場合は除きます。

アクション中に要素がDOMから切り離された場合、このメソッドは例外をスローします。

page.mouseを使用して、要素の中心、または指定されたpositionにマウスカーソルを合わせます。

---

指定されたtimeout時間内にすべてのステップが完了しなかった場合、このメソッドはTimeoutErrorをスローします。タイムアウトにゼロを渡すと、これは無効になります。

バージョン 1.14 で追加 innerHTML

locator.innerHTML

使用例

await locator.innerHTML();
await locator.innerHTML(options);

引数

• options Object (オプション)

  • element.innerHTMLを返します。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<string>#

バージョン 1.14 で追加 innerText

locator.innerText

テキストのアサート

ページ上のテキストをアサートする必要がある場合は、不安定さを避けるために、expect(locator).toHaveText() を useInnerText オプション付きで使用することを推奨します。詳細については、アサーションガイドを参照してください。

使用例

await locator.innerText();
await locator.innerText(options);

引数

• options Object (オプション)

  • element.innerTextを返します。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<string>#

バージョン 1.14 で追加 inputValue

locator.inputValue

一致する<input>、<textarea>、または<select>要素の値を返します。

値のアサート

使用例

const value = await page.getByRole('textbox').inputValue();

引数

• options Object (オプション)

  • 入力値をアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toHaveValue()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

詳細

Promise<string>#

---

入力、テキストエリア、またはセレクトではない要素をスローします。ただし、要素が関連付けられたcontrolを持つ<label>要素内にある場合、コントロールの値を返します。

バージョン 1.14 で追加 isChecked

locator.isChecked

要素がチェックされているかどうかを返します。要素がチェックボックスまたはラジオ入力でない場合はエラーをスローします。

チェック状態のアサート

使用例

const checked = await page.getByRole('checkbox').isChecked();

引数

• options Object (オプション)

  • チェックボックスがチェックされていることをアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toBeChecked()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<boolean>#

バージョン 1.14 で追加 isDisabled

locator.isDisabled

要素が無効になっているかどうかを返します。有効の反対です。

無効状態のアサート

使用例

const disabled = await page.getByRole('button').isDisabled();

引数

• options Object (オプション)

  • 要素が無効になっていることをアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toBeDisabled()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<boolean>#

バージョン 1.14 で追加 isEditable

locator.isEditable

要素が編集可能かどうかを返します。ターゲット要素が<input>、<textarea>、<select>、[contenteditable]ではなく、[aria-readonly]を許可するロールを持っていない場合、このメソッドはエラーをスローします。

編集可能状態のアサート

使用例

const editable = await page.getByRole('textbox').isEditable();

引数

• options Object (オプション)

  • 要素が編集可能であることをアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toBeEditable()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<boolean>#

バージョン 1.14 で追加 isEnabled

locator.isEnabled

要素が有効かどうかを返します。

有効状態のアサート

使用例

const enabled = await page.getByRole('button').isEnabled();

引数

• options Object (オプション)

  • 要素が有効であることをアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toBeEnabled()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<boolean>#

バージョン 1.14 で追加 isHidden

locator.isHidden

要素が非表示かどうかを返します。表示の反対です。

可視性のアサート

使用例

const hidden = await page.getByRole('button').isHidden();

引数

• options Object (オプション)

  • 要素が非表示であることをアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toBeHidden()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

    非推奨

    timeout number (オプション)#

戻り値

• このオプションは無視されます。locator.isHidden()は、要素が非表示になるのを待たずにすぐに返します。

---

Promise<boolean>#

バージョン 1.14 で追加 isVisible

locator.isVisible

要素が非表示かどうかを返します。表示の反対です。

要素が表示かどうかを返します。

使用例

const visible = await page.getByRole('button').isVisible();

引数

• options Object (オプション)

  • 要素が表示されていることをアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toBeVisible()を使用することを推奨します。詳細については、アサーションガイドを参照してください。

    非推奨

    timeout number (オプション)#

戻り値

• このオプションは無視されます。locator.isVisible()は、要素が表示されるのを待たずにすぐに返します。

---

Promise<boolean>#

バージョン 1.14 で追加 last

locator.last

使用例

const banana = await page.getByRole('listitem').last();

戻り値

• 最後に一致する要素へのロケーターを返します。

---

Locator#

バージョン 1.14 で追加 locator

locator.locator

Locatorの詳細はこちら.

使用例

locator.locator(selectorOrLocator);
locator.locator(selectorOrLocator, options);

引数

• このメソッドは、ロケーターのサブツリー内で指定されたセレクターに一致する要素を検索します。また、locator.filter()メソッドと同様に、フィルターオプションも受け入れます。

  selectorOrLocator string | Locator#

• options Object (オプション)

  • DOM要素の解決に使用するセレクターまたはロケーター。

    この相対locatorに一致する要素を含む結果にメソッドの結果を絞り込みます。たとえば、text=Playwrightを持つarticleは、<article><div>Playwright</div></article>に一致します。

    内部locatorは、外部locatorに対する**相対的である必要**があり、ドキュメントルートではなく、外部locatorの一致からクエリが開始されます。たとえば、<article><content><div>Playwright</div></content></article>内のdivを持つcontentを見つけることができます。ただし、article divを持つcontentを探すことは失敗します。内部locatorは相対的でなければならず、contentの外側の要素を使用すべきではないためです。

    外部locatorと内部locatorは同じフレームに属している必要があることに注意してください。内部locatorはFrameLocatorを含んではいけません。

  • hasNot Locator (任意)バージョン 1.33 で追加#

    内部locatorに一致する要素を含まない要素に一致します。内部locatorは外部locatorに対してクエリされます。たとえば、divを持たないarticleは、<article><span>Playwright</span></article>に一致します。

    外部locatorと内部locatorは同じフレームに属している必要があることに注意してください。内部locatorはFrameLocatorを含んではいけません。

  • hasNotText string | RegExp (任意)バージョン 1.33 で追加#

    指定されたテキストを子要素または子孫要素のどこかに含まない要素に一致します。stringが渡されると、マッチングは大文字と小文字を区別せず、部分文字列を検索します。

  • has Locator (オプション)#

    指定されたテキストを子要素または子孫要素のどこかに含む要素に一致します。stringが渡されると、マッチングは大文字と小文字を区別せず、部分文字列を検索します。たとえば、"Playwright"は<article><div>Playwright</div></article>に一致します。

戻り値

• hasText string | RegExp (オプション)#

---

Locator#

バージョン 1.14 で追加 nth

locator.nth

使用例

const banana = await page.getByRole('listitem').nth(2);

引数

• n番目に一致する要素へのロケーターを返します。ゼロベースであり、nth(0)は最初の要素を選択します。

戻り値

• index number#

---

Locator#

バージョン 1.33 で追加 or

locator.or

2つのロケーターのいずれかまたは両方に一致するすべての要素に一致するロケーターを作成します。

使用例

両方のロケーターが何かに一致する場合、結果のロケーターには複数のマッチが含まれる可能性があり、ロケーターストrictness違反が発生する可能性があることに注意してください。

注記

「新しいメール」ボタンをクリックしたいが、代わりにセキュリティ設定ダイアログが表示されるシナリオを考えてみましょう。この場合、「新しいメール」ボタンまたはダイアログのいずれかを待機し、それに応じて対応できます。

const newEmail = page.getByRole('button', { name: 'New' });
const dialog = page.getByText('Confirm security settings');
await expect(newEmail.or(dialog).first()).toBeVisible();
if (await dialog.isVisible())
  await page.getByRole('button', { name: 'Dismiss' }).click();
await newEmail.click();

引数

• 「新しいメール」ボタンとセキュリティダイアログの両方が画面に表示される場合、「or」ロケーターは両方に一致し、「strict mode violation」エラーがスローされる可能性があります。この場合、locator.first()を使用して、それらの1つのみを一致させることができます。

  locator Locator#

戻り値

• 一致させる代替ロケーター。

---

Locator#

page 追加: v1.19

locator.page

使用例

locator.page();

戻り値

• このロケーターが属するページ。

---

Page#

バージョン 1.14 で追加 press

locator.press

使用例

await page.getByRole('textbox').press('Backspace');

引数

• 一致する要素にフォーカスし、キーの組み合わせを押します。

  key string#

• options Object (オプション)

  • 押すキーの名前、またはArrowLeftやaなどの生成する文字。

    delay number (オプション)#

  • keydownとkeyupの間隔 (ミリ秒単位)。デフォルトは0です。

    非推奨

    このオプションは、将来デフォルトで true になります。

    ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機しています。このフラグを設定すると、待機をオプトアウトできます。このオプションが必要になるのは、アクセスできないページに移動するなど、例外的なケースのみです。デフォルトは false です。

  • noWaitAfter boolean (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

詳細

Promise<void>#

要素にフォーカスし、keyboard.down()とkeyboard.up()を使用します。

keyは、意図されたkeyboardEvent.key値、またはテキストを生成するための単一の文字を指定できます。key値のスーパーセットは、こちらにあります。キーの例は次のとおりです。

F1 - F12、Digit0- Digit9、KeyA- KeyZ、Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、ArrowUpなど。

次の修飾子ショートカットもサポートされています: Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMetaは、WindowsおよびLinuxではControlに、macOSではMetaに解決されます。

Shiftキーを押しながらにすると、keyに対応するテキストが大文字で入力されます。

keyが単一の文字の場合、大文字と小文字が区別されるため、値aとAはそれぞれ異なるテキストを生成します。

---

key: "Control+o"、key: "Control++、またはkey: "Control+Shift+T"のようなショートカットもサポートされています。修飾子で指定すると、修飾子が押され、後続のキーが押されている間、保持されます。

pressSequentially 追加: v1.38

locator.pressSequentially

ヒント

ほとんどの場合、代わりにlocator.fill()を使用する必要があります。ページに特別なキーボード処理がある場合にのみ、キーを1つずつ押す必要があります。

要素にフォーカスし、テキスト内の各文字に対してkeydown、keypress/input、およびkeyupイベントを送信します。

使用例

await locator.pressSequentially('Hello'); // Types instantly
await locator.pressSequentially('World', { delay: 100 }); // Types slower, like a user

ControlやArrowDownのような特殊キーを押すには、locator.press()を使用します。

const locator = page.getByLabel('Password');
await locator.pressSequentially('my password');
await locator.press('Enter');

引数

• テキストフィールドに入力してからフォームを送信する例

  text string#

• options Object (オプション)

  • フォーカスされた要素に順番に押す文字の文字列。

    delay number (オプション)#

  • キー押下の間隔 (ミリ秒単位)。デフォルトは0です。

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • noWaitAfter boolean (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<void>#

バージョン 1.14 で追加 screenshot

locator.screenshot

使用例

await page.getByRole('link').screenshot();

ロケーターに一致する要素のスクリーンショットを撮ります。

await page.getByRole('link').screenshot({ animations: 'disabled', path: 'link.png' });

引数

• options Object (オプション)

  • アニメーションを無効にしてスクリーンショットをファイルに保存する

    animations "disabled" | "allow" (オプション)#

    • "disabled"に設定すると、CSSアニメーション、CSSトランジション、およびWebアニメーションを停止します。アニメーションは、その期間に応じて異なる扱いを受けます。
    • 有限アニメーションは完了まで早送りされるため、transitionendイベントが発生します。

    無限アニメーションは初期状態にキャンセルされ、スクリーンショット後に再度再生されます。

  • デフォルトは、アニメーションをそのままにする"allow"です。

    caret "hide" | "initial" (オプション)#

  • "hide"に設定すると、スクリーンショットはテキストカーソルを非表示にします。"initial"に設定すると、テキストカーソルの動作は変更されません。デフォルトは"hide"です。

    mask Array<Locator> (オプション)#

  • スクリーンショットを撮るときにマスクするロケーターを指定します。マスクされた要素は、ピンク色のボックス#FF00FF（maskColorでカスタマイズ）でオーバーレイされ、そのバウンディングボックスを完全に覆います。マスクは非表示の要素にも適用されます。表示されている要素のみを一致させるを参照して、それを無効にしてください。maskColor string (オプション)#

    追加: v1.35

  • マスクされた要素のオーバーレイボックスの色を、CSSカラー形式で指定します。デフォルトの色はピンク#FF00FFです。

    omitBackground boolean (オプション)#

  • デフォルトの白い背景を非表示にし、透明度のあるスクリーンショットをキャプチャできるようにします。jpeg画像には適用されません。デフォルトはfalseです。

    path string (オプション)#

  • 画像を保存するファイルパス。スクリーンショットのタイプは、ファイル拡張子から推測されます。pathが相対パスの場合、現在の作業ディレクトリからの相対パスとして解決されます。パスが指定されていない場合、画像はディスクに保存されません。

    quality number (オプション)#

  • 画像の品質、0〜100の間。png画像には適用されません。

    scale "css" | "device" (オプション)#

    "css"に設定すると、スクリーンショットはページ上のCSSピクセルごとに1ピクセルになります。高DPIデバイスの場合、これによりスクリーンショットのサイズが小さくなります。"device"オプションを使用すると、デバイスピクセルごとに1ピクセルが生成されるため、高DPIデバイスのスクリーンショットは2倍以上の大きさになります。

  • デフォルトは"device"です。style string (オプション)#

    追加: v1.41

  • スクリーンショットを作成中に適用するスタイルシートのテキスト。これは、動的な要素を非表示にしたり、要素を非表示にしたり、プロパティを変更して、再現可能なスクリーンショットを作成するのに役立ちます。このスタイルシートはShadow DOMを貫通し、内部フレームに適用されます。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • timeout number (オプション)#

    type "png" | "jpeg" (オプション)#

戻り値

• スクリーンショットのタイプを指定します。デフォルトはpngです。

詳細

Promise<Buffer>#

このメソッドは、ロケーターに一致する特定の要素のサイズと位置にクリップされたページのスクリーンショットをキャプチャします。要素が他の要素で覆われている場合、スクリーンショットに実際に表示されません。要素がスクロール可能なコンテナーの場合、現在スクロールされているコンテンツのみがスクリーンショットに表示されます。

このメソッドは、操作性チェックを待機し、スクリーンショットを撮る前に要素をビューにスクロールします。要素がDOMから切り離されている場合、メソッドはエラーをスローします。

---

キャプチャされたスクリーンショットを含むバッファーを返します。

バージョン 1.14 で追加 scrollIntoViewIfNeeded

locator.scrollIntoViewIfNeeded

このメソッドは、操作性チェックを待機し、IntersectionObserverのratioで定義されているように、要素が完全に表示されていない限り、要素をビューにスクロールしようとします。

使用例

await locator.scrollIntoViewIfNeeded();
await locator.scrollIntoViewIfNeeded(options);

引数

• options Object (オプション)

  • スクロールの代替方法については、スクロールを参照してください。

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• timeout number (オプション)#

---

Promise<void>#

バージョン 1.14 で追加 selectOption

locator.selectOption

使用例

<select multiple>
  <option value="red">Red</option>
  <option value="green">Green</option>
  <option value="blue">Blue</option>
</select>

// single selection matching the value or label
element.selectOption('blue');

// single selection matching the label
element.selectOption({ label: 'Blue' });

// multiple selection for red, green and blue options
element.selectOption(['red', 'green', 'blue']);

引数

• <select>でオプションまたはオプションを複数選択します。

  • values null | string | ElementHandle | Array<string> | Object | Array<ElementHandle> | Array<Object>#

    value string (オプション)

  • option.valueで一致させます。オプション。

    label string (オプション)

  • option.labelで一致させます。オプション。

    index number (オプション)

  選択するオプション。<select> が multiple 属性を持つ場合、一致するすべてのオプションが選択され、そうでなければ、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。文字列値は、値とラベルの両方に一致します。すべての指定されたプロパティが一致する場合、オプションは一致すると見なされます。
• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<Array<string>>#

詳細

このメソッドは、操作可能性チェックを待ち、指定されたすべてのオプションが <select> 要素に存在することを待って、これらのオプションを選択します。

ターゲット要素が <select> 要素でない場合、このメソッドはエラーをスローします。ただし、要素が関連付けられた control を持つ <label> 要素内にある場合、代わりにコントロールが使用されます。

正常に選択されたオプション値の配列を返します。

提供されたすべてのオプションが選択されると、change および input イベントをトリガーします。

---

selectText

バージョン 1.14 で追加 locator.selectText

このメソッドは、操作可能性チェックを待ち、次に要素にフォーカスを当て、そのテキストコンテンツをすべて選択します。

要素が関連付けられた control を持つ <label> 要素内にある場合、代わりにコントロール内のテキストにフォーカスを当てて選択します。

使用例

await locator.selectText();
await locator.selectText(options);

引数

• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

---

setChecked

Added in: v1.15 locator.setChecked

チェックボックスまたはラジオ要素の状態を設定します。

使用例

await page.getByRole('checkbox').setChecked(true);

引数

• checked boolean#

  チェックボックスをチェックするか、チェックを外すか。

• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の可視ポイントの一部を使用します。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (オプション)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

• Promise<void>#

詳細

このメソッドは、次の手順を実行して要素をチェックまたはチェック解除します。

1. 一致する要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはエラーをスローします。
2. 要素がすでに正しいチェック状態になっている場合、このメソッドはすぐに返ります。
3. force オプションが設定されていない限り、一致する要素の操作可能性チェックを待ちます。チェック中に要素がデタッチされた場合、アクション全体が再試行されます。
4. 必要に応じて、要素をビューにスクロールします。
5. page.mouse を使用して、要素の中央をクリックします。
6. 要素がチェックまたはチェック解除されたことを確認します。そうでない場合、このメソッドはエラーをスローします。

指定された timeout の間にすべての手順が完了しなかった場合、このメソッドは TimeoutError をスローします。ゼロタイムアウトを渡すと、これは無効になります。

---

setInputFiles

バージョン 1.14 で追加 locator.setInputFiles

ファイルまたは複数のファイルを <input type=file> にアップロードします。[webkitdirectory] 属性を持つ入力の場合、単一のディレクトリパスのみがサポートされます。

使用例

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

引数

• files string | Array<string> | Object | Array<Object>#

  • name string

    ファイル名

  • mimeType string

    ファイルタイプ

  • buffer Buffer

    ファイルの内容

• options Object (オプション)

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

詳細

ファイル入力の値をこれらのファイルパスまたはファイルに設定します。filePaths の一部が相対パスである場合、それらは現在の作業ディレクトリからの相対パスとして解決されます。空の配列の場合、選択されたファイルをクリアします。

このメソッドは、Locator が input 要素 を指していることを期待します。ただし、要素が関連付けられた control を持つ <label> 要素内にある場合、代わりにコントロールをターゲットにします。

---

tap

バージョン 1.14 で追加 locator.tap

ロケーターに一致する要素に対してタップジェスチャを実行します。タッチイベントを手動でディスパッチして他のジェスチャをエミュレートする例については、レガシータッチイベントのエミュレートのページを参照してください。

使用例

await locator.tap();
await locator.tap(options);

引数

• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを確認し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows および Linux では "Control" に、macOS では "Meta" に解決されます。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の可視ポイントの一部を使用します。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (オプション)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。キーボード modifiers は、trial に関係なく押され、これらのキーが押されたときにのみ表示される要素のテストを可能にすることに注意してください。

戻り値

• Promise<void>#

詳細

このメソッドは、次の手順を実行して要素をタップします。

1. force オプションが設定されていない限り、要素の操作可能性チェックを待ちます。
2. 必要に応じて、要素をビューにスクロールします。
3. 要素の中央、または指定された position をタップするには、page.touchscreen を使用します。

アクション中に要素がDOMから切り離された場合、このメソッドは例外をスローします。

指定された timeout の間にすべての手順が完了しなかった場合、このメソッドは TimeoutError をスローします。ゼロタイムアウトを渡すと、これは無効になります。

注記

element.tap() には、ブラウザコンテキストの hasTouch オプションが true に設定されている必要があります。

---

textContent

バージョン 1.14 で追加 locator.textContent

node.textContent を返します。

テキストのアサート

ページ上のテキストをアサートする必要がある場合は、不安定さを避けるために、expect(locator).toHaveText() を推奨します。詳細については、アサーションガイドを参照してください。

使用例

await locator.textContent();
await locator.textContent(options);

引数

• options Object (オプション)

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<null | string>#

---

uncheck

バージョン 1.14 で追加 locator.uncheck

チェックボックスまたはラジオ要素がチェック解除されていることを確認します。

使用例

await page.getByRole('checkbox').uncheck();

引数

• options Object (オプション)

  • force boolean (オプション)#

    アクション実行可能性チェックをバイパスするかどうか。デフォルトは false です。

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Object (オプション)#

    • x number

    • y number

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の可視ポイントの一部を使用します。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

  • trial boolean (オプション)#

    設定すると、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

• Promise<void>#

詳細

このメソッドは、次の手順を実行して要素をチェック解除します。

1. 要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはエラーをスローします。要素がすでにチェック解除されている場合、このメソッドはすぐに返ります。
2. force オプションが設定されていない限り、要素の操作可能性チェックを待ちます。
3. 必要に応じて、要素をビューにスクロールします。
4. page.mouse を使用して、要素の中央をクリックします。
5. 要素がチェック解除されたことを確認します。そうでない場合、このメソッドはエラーをスローします。

アクション中に要素がDOMから切り離された場合、このメソッドは例外をスローします。

指定された timeout の間にすべての手順が完了しなかった場合、このメソッドは TimeoutError をスローします。ゼロタイムアウトを渡すと、これは無効になります。

---

waitFor

Added in: v1.16 locator.waitFor

ロケーターで指定された要素が state オプションを満たすときに返ります。

ターゲット要素がすでに条件を満たしている場合、メソッドはすぐに返ります。それ以外の場合は、条件が満たされるまで最大 timeout ミリ秒待機します。

使用例

const orderSent = page.locator('#order-sent');
await orderSent.waitFor();

引数

• options Object (オプション)

  • state "attached" | "detached" | "visible" | "hidden" (オプション)#

    デフォルトは 'visible' です。次のいずれかになります。

    • 'attached' - 要素が DOM に存在することを待ちます。
    • 'detached' - 要素が DOM に存在しないことを待ちます。
    • 'visible' - 要素が空でないバウンディングボックスを持ち、visibility:hidden でないことを待ちます。コンテンツがない要素や display:none の要素は空のバウンディングボックスを持ち、可視とは見なされないことに注意してください。
    • 'hidden' - 要素が DOM からデタッチされるか、空のバウンディングボックスを持つか、visibility:hidden になるのを待ちます。これは 'visible' オプションの反対です。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#

---

Deprecated

elementHandle

バージョン 1.14 で追加 locator.elementHandle

推奨されません

Locator とウェブアサーションを ElementHandle よりも常に優先してください。後者は本質的に競争状態になりやすいためです。

指定されたロケーターを最初の一致する DOM 要素に解決します。一致する要素がない場合、1つになるまで待機します。複数の要素がロケーターに一致する場合、エラーをスローします。

使用例

await locator.elementHandle();
await locator.elementHandle(options);

引数

• options Object (オプション)

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<ElementHandle>#

---

elementHandles

バージョン 1.14 で追加 locator.elementHandles

推奨されません

Locator とウェブアサーションを ElementHandle よりも常に優先してください。後者は本質的に競争状態になりやすいためです。

指定されたロケーターを一致するすべての DOM 要素に解決します。一致する要素がない場合、空のリストを返します。

使用例

await locator.elementHandles();

戻り値

• Promise<Array<ElementHandle>>#

---

type

バージョン 1.14 で追加 locator.type

非推奨

ほとんどの場合、locator.fill() を使用する必要があります。ページに特別なキーボード処理がある場合にのみ、キーを1つずつ押す必要があります。この場合は、locator.pressSequentially() を使用してください。

ほとんどの場合、代わりにlocator.fill()を使用する必要があります。ページに特別なキーボード処理がある場合にのみ、キーを1つずつ押す必要があります。

要素にフォーカスし、テキスト内の各文字に対してkeydown、keypress/input、およびkeyupイベントを送信します。

使用例

引数

• text string#

  フォーカスされた要素に入力するテキスト。

• options Object (オプション)

  • delay number (オプション)#

    delay number (オプション)#

  • noWaitAfter boolean (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout number (オプション)#

    最大タイムアウト時間 (ミリ秒単位)。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、設定の actionTimeout オプション、または browserContext.setDefaultTimeout() メソッドまたは page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

• Promise<void>#