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

Locator

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

ロケーターについて詳しく学ぶ.

メソッド​

all​

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

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

注

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

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

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

使用法

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

戻り値

allInnerTexts​

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

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

テキストのアサート

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

使用法

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

戻り値

allTextContents​

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

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

テキストのアサート

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

使用法

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

戻り値

and​

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

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

使用法

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

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

引数

  • locator Locator#

    一致させる追加のロケーター。

戻り値

ariaSnapshot​

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

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

使用法

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

引数

  • options Object (オプション)

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

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

    • timeout number (オプション)#

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

戻り値

詳細

このメソッドは、指定された要素の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を呼び出します。

使用法

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

引数

戻り値

boundingBox​

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

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

使用法

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

引数

戻り値

  • Promise<null | Object>#

    • x number

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

    • y number

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

    • width number

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

    • height number

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

詳細

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

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

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

check​

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

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

使用法

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

引数

  • options Object (オプション)

    • force boolean (オプション)#

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

    • noWaitAfter boolean (オプション)#

      非推奨

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

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

    • position Object (オプション)#

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

    • timeout number (オプション)#

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

    • trial boolean (オプション)#

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

戻り値

詳細

以下のステップを実行します

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

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

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

clear​

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

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

使用法

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

引数

  • options Object (オプション)

    • force boolean (オプション)#

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

    • noWaitAfter boolean (オプション)#

      非推奨

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

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

    • timeout number (オプション)#

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

戻り値

詳細

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

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

click​

追加バージョン: v1.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 (オプション)#

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

    • timeout number (オプション)#

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

    • trial boolean (オプション)#

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

戻り値

詳細

このメソッドは、以下のステップを実行して要素をクリックします

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

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

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

contentFrame​

追加バージョン: v1.43 locator.contentFrame

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

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

逆の操作については、frameLocator.owner()を使用してください。

使用法

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

戻り値

count​

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

ロケーターに一致する要素の数を返します。

カウントのアサート

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

使用法

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

戻り値

dblclick​

追加バージョン: v1.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 (オプション)#

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

    • timeout number (オプション)#

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

    • trial ブーリアン (オプション)#

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

戻り値

詳細

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

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

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

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

注

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

dispatchEvent​

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

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

使用法

await locator.dispatchEvent('click');

引数

  • type 文字列#

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

  • eventInit EvaluationArgument (オプション)#

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

  • options Object (オプション)

戻り値

詳細

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

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

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

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

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

dragTo​

追加: v1.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#

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

  • options Object (オプション)

    • force ブーリアン (オプション)#

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

    • noWaitAfter ブーリアン (オプション)#

      非推奨

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

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

    • sourcePosition オブジェクト (オプション)#

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

    • targetPosition オブジェクト (オプション)#

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

    • timeout 数値 (オプション)#

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

    • trial ブーリアン (オプション)#

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

戻り値

詳細

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

evaluate​

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

マッチする要素を引数としてページ内でJavaScriptコードを実行します。

使用法

引数

  • pageFunction 関数 | 文字列#

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

  • arg EvaluationArgument (オプション)#

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

  • options Object (オプション)

    • timeout 数値 (オプション)#

      評価する前にロケーターを待つ最大ミリ秒数。ロケーターが解決された後、評価自体はタイムアウトによって制限されないことに注意してください。デフォルトは0 (タイムアウトなし) です。

戻り値

詳細

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

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

pageFunctionが例外をスローまたは拒否した場合、このメソッドは例外をスローします。

evaluateAll​

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

マッチするすべての要素を引数としてページ内でJavaScriptコードを実行します。

使用法

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

引数

戻り値

詳細

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

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

pageFunctionが例外をスローまたは拒否した場合、このメソッドは例外をスローします。

evaluateHandle​

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

マッチする要素を引数としてページ内でJavaScriptコードを実行し、結果をJSHandleで返します。

使用法

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

引数

  • pageFunction 関数 | 文字列#

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

  • arg EvaluationArgument (オプション)#

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

  • options Object (オプション)

    • timeout 数値 (オプション)#

      評価する前にロケーターを待つ最大ミリ秒数。ロケーターが解決された後、評価自体はタイムアウトによって制限されないことに注意してください。デフォルトは0 (タイムアウトなし) です。

戻り値

詳細

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

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

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

pageFunctionが例外をスローまたは拒否した場合、このメソッドは例外をスローします。

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

fill​

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

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

