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

Locator

ロケーターは、Playwrightの自動待機と再試行可能性の中心的な要素です。簡単に言えば、ロケーターはページ上の要素をいつでも見つける方法を表します。ロケーターはpage.locator()メソッドで作成できます。

ロケーターについてさらに詳しく.

メソッド​

all​

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

ロケーターが要素のリストを指す場合、これはそれぞれの要素を指すロケーターの配列を返します。

注

locator.all()はロケーターに一致する要素を待たず、代わりにページに存在するものを即座に返します。

要素のリストが動的に変化する場合、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`値の配列を返します。

テキストのアサート

ページ上のテキストをアサートする必要がある場合は、不安定さを避けるために`use_inner_text`オプションを指定したexpect(locator).to_have_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_

このロケーターと引数のロケーターの両方に一致するロケーターを作成します。

使用方法

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

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

引数

戻り値

aria_snapshot​

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

指定された要素のARIAスナップショットをキャプチャします。対応するアサーションについては、ARIAスナップショットおよびexpect(locator).to_match_aria_snapshot()について詳しくお読みください。

使用方法

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

引数

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

    各要素のシンボリックリファレンスを生成します。スナップショットをキャプチャした直後に`aria-ref=<ref>`ロケーターを使用して、要素に対してアクションを実行できます。

  • timeout float (オプション)#

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

戻り値

詳細

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

このメソッドは、ロケーターに一致する要素のバウンディングボックスを返します。要素が非表示の場合、`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からデタッチされた場合、このメソッドはエラーをスローします。

すべてのステップが指定されたタイムアウト内に完了しなかった場合、このメソッドは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]`要素ではない場合、このメソッドはエラーをスローします。ただし、要素が関連するコントロールを持つ`<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を使用して要素の中心、または指定された位置をクリックします。
  4. no_wait_afterオプションが設定されていない限り、開始されたナビゲーションが成功または失敗するのを待ちます。

アクション中に要素がDOMからデタッチされた場合、このメソッドはエラーをスローします。

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

count​

追加バージョン: v1.14 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を使用して要素の中心、または指定された位置をダブルクリックします。

アクション中に要素がDOMからデタッチされた場合、このメソッドはエラーをスローします。

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

注

element.dblclick()は、2つのclickイベントと1つの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 ロケーター#

    ドラッグ先の要素のロケーター。

  • 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`です。アクションを実行せずに要素がアクションの準備ができるまで待機するのに役立ちます。

戻り値

詳細

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

evaluate​

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

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

使用方法

引数

  • expression str#

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

  • arg EvaluationArgument (オプション)#

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

  • timeout float (オプション)#

    評価する前にロケーターを待機する最大時間（ミリ秒単位）。ロケーターが解決された後、評価自体はタイムアウトによって制限されないことに注意してください。デフォルトは`30000`（30秒）です。`0`を渡すとタイムアウトが無効になります。

戻り値

詳細

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

もし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に渡すオプションの引数。

戻り値

詳細

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

もし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`を渡すとタイムアウトが無効になります。

戻り値

詳細

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

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]`要素ではない場合、このメソッドはエラーをスローします。ただし、要素が関連するコントロールを持つ`<label>`要素内にある場合、代わりにそのコントロールに値が入力されます。

細粒度のキーボードイベントを送信するには、locator.press_sequentially()を使用します。

filter​

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

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

使用方法

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 ロケーター (オプション)#

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

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

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

  • has_not ロケーター (オプション)追加バージョン: v1.33#

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

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

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

    指定されたテキストを、子要素または子孫要素内に含まない要素に一致します。文字列を渡した場合、大文字と小文字を区別せず、部分文字列を検索します。

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

    指定されたテキストを、子要素または子孫要素内に含む要素に一致します。文字列を渡した場合、大文字と小文字を区別せず、部分文字列を検索します。例えば、`\"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 = 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)

引数

戻り値

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ロール、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として使用されます。必要に応じて、selectors.set_test_id_attribute()を使用して異なるテストID属性を設定できます。

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

要素をそのタイトル属性によって特定できます。

使用方法

以下の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を使用して要素の中心、または指定された位置にカーソルを合わせます。

アクション中に要素がDOMからデタッチされた場合、このメソッドはエラーをスローします。

すべてのステップが指定されたタイムアウト内に完了しなかった場合、このメソッドは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`を返します。

テキストのアサート

ページ上のテキストをアサートする必要がある場合は、不安定さを避けるために`use_inner_text`オプションを指定したexpect(locator).to_have_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()

引数

戻り値

詳細

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

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

要素が非表示であるかどうかを返します。表示の逆です。

可視性のアサート

要素が非表示であることをアサートする必要がある場合は、不安定さを避けるために 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(selector_or_locator)
locator.locator(selector_or_locator, **kwargs)

引数

  • selector_or_locator str | Locator#

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

  • has Locator (オプション)#

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

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

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

  • has_not ロケーター (オプション)追加バージョン: v1.33#

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

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

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

    指定されたテキストを、子要素または子孫要素内に含まない要素に一致します。文字列を渡した場合、大文字と小文字を区別せず、部分文字列を検索します。

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

    指定されたテキストを、子要素または子孫要素内に含む要素に一致します。文字列を渡した場合、大文字と小文字を区別せず、部分文字列を検索します。例えば、`\"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つのロケーターのいずれか一方または両方に一致するすべての要素に一致するロケーターを作成します。

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

使用方法

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

注

「新しいメール」ボタンとセキュリティダイアログの両方が画面に表示された場合、「or」ロケーターは両方に一致し、おそらく「厳密モード違反」エラーをスローする可能性があります。この場合、locator.first を使用して、いずれか一方のみに一致させることができます。

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​

追加バージョン: 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アニメーションを停止します。アニメーションは、その期間に応じて異なる扱いを受けます。

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

    デフォルトは、アニメーションに影響を与えない "allow" です。

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

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

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

    スクリーンショットを撮る際にマスクすべきロケーターを指定します。マスクされた要素は、そのバウンディングボックスを完全に覆うピンクのボックス #FF00FF （mask_color でカスタマイズ可能）でオーバーレイされます。マスクは非表示の要素にも適用されます。これを無効にするには、可視要素のみを照合するを参照してください。

  • mask_color str (オプション)追加バージョン: 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 (オプション)追加バージョン: 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> 要素でない場合、このメソッドはエラーをスローします。ただし、要素が関連するコントロールを持つ <label> 要素内にある場合、代わりにそのコントロールが使用されます。

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

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

select_text​

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

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

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

使用方法

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

引数

戻り値

set_checked​

追加バージョン: 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. 要素の中心、または指定されたpositionをタップするには、page.touchscreen を使用します。

アクション中に要素が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
非推奨

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

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

使用方法

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

引数

戻り値

element_handles​

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

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

指定されたロケーターをすべての一致する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()メソッドを使用して変更できます。

戻り値