メインコンテンツにスキップ

Locator

Locatorは、Playwrightの自動待機とリトライ機能の中心となるものです。Locatorは、任意の瞬間にページ上の要素を見つける方法を表します。Locatorは、page.locator() メソッドで作成できます。

Locatorの詳細はこちら.

メソッド​

all​

追加バージョン: v1.29 locator.all

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

注記

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

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

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

使用例

for li in page.get_by_role('listitem').all():
  li.click();

戻り値

all_inner_texts​

追加バージョン: v1.14 locator.all_inner_texts

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

テキストのアサーション

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

使用例

texts = page.get_by_role("link").all_inner_texts()

戻り値

all_text_contents​

追加バージョン: v1.14 locator.all_text_contents

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

テキストのアサーション

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

使用例

texts = page.get_by_role("link").all_text_contents()

戻り値

and_​

追加バージョン: v1.34 locator.and_

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

使用例

次の例は、特定のタイトルを持つボタンを見つけます。

button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))

引数

  • locator Locator#

    一致させる追加のlocator。

戻り値

aria_snapshot​

追加バージョン: v1.49 locator.aria_snapshot

指定された要素のariaスナップショットをキャプチャします。ariaスナップショットと対応するアサーションである expect(locator).to_match_aria_snapshot() について詳しくはこちらをご覧ください。

使用例

page.get_by_role("link").aria_snapshot()

引数

戻り値

詳細

このメソッドは、指定された要素の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​

追加バージョン: v1.28 locator.blur

要素の blur を呼び出します。

使用例

locator.blur()
locator.blur(**kwargs)

引数

戻り値

bounding_box​

追加バージョン: v1.14 locator.bounding_box

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

使用例

box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

引数

戻り値

  • NoneType | Dict#

    • x float

      要素のx座標（ピクセル単位）。

    • y float

      要素のy座標（ピクセル単位）。

    • width float

      要素の幅（ピクセル単位）。

    • height float

      要素の高さ（ピクセル単位）。

詳細

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

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

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

check​

追加バージョン: v1.14 locator.check

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

使用例

page.get_by_role("checkbox").check()