使用法

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

引数

  • value 文字列#

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

  • options Object (オプション)

    • force ブーリアン (オプション)#

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

    • noWaitAfter ブーリアン (オプション)#

      非推奨

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

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

    • timeout 数値 (オプション)#

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

戻り値

詳細

このメソッドは、アクション可能性チェックを待ち、要素にフォーカスし、値を入力して、入力後にinputイベントをトリガーします。入力フィールドをクリアするために空の文字列を渡すこともできます。

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

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

filter​

追加: v1.22 locator.filter

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

使用法

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

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

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

      外部および内部ロケーターは同じフレームに属している必要があります。内部ロケーターはFrameLocatorを含んではなりません。

    • hasNot Locator (オプション)追加: v1.33#

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

      外部および内部ロケーターは同じフレームに属している必要があります。内部ロケーターはFrameLocatorを含んではなりません。

    • hasNotText 文字列 | RegExp (オプション)追加: v1.33#

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

    • hasText 文字列 | RegExp (オプション)#

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

    • visible ブーリアン (オプション)追加: v1.51#

      可視要素または非可視要素のみにマッチします。

戻り値

first​

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

最初のマッチする要素へのロケーターを返します。

使用法

locator.first();

戻り値

focus​

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

マッチする要素に対してfocusを呼び出します。

使用法

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

引数

戻り値

frameLocator​

追加: v1.17 locator.frameLocator

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

使用法

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

引数

  • selector 文字列#

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

戻り値

getAttribute​

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

マッチする要素の属性値を返します。

属性のアサート

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

使用法

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

引数

戻り値

getByAltText​

追加: v1.27 locator.getByAltText

altテキストによって要素を特定できます。

使用法

例えば、このメソッドはaltテキスト「Playwright logo」によって画像を見つけます。

<img alt='Playwright logo'>
await page.getByAltText('Playwright logo').click();

引数

  • text 文字列 | RegExp#

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

  • options Object (オプション)

    • exact ブーリアン (オプション)#

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

戻り値

getByLabel​

追加: v1.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 文字列 | RegExp#

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

  • options Object (オプション)

    • exact ブーリアン (オプション)#

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

戻り値

getByPlaceholder​

追加: v1.27 locator.getByPlaceholder

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

使用法

例えば、以下のDOM構造を考えてみましょう。

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

プレースホルダーテキストによって要素を特定した後、入力を埋めることができます。

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

引数

  • text 文字列 | RegExp#

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

  • options Object (オプション)

    • exact ブーリアン (オプション)#

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

戻り値

getByRole​

追加: v1.27 locator.getByRole

ARIAロール、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 ブーリアン (オプション)#

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

      aria-checkedについて詳しくはこちら。

    • disabled ブーリアン (オプション)#

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

      注

      他のほとんどの属性とは異なり、disabledはDOM階層を通じて継承されます。aria-disabledについて詳しくはこちら。

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

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

    • expanded ブーリアン (オプション)#

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

      aria-expandedについて詳しくはこちら。

    • includeHidden ブーリアン (オプション)#

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

      aria-hiddenについて詳しくはこちら。

    • level 数値 (オプション)#

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

      aria-levelについて詳しくはこちら。

    • name 文字列 | RegExp (オプション)#

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

      アクセシブルネームについて詳しくはこちら。

    • pressed ブーリアン (オプション)#

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

      aria-pressedについて詳しくはこちら。

    • selected ブーリアン (オプション)#

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

      aria-selectedについて詳しくはこちら。

戻り値

詳細

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

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

getByTestId​

追加: v1.27 locator.getByTestId

テストIDによって要素を特定します。

使用法

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

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

要素をそのテストIDによって特定できます。

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

引数

戻り値

詳細

デフォルトでは、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​

追加: v1.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 文字列 | RegExp#

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

  • options Object (オプション)

    • exact ブーリアン (オプション)#

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

戻り値

詳細

テキストによるマッチングは、厳密な一致であっても常に空白を正規化します。例えば、複数のスペースを1つに変換し、改行をスペースに変換し、前後の空白を無視します。

buttonおよびsubmitタイプの入力要素は、テキストコンテンツではなくそのvalueによってマッチされます。例えば、テキスト"Log in"で特定する場合、<input type=button value="Log in">にマッチします。

getByTitle​

追加: v1.27 locator.getByTitle

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

使用法

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

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

タイトルテキストによって要素を特定した後、問題数をチェックできます。

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

