ロケーター

ロケーターは、待機とアクションの機能を組み合わせた新しい実験的な API です。追加の前提条件チェックにより、失敗したアクションの自動再試行が可能になり、より信頼性が高く、不安定さの少ない自動化スクリプトが実現します。

注記

ロケーター API は実験段階であり、ロケーター API の破壊的な変更に対してはセマンティックバージョニングに従いません。

ユースケース

要素の待機

await page.locator('button').wait();

以下の前提条件が自動的にチェックされます

• 要素が表示または非表示になるのを待ちます。

関数の待機

await page
  .locator(() => {
    let resolve!: (node: HTMLCanvasElement) => void;
    const promise = new Promise(res => {
      return (resolve = res);
    });
    const observer = new MutationObserver(records => {
      for (const record of records) {
        if (record.target instanceof HTMLCanvasElement) {
          resolve(record.target);
        }
      }
    });
    observer.observe(document);
    return promise;
  })
  .wait();

要素のクリック

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

以下の前提条件が自動的にチェックされます

• 要素がビューポート内にあることを確認します。
• 要素が表示または非表示になるのを待ちます。
• 要素が有効になるのを待ちます。
• 要素が連続する 2 つのアニメーションフレームで安定したバウンディングボックスを持つようになるのを待ちます。

条件に一致する要素のクリック

await page
  .locator('button')
  .filter(button => !button.disabled)
  .click();

以下の前提条件が自動的にチェックされます

• 要素がビューポート内にあることを確認します。
• 要素が表示または非表示になるのを待ちます。
• 要素が有効になるのを待ちます。
• 要素が連続する 2 つのアニメーションフレームで安定したバウンディングボックスを持つようになるのを待ちます。

入力の入力

await page.locator('input').fill('value');

入力タイプを自動的に検出し、指定された値で入力する適切な方法を選択します。

以下の前提条件が自動的にチェックされます

• 要素がビューポート内にあることを確認します。
• 要素が表示または非表示になるのを待ちます。
• 要素が有効になるのを待ちます。
• 要素が連続する 2 つのアニメーションフレームで安定したバウンディングボックスを持つようになるのを待ちます。

要素プロパティの取得

const enabled = await page
  .locator('button')
  .map(button => !button.disabled)
  .wait();

要素にカーソルを合わせる

await page.locator('div').hover();

以下の前提条件が自動的にチェックされます

• 要素がビューポート内にあることを確認します。
• 要素が表示または非表示になるのを待ちます。
• 要素が連続する 2 つのアニメーションフレームで安定したバウンディングボックスを持つようになるのを待ちます。

要素のスクロール

await page.locator('div').scroll({
  scrollLeft: 10,
  scrollTop: 20,
});

以下の前提条件が自動的にチェックされます

• 要素がビューポート内にあることを確認します。
• 要素が表示または非表示になるのを待ちます。
• 要素が連続する 2 つのアニメーションフレームで安定したバウンディングボックスを持つようになるのを待ちます。

ロケーターの構成

ロケーターは、前提条件やその他のオプションを調整するように構成できます

await page
  .locator('button')
  .setEnsureElementIsInTheViewport(false)
  .setTimeout(0)
  .setVisibility(null)
  .setWaitForEnabled(false)
  .setWaitForStableBoundingBox(false)
  .click();

ロケーターイベントの取得

現在、ロケーターは、ロケーターがアクションを実行しようとしているときに通知する単一のイベントをサポートしています

let willClick = false;
await page
  .locator('button')
  .on(LocatorEvent.Action, () => {
    willClick = true;
  })
  .click();

このイベントは、ログ/デバッグまたはその他の目的で使用できます。ロケーターがアクションを再試行すると、イベントが複数回発生する可能性があります。