引数

  • force bool (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

次の手順を実行します

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

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

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

clear​

追加バージョン: v1.28 locator.clear

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

使用例

page.get_by_role("textbox").clear()

引数

  • force bool (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

詳細

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

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

click​

追加バージョン: v1.14 locator.click

要素をクリックします。

使用例

ボタンをクリックする

page.get_by_role("button").click()

キャンバス上の特定の位置をShift+右クリックする

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

引数

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

    デフォルトは left です。

  • click_count int (オプション)#

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

  • delay float (オプション)#

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

  • force bool (オプション)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

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

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

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

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

count​

追加バージョン: v1.14 locator.count

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

countのアサーション

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

使用例

count = page.get_by_role("listitem").count()

戻り値

dblclick​

追加バージョン: v1.14 locator.dblclick

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

使用例

locator.dblclick()
locator.dblclick(**kwargs)

引数

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

    デフォルトは left です。

  • delay float (オプション)#

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

  • force bool (オプション)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

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

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

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

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

注記

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

dispatch_event​

追加バージョン: v1.14 locator.dispatch_event

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

使用例

locator.dispatch_event("click")

引数

  • type str#

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

  • event_init EvaluationArgument (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

詳細

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

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

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

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

data_transfer = page.evaluate_handle("new DataTransfer()")
locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

drag_to​

追加バージョン: v1.18 locator.drag_to

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

使用例

source = page.locator("#source")
target = page.locator("#target")

source.drag_to(target)
# or specify exact positions relative to the top-left corners of the elements:
source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

引数

  • target Locator#

    ドラッグ先の要素のlocator。

  • force bool (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • source_position Dict (オプション)#

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

  • target_position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

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

evaluate​

追加バージョン: v1.14 locator.evaluate

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

使用例

引数

  • expression str#

    ブラウザコンテキストで評価されるJavaScript式。式が関数として評価される場合、関数は自動的に呼び出されます。

  • arg EvaluationArgument (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

詳細

expression の戻り値を返します。これは、一致する要素を最初の引数として、arg を2番目の引数として呼び出されます。

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

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

evaluate_all​

追加バージョン: v1.14 locator.evaluate_all

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

使用例

locator = page.locator("div")
more_than_ten = locator.evaluate_all("(divs, min) => divs.length > min", 10)

引数

  • expression str#

    ブラウザコンテキストで評価されるJavaScript式。式が関数として評価される場合、関数は自動的に呼び出されます。

  • arg EvaluationArgument (オプション)#

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

戻り値

詳細

expression の戻り値を返します。これは、一致するすべての要素の配列を最初の引数として、arg を2番目の引数として呼び出されます。

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

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

evaluate_handle​

追加バージョン: v1.14 locator.evaluate_handle

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

使用例

locator.evaluate_handle(expression)
locator.evaluate_handle(expression, **kwargs)

引数

  • expression str#

    ブラウザコンテキストで評価されるJavaScript式。式が関数として評価される場合、関数は自動的に呼び出されます。

  • arg EvaluationArgument (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

詳細

expression の戻り値をJSHandleとして返します。これは、一致する要素を最初の引数として、argを2番目の引数として呼び出されます。

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

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

expression がスローまたはリジェクトされる場合、このメソッドはスローします。

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

fill​

追加バージョン: v1.14 locator.fill

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

使用例

page.get_by_role("textbox").fill("example value")

引数

  • value str#

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

  • force bool (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

詳細

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

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

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

filter​

バージョン v1.22 で追加 locator.filter

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

使用例

row_locator = page.locator("tr")
# ...
row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

引数

  • 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 に FrameLocator を含めることはできません。

  • has_not Locator (オプション)バージョン v1.33 で追加#

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

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

  • has_not_text str | Pattern (オプション)バージョン v1.33 で追加#

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

  • has_text str | Pattern (オプション)#

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

  • visible bool (オプション)バージョン v1.51 で追加#

    表示または非表示の要素のみに一致します。

戻り値

focus​

追加バージョン: v1.14 locator.focus

一致する要素に対して focus を呼び出します。

使用例

locator.focus()
locator.focus(**kwargs)

引数

戻り値

frame_locator​

バージョン v1.17 で追加 locator.frame_locator

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

使用例

locator = page.frame_locator("iframe").get_by_text("Submit")
locator.click()

引数

  • selector str#

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

戻り値

get_attribute​

追加バージョン: v1.14 locator.get_attribute

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

属性のアサーション

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

使用例

locator.get_attribute(name)
locator.get_attribute(name, **kwargs)

引数

  • name str#

    値を取得する属性名。

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

get_by_alt_text​

バージョン v1.27 で追加 locator.get_by_alt_text

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

使用例

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

<img alt='Playwright logo'>
page.get_by_alt_text("Playwright logo").click()

引数

  • text str | Pattern#

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

  • exact bool (オプション)#

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

戻り値

get_by_label​

バージョン v1.27 で追加 locator.get_by_label

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

使用例

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

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

引数

  • text str | Pattern#

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

  • exact bool (オプション)#

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

戻り値

get_by_placeholder​

バージョン v1.27 で追加 locator.get_by_placeholder

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

使用例

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

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

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

page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

引数

  • text str | Pattern#

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

  • exact bool (オプション)#

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

戻り値

get_by_role​

バージョン v1.27 で追加 locator.get_by_role

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

使用例

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

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

各要素を暗黙的なロールで特定できます

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).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 ロール。

  • checked bool (オプション)#

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

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

  • disabled bool (オプション)#

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

    注記

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

  • exact bool (オプション)追加バージョン: v1.28#

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

  • expanded bool (オプション)#

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

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

  • include_hidden bool (オプション)#

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

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

  • level int (オプション)#

    通常、ロール heading、listitem、row、treeitem に存在する数値属性。<h1>-<h6> 要素のデフォルト値が設定されています。

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

  • name str | Pattern (オプション)#

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

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

  • pressed bool (オプション)#

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

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

  • selected bool (オプション)#

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

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

戻り値

詳細

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

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

get_by_test_id​

バージョン v1.27 で追加 locator.get_by_test_id

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

使用例

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

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

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

page.get_by_test_id("directions").click()

引数

  • test_id str | Pattern#

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

戻り値

詳細

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

get_by_text​

バージョン v1.27 で追加 locator.get_by_text

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

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

使用例

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

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

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

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

引数

  • text str | Pattern#

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

  • exact bool (オプション)#

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

戻り値

詳細

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

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

get_by_title​

バージョン v1.27 で追加 locator.get_by_title

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

使用例

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

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

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

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

引数

  • text str | Pattern#

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

  • exact bool (オプション)#

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

戻り値

highlight​

バージョン v1.20 で追加 locator.highlight

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

使用例

locator.highlight()

戻り値

hover​

追加バージョン: v1.14 locator.hover

一致する要素の上にマウスカーソルを合わせます。

使用例

page.get_by_role("link").hover()

引数

  • force bool (オプション)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

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

  • no_wait_after bool (オプション)追加バージョン: v1.28#

    非推奨

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

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

  • position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

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

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

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

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

inner_html​

追加バージョン: v1.14 locator.inner_html

element.innerHTML を返します。

使用例

locator.inner_html()
locator.inner_html(**kwargs)

引数

戻り値

inner_text​

追加バージョン: v1.14 locator.inner_text

element.innerText を返します。

テキストのアサーション

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

使用例

locator.inner_text()
locator.inner_text(**kwargs)

引数

戻り値

input_value​

追加バージョン: v1.14 locator.input_value

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

値のアサーション

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

使用例

value = page.get_by_role("textbox").input_value()

引数

戻り値

詳細

input、textarea、または select ではない要素をスローします。ただし、要素が関連付けられた control を持つ <label> 要素内にある場合、control の値を返します。

is_checked​

追加バージョン: v1.14 locator.is_checked

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

チェックされた状態のアサーション

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

使用例

checked = page.get_by_role("checkbox").is_checked()

引数

戻り値

is_disabled​

追加バージョン: v1.14 locator.is_disabled

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

無効化された状態のアサーション

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

使用例

disabled = page.get_by_role("button").is_disabled()

引数

戻り値

is_editable​

追加バージョン: v1.14 locator.is_editable

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

編集可能な状態のアサーション

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

使用例

editable = page.get_by_role("textbox").is_editable()

引数

戻り値

is_enabled​

追加バージョン: v1.14 locator.is_enabled

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

有効化された状態のアサーション

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

使用例

enabled = page.get_by_role("button").is_enabled()

引数

戻り値

is_hidden​

追加バージョン: v1.14 locator.is_hidden

要素が非表示になっているかどうかを返します。visible の反対です。

表示状態のアサーション

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

使用例

hidden = page.get_by_role("button").is_hidden()

引数

  • timeout float (オプション)#

    非推奨

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

戻り値

is_visible​

追加バージョン: v1.14 locator.is_visible

要素が 表示 されているかどうかを返します。

表示状態のアサーション

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

使用例

visible = page.get_by_role("button").is_visible()

引数

  • timeout float (オプション)#

    非推奨

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

戻り値

locator​

追加バージョン: v1.14 locator.locator

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

Locatorの詳細はこちら.

使用例

locator.locator(selector_or_locator)
locator.locator(selector_or_locator, **kwargs)

引数

  • selector_or_locator str | Locator#

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

  • 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 に FrameLocator を含めることはできません。

  • has_not Locator (オプション)バージョン v1.33 で追加#

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

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

  • has_not_text str | Pattern (オプション)バージョン v1.33 で追加#

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

  • has_text str | Pattern (オプション)#

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

戻り値

nth​

追加バージョン: v1.14 locator.nth

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

使用例

banana = page.get_by_role("listitem").nth(2)

引数

戻り値

or_​

バージョン v1.33 で追加 locator.or_

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

両方のロケーターが何かに一致する場合、結果のロケーターは複数の一致を持つ可能性があり、ロケーターストrictness 違反を引き起こす可能性があることに注意してください。

使用例

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

注記

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

new_email = page.get_by_role("button", name="New")
dialog = page.get_by_text("Confirm security settings")
expect(new_email.or_(dialog).first).to_be_visible()
if (dialog.is_visible()):
  page.get_by_role("button", name="Dismiss").click()
new_email.click()

引数

  • locator Locator#

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

戻り値

press​

追加バージョン: v1.14 locator.press

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

使用例

page.get_by_role("textbox").press("Backspace")

引数

  • key str#

    押すキーの名前、または生成する文字（例：ArrowLeft や a）。

  • delay float (オプション)#

    keydown と keyup の間の待ち時間（ミリ秒単位）。デフォルトは 0 です。

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

詳細

要素にフォーカスし、次に 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" などのショートカットもサポートされています。修飾キーを指定すると、後続のキーが押されている間、修飾キーが押されたままになります。

press_sequentially​

Added in: v1.38 locator.press_sequentially
ヒント

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

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

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

使用例

locator.press_sequentially("hello") # types instantly
locator.press_sequentially("world", delay=100) # types slower, like a user

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

locator = page.get_by_label("Password")
locator.press_sequentially("my password")
locator.press("Enter")

引数

  • text str#

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

  • delay float (オプション)#

    キー押下間の待ち時間（ミリ秒単位）。デフォルトは 0 です。

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

screenshot​

追加バージョン: v1.14 locator.screenshot

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

使用例

page.get_by_role("link").screenshot()

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

page.get_by_role("link").screenshot(animations="disabled", path="link.png")

引数

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

    "disabled" に設定すると、CSS アニメーション、CSS トランジション、および Web Animations を停止します。アニメーションは、期間に応じて異なる処理を受けます。

    • 有限のアニメーションは完了まで早送りされるため、transitionend イベントが発火します。
    • 無限のアニメーションは初期状態にキャンセルされ、スクリーンショット後に再度再生されます。

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

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

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

  • mask List[Locator] (オプション)#

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

  • mask_color str (オプション)Added in: v1.35#

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

  • omit_background bool (オプション)#

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

  • path Union[str, pathlib.Path] (オプション)#

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

  • quality int (オプション)#

    画像の品質（0〜100）。png 画像には適用されません。

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

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

    デフォルトは "device" です。

  • style str (オプション)Added in: v1.41#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

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

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

戻り値

詳細

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

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

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

scroll_into_view_if_needed​

追加バージョン: v1.14 locator.scroll_into_view_if_needed

このメソッドは、アクション可能性チェックを待ってから、IntersectionObserver の ratio で定義されているように完全に表示されていない限り、要素をビューにスクロールしようとします。

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

使用例

locator.scroll_into_view_if_needed()
locator.scroll_into_view_if_needed(**kwargs)

引数

戻り値

select_option​

追加バージョン: v1.14 locator.select_option

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

使用例

<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.select_option("blue")
# single selection matching the label
element.select_option(label="blue")
# multiple selection for blue, red and second option
element.select_option(value=["red", "green", "blue"])

引数

  • force bool (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • element ElementHandle | List[ElementHandle] (オプション)#

    選択するオプション要素。オプション。

  • index int | List[int] (オプション)#

    インデックスで選択するオプション。オプション。

  • value str | List[str] (オプション)#

    値で選択するオプション。<select> に multiple 属性がある場合、指定されたすべてのオプションが選択されます。それ以外の場合は、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。オプション。

  • label str | List[str] (オプション)#

    ラベルで選択するオプション。<select> に multiple 属性がある場合、指定されたすべてのオプションが選択されます。それ以外の場合は、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。オプション。

戻り値

詳細

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

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

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

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

select_text​

追加バージョン: v1.14 locator.select_text

このメソッドは、アクション可能性 チェックを待ってから、要素にフォーカスし、そのすべてのテキストコンテンツを選択します。

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

使用例

locator.select_text()
locator.select_text(**kwargs)

引数

戻り値

set_checked​

Added in: v1.15 locator.set_checked

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

使用例

page.get_by_role("checkbox").set_checked(True)

引数

  • checked bool#

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

  • force bool (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

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

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

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

set_input_files​

追加バージョン: v1.14 locator.set_input_files

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

使用例

# Select one file
page.get_by_label("Upload file").set_input_files('myfile.pdf')

# Select multiple files
page.get_by_label("Upload files").set_input_files(['file1.txt', 'file2.txt'])

# Select a directory
page.get_by_label("Upload directory").set_input_files('mydir')

# Remove all the selected files
page.get_by_label("Upload file").set_input_files([])

# Upload buffer from memory
page.get_by_label("Upload file").set_input_files(
    files=[
        {"name": "test.txt", "mimeType": "text/plain", "buffer": b"this is a test"}
    ],
)

引数

戻り値

詳細

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

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

tap​

追加バージョン: v1.14 locator.tap

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

使用例

locator.tap()
locator.tap(**kwargs)

引数

  • force bool (オプション)#

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

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

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

  1. 要素に対する操作性チェックが完了するのを待ちます。ただし、force オプションが設定されている場合は除きます。
  2. 必要に応じて、要素をビューにスクロールします。
  3. page.touchscreen を使用して、要素の中心、または指定された position をタップします。

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

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

注記

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

text_content​

追加バージョン: v1.14 locator.text_content

node.textContent を返します。

テキストのアサーション

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

使用例

locator.text_content()
locator.text_content(**kwargs)

引数

戻り値

uncheck​

追加バージョン: v1.14 locator.uncheck

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

使用例

page.get_by_role("checkbox").uncheck()

引数

  • force bool (オプション)#

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

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • position Dict (オプション)#

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

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

戻り値

詳細

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

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

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

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

wait_for​

追加: v1.16 locator.wait_for

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

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

使用例

order_sent = page.locator("#order-sent")
order_sent.wait_for()

引数

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

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

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

プロパティ​

content_frame​

追加: v1.43 locator.content_frame

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

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

逆の操作には、frame_locator.owner を使用してください。

使用例

locator = page.locator("iframe[name=\"embedded\"]")
# ...
frame_locator = locator.content_frame
frame_locator.get_by_role("button").click()

戻り値

first​

追加バージョン: v1.14 locator.first

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

使用例

locator.first

戻り値

last​

追加バージョン: v1.14 locator.last

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

使用例

banana = page.get_by_role("listitem").last

戻り値

page​

追加: v1.19 locator.page

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

使用例

locator.page

戻り値

非推奨​

element_handle​

追加バージョン: v1.14 locator.element_handle
推奨されません

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

指定されたロケーターを最初の一致する DOM 要素に解決します。一致する要素がない場合は、要素が現れるまで待ちます。複数の要素がロケーターに一致する場合、例外をスローします。

使用例

locator.element_handle()
locator.element_handle(**kwargs)

引数

戻り値

element_handles​

追加バージョン: v1.14 locator.element_handles
推奨されません

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

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

使用例

locator.element_handles()

戻り値

type​

追加バージョン: v1.14 locator.type
非推奨

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

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

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

使用例

引数

  • text str#

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

  • delay float (オプション)#

    キー押下間の待ち時間（ミリ秒単位）。デフォルトは 0 です。

  • no_wait_after bool (オプション)#

    非推奨

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

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

  • timeout float (オプション)#

    最大タイムアウト時間（ミリ秒単位）。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は、browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値