引数

  • text 文字列 | RegExp#

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

  • options Object (オプション)

    • exact ブーリアン (オプション)#

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

戻り値

highlight​

追加: v1.20 locator.highlight

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

使用法

await locator.highlight();

戻り値

hover​

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

マッチする要素にマウスオーバーします。

使用法

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

引数

  • options Object (オプション)

    • force ブーリアン (オプション)#

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

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

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

    • noWaitAfter ブーリアン (オプション)追加バージョン: v1.28#

      非推奨

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

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

    • position オブジェクト (オプション)#

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

    • timeout 数値 (オプション)#

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

    • trial ブーリアン (オプション)#

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

戻り値

詳細

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

  1. forceオプションが設定されていない限り、要素に対するアクション可能性のチェックを待ちます。
  2. 必要に応じて要素をビューにスクロールします。
  3. page.mouseを使用して、要素の中心、または指定された位置にマウスオーバーします。

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

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

innerHTML​

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

element.innerHTMLを返します。

使用法

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

引数

戻り値

innerText​

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

element.innerTextを返します。

テキストのアサート

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

使用法

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

引数

戻り値

inputValue​

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

マッチする<input>、<textarea>、または<select>要素の値を返します。

値のアサート

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

使用法

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

引数

戻り値

詳細

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

isChecked​

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

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

チェック状態のアサート

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

使用法

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

引数

戻り値

isDisabled​

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

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

無効状態のアサート

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

使用法

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

引数

戻り値

isEditable​

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

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

編集可能状態のアサート

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

使用法

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

引数

戻り値

isEnabled​

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

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

有効状態のアサート

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

使用法

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

引数

戻り値

isHidden​

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

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

可視性のアサート

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

使用法

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

引数

  • options Object (オプション)

    • timeout 数値 (オプション)#

      非推奨

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

戻り値

isVisible​

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

要素が可視かどうかを返します。

可視性のアサート

要素が可視であることをアサートする必要がある場合は、不安定さを避けるためにexpect(locator).toBeVisible()を使用してください。詳細については、アサートガイドを参照してください。

使用法

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

引数

  • options Object (オプション)

    • timeout 数値 (オプション)#

      非推奨

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

戻り値

last​

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

最後のマッチする要素へのロケーターを返します。

使用法

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

戻り値

locator​

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

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

ロケーターについて詳しく学ぶ.

使用法

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

引数

  • selectorOrLocator 文字列 | Locator#

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

  • options Object (オプション)

    • has Locator (オプション)#

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

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

      外部および内部ロケーターは同じフレームに属している必要があります。内部ロケーターはFrameLocatorを含んではなりません。

    • hasNot Locator (オプション)追加: v1.33#

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

      外部および内部ロケーターは同じフレームに属している必要があります。内部ロケーターはFrameLocatorを含んではなりません。

    • hasNotText 文字列 | RegExp (オプション)追加: v1.33#

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

    • hasText 文字列 | RegExp (オプション)#

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

戻り値

nth​

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

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

使用法

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

引数

戻り値

or​

追加: v1.33 locator.or

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

両方のロケーターが何かにマッチする場合、結果のロケーターには複数のマッチが含まれるため、ロケーターの厳密性違反を引き起こす可能性があることに注意してください。

使用法

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

注

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

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();

引数

  • locator Locator#

    マッチする代替ロケーター。

戻り値

page​

追加: v1.19 locator.page

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

使用法

locator.page();

戻り値

press​

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

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

使用法

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

引数

  • key 文字列#

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

  • options Object (オプション)

    • delay 数値 (オプション)#

      keydownとkeyupの間に待機するミリ秒単位の時間。デフォルトは0です。

    • noWaitAfter ブーリアン (オプション)#

      非推奨

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

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

    • timeout 数値 (オプション)#

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

戻り値

詳細

要素にフォーカスし、その後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 が単一の文字の場合、大文字と小文字は区別されます。したがって、a と A の値はそれぞれ異なるテキストを生成します。

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

pressSequentially​

追加バージョン: v1.38 locator.pressSequentially
ヒント

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

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

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

使用法

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

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

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

引数

  • text string#

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

  • options Object (オプション)

    • delay number (optional)#

      キー入力間の待機時間（ミリ秒）。デフォルトは0です。

    • noWaitAfter boolean (optional)#

      非推奨

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

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

    • timeout number (optional)#

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

戻り値

screenshot​

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

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

使用法

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

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

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

引数

  • options Object (オプション)

    • animations "disabled" | "allow" (optional)#

      "disabled"に設定すると、CSSアニメーション、CSSトランジション、Webアニメーションが停止します。アニメーションは、その持続時間によって異なる扱いを受けます

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

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

    • caret "hide" | "initial" (optional)#

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

    • mask Array<Locator> (optional)#

      スクリーンショットを撮るときにマスクするロケーターを指定します。マスクされた要素は、そのバウンディングボックスを完全に覆うピンクのボックス#FF00FF（maskColorでカスタマイズ）でオーバーレイされます。マスクは不可視要素にも適用されます。可視要素のみを一致させるを参照して、これを無効にすることができます。

    • maskColor string (optional)追加バージョン: v1.35#

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

    • omitBackground boolean (optional)#

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

    • path string (optional)#

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

    • quality number (optional)#

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

    • scale "css" | "device" (optional)#

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

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

    • style string (optional)追加バージョン: v1.41#

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

    • timeout number (optional)#

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

    • type "png" | "jpeg" (optional)#

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

戻り値

詳細

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

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

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

scrollIntoViewIfNeeded​

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

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

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

使用法

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

引数

戻り値

selectOption​

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

<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.selectOption('blue');

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

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

引数

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

    • value string (optional)

      option.valueで一致します。オプション。

    • label string (optional)

      option.labelで一致します。オプション。

    • index number (optional)

      インデックスで一致します。オプション。

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

    • force boolean (optional)#

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

    • noWaitAfter boolean (optional)#

      非推奨

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

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

    • timeout number (optional)#

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

戻り値

詳細

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

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

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

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

selectText​

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

このメソッドはアクション性チェックを待ち、その後、要素にフォーカスし、そのテキストコンテンツ全体を選択します。

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

使用法

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

引数

戻り値

setChecked​

追加バージョン: v1.15 locator.setChecked

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

使用法

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

引数

  • checked boolean#

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

  • options Object (オプション)

    • force boolean (optional)#

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

    • noWaitAfter boolean (optional)#

      非推奨

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

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

    • position Object (optional)#

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

    • timeout number (optional)#

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

    • trial boolean (optional)#

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

戻り値

詳細

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

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

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

setInputFiles​

追加バージョン: v1.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')
});

引数

戻り値

詳細

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

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

tap​

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

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

使用法

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

引数

  • options Object (オプション)

    • force boolean (optional)#

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

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

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

    • noWaitAfter boolean (optional)#

      非推奨

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

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

    • position Object (optional)#

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

    • timeout number (optional)#

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

    • trial boolean (optional)#

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

戻り値

詳細

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

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

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

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

注

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

textContent​

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

node.textContentを返します。

テキストのアサート

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

使用法

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

引数

戻り値

uncheck​

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

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

使用法

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

引数

  • options Object (オプション)

    • force boolean (optional)#

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

    • noWaitAfter boolean (optional)#

      非推奨

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

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

    • position Object (optional)#

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

    • timeout number (optional)#

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

    • trial boolean (optional)#

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

戻り値

詳細

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

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

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

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

waitFor​

追加バージョン: v1.16 locator.waitFor

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

ターゲット要素が既に条件を満たしている場合、メソッドはすぐに返ります。そうでない場合、条件が満たされるまで最大タイムアウトミリ秒待機します。

使用法

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

引数

  • options Object (オプション)

    • state "attached" | "detached" | "visible" | "hidden" (optional)#

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

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

    • timeout number (optional)#

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

戻り値

非推奨​

elementHandle​

追加バージョン: v1.14 locator.elementHandle
推奨されない

ロケーターとWebアサーションをElementHandleよりも常に優先してください。後者は本質的に競合状態になりやすいためです。

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

使用法

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

引数

戻り値

elementHandles​

追加バージョン: v1.14 locator.elementHandles
推奨されない

ロケーターとWebアサーションをElementHandleよりも常に優先してください。後者は本質的に競合状態になりやすいためです。

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

使用法

await locator.elementHandles();

戻り値

type​

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

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

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

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

使用法

引数

  • text string#

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

  • options Object (オプション)

    • delay number (optional)#

      キー入力間の待機時間（ミリ秒）。デフォルトは0です。

    • noWaitAfter boolean (optional)#

      非推奨

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

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

    • timeout number (optional)#

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

戻り値