ロケーター

はじめに

ロケーターは、Playwrightの自動待機と再試行可能性の中心となるものです。簡単に言えば、ロケーターはいつでもページ上の要素を見つける方法を表します。

クイックガイド

以下は推奨される組み込みロケーターです。

• Page.getByRole()：明示的および暗黙的なアクセシビリティ属性で要素を特定します。
• Page.getByText()：テキストコンテンツで要素を特定します。
• Page.getByLabel()：関連付けられたラベルのテキストでフォームコントロールを特定します。
• Page.getByPlaceholder()：プレースホルダーで入力を特定します。
• Page.getByAltText()：要素（通常は画像）をその代替テキストで特定します。
• Page.getByTitle()：要素をそのタイトル属性で特定します。
• Page.getByTestId()：data-testid属性に基づいて要素を特定します（他の属性も設定できます）。

page.getByLabel("User Name").fill("John");

page.getByLabel("Password").fill("secret-password");

page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
    .click();

assertThat(page.getByText("Welcome, John!")).isVisible();

要素の特定

Playwrightには複数の組み込みロケーターがあります。テストを堅牢にするために、ユーザーに表示される属性やPage.getByRole()のような明示的な契約を優先することをお勧めします。

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

https://:3000

<button>Sign in</button>

「Sign in」という名前のbuttonの役割で要素を特定します。

page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
    .click();

注

コードジェネレーターを使用してロケーターを生成し、必要に応じて編集します。

ロケーターがアクションに使用されるたびに、最新のDOM要素がページ内で特定されます。以下のスニペットでは、基になるDOM要素が各アクションの前に2回特定されます。これは、再レンダリングによって呼び出しの間にDOMが変更された場合、ロケーターに対応する新しい要素が使用されることを意味します。

Locator locator = page.getByRole(AriaRole.BUTTON,
                                 new Page.GetByRoleOptions().setName("Sign in"));

locator.hover();
locator.click();

Page.getByLabel()など、ロケーターを作成するすべてのメソッドは、LocatorおよびFrameLocatorクラスでも利用できるため、それらを連結してロケーターを反復的に絞り込むことができます。

Locator locator = page
    .frameLocator("#my-frame")
    .getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"));

locator.click();

役割による特定

Page.getByRole()ロケーターは、ユーザーや支援技術がページをどのように認識するか、たとえば、ある要素がボタンかチェックボックスかなどを反映します。役割で特定する場合、通常はアクセシブルな名前も渡して、ロケーターが正確な要素を特定できるようにする必要があります。

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

https://:3000

サインアップ

購読

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

各要素をその暗黙的な役割で特定できます。

assertThat(page
    .getByRole(AriaRole.HEADING,
               new Page.GetByRoleOptions().setName("Sign up")))
    .isVisible();

page.getByRole(AriaRole.CHECKBOX,
               new Page.GetByRoleOptions().setName("Subscribe"))
    .check();

page.getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName(
                   Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
    .click();

役割ロケーターには、ボタン、チェックボックス、見出し、リンク、リスト、テーブルなどが含まれ、ARIAロール、ARIA属性、アクセシブルな名前に関するW3C仕様に従います。<button>のような多くのhtml要素には、役割ロケーターによって認識される暗黙的に定義された役割があることに注意してください。

役割ロケーターは、アクセシビリティ監査や適合性テストを置き換えるものではないことに注意してください。むしろ、ARIAガイドラインに関する早期フィードバックを提供します。

役割ロケーターを使用する場合

ユーザーや支援技術がページを認識する方法に最も近い方法であるため、要素を特定するために役割ロケーターを優先することをお勧めします。

ラベルによる特定

ほとんどのフォームコントロールには通常、フォームと対話するのに便利に使える専用のラベルがあります。この場合、Page.getByLabel()を使用して、関連付けられたラベルによってコントロールを特定できます。

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

https://:3000

パスワード

<label>Password <input type="password" /></label>

ラベルテキストで要素を特定した後、入力を埋めることができます。

page.getByLabel("Password").fill("secret");

ラベルロケーターを使用する場合

フォームフィールドを特定する場合にこのロケーターを使用します。

プレースホルダーによる特定

入力には、ユーザーが入力する値をヒントするプレースホルダー属性がある場合があります。Page.getByPlaceholder()を使用して、このような入力を特定できます。

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

https://:3000

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

プレースホルダーテキストで入力を見つけてから、入力できます。

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

プレースホルダーロケーターを使用する場合

ラベルがなく、プレースホルダーテキストがあるフォーム要素を特定する場合に、このロケーターを使用します。

テキストによる特定

要素が含むテキストで要素を見つけます。Page.getByText()を使用する場合、部分文字列、正確な文字列、または正規表現で一致させることができます。

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

https://:3000

ようこそ、ジョンさん

<span>Welcome, John</span>

要素をそれが含むテキストで特定できます

assertThat(page.getByText("Welcome, John")).isVisible();

厳密な一致を設定する

assertThat(page
    .getByText("Welcome, John", new Page.GetByTextOptions().setExact(true)))
    .isVisible();

正規表現で一致

assertThat(page
    .getByText(Pattern.compile("welcome, john$", Pattern.CASE_INSENSITIVE)))
    .isVisible();

注

テキストによる一致は、厳密な一致であっても常に空白を正規化します。例えば、複数のスペースを1つにまとめ、改行をスペースに変換し、先頭と末尾の空白を無視します。

テキストロケーターを使用する場合

div、span、pなどの非対話型要素を見つけるにはテキストロケーターを使用することをお勧めします。button、a、inputなどの対話型要素には役割ロケーターを使用してください。

また、リスト内の特定のアイテムを見つけようとする場合に便利なテキストによるフィルタリングも可能です。

altテキストによる特定

すべての画像には、画像の説明となるalt属性が必要です。Page.getByAltText()を使用して、代替テキストに基づいて画像を特定できます。

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

https://:3000

<img alt="playwright logo" src="/img/playwright-logo.svg" width="100" />

代替テキストで画像を特定した後、クリックできます。

page.getByAltText("playwright logo").click();

altロケーターを使用する場合

imgやarea要素など、altテキストをサポートする要素がある場合にこのロケーターを使用します。

タイトルによる特定

Page.getByTitle()を使用して、一致するタイトル属性を持つ要素を特定します。

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

https://:3000

25件の問題

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

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

assertThat(page.getByTitle("Issues count")).hasText("25 issues");

タイトルロケーターを使用する場合

要素にtitle属性がある場合にこのロケーターを使用します。

テストIDによる特定

テストIDによるテストは、テキストや属性の役割が変更されてもテストが成功するため、最も堅牢なテスト方法です。QAと開発者は明示的なテストIDを定義し、Page.getByTestId()でそれらをクエリする必要があります。ただし、テストIDによるテストはユーザー向けではありません。役割やテキスト値が重要な場合は、役割やテキストロケーターのようなユーザー向けロケーターの使用を検討してください。

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

https://:3000

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

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

page.getByTestId("directions").click();

testidロケーターを使用する場合

テストID方式を使用する場合や、役割やテキストで特定できない場合にもテストIDを使用できます。

カスタムテストID属性を設定する

デフォルトでは、Page.getByTestId()はdata-testid属性に基づいて要素を特定しますが、テスト設定で、またはSelectors.setTestIdAttribute()を呼び出すことで設定できます。

テストIDを設定して、テストにカスタムデータ属性を使用します。

playwright.selectors().setTestIdAttribute("data-pw");

HTMLでは、デフォルトのdata-testidの代わりにdata-pwをテストIDとして使用できるようになりました。

https://:3000

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

そして、通常どおり要素を特定します

page.getByTestId("directions").click();

CSSまたはXPathによる特定

どうしてもCSSまたはXPathロケーターを使用する必要がある場合は、Page.locator()を使用して、ページ内で要素を見つける方法を記述するセレクターを受け取るロケーターを作成できます。PlaywrightはCSSおよびXPathセレクターをサポートしており、css=またはxpath=プレフィックスを省略した場合でも自動検出します。

page.locator("css=button").click();
page.locator("xpath=//button").click();

page.locator("button").click();
page.locator("//button").click();

XPathおよびCSSセレクターは、DOM構造または実装に依存する可能性があります。これらのセレクターは、DOM構造が変更されると壊れる可能性があります。以下の長いCSSまたはXPathチェーンは、不安定なテストにつながる悪い慣行の例です。

page.locator(
    "#tsf > div:nth-child(2) > div.A8SBwf > div.RNNXgb > div > div.a4bIc > input"
).click();

page.locator("//*[@id='tsf']/div[2]/div[1]/div[1]/div/div[2]/input").click();

これを使用する場合

DOMはしばしば変更され、堅牢性のないテストにつながるため、CSSとXPathは推奨されません。代わりに、役割ロケーターなどのユーザーがページを認識する方法に近いロケーターを考案するか、テストIDを使用して明示的なテスト契約を定義することを試みてください。

Shadow DOMでの特定

Playwrightのすべてのロケーターは、デフォルトでShadow DOM内の要素と連携します。例外は以下のとおりです。

• XPathによる特定はシャドウルーツを貫通しません。
• クローズモードのシャドウルーツはサポートされていません。

カスタムWebコンポーネントの次の例を考えてみましょう。

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

シャドウルートが存在しないかのように、同じ方法で特定できます。

<div>Details</div>をクリックするには

page.getByText("Details").click();

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

<x-details>をクリックするには

page.locator("x-details", new Page.LocatorOptions().setHasText("Details"))
    .click();

<x-details role=button aria-expanded=true aria-controls=inner-details>
  <div>Title</div>
  #shadow-root
    <div id=inner-details>Details</div>
</x-details>

<x-details>に「Details」というテキストが含まれていることを確認するには

assertThat(page.locator("x-details")).containsText("Details");

ロケーターのフィルタリング

2番目の製品カードの購入ボタンをクリックしたいという次のDOM構造を考えてみましょう。適切なロケーターを取得するためにロケーターをフィルタリングするにはいくつかのオプションがあります。

https://:3000

• 製品1

• 製品2

<ul>
  <li>
    <h3>Product 1</h3>
    <button>Add to cart</button>
  </li>
  <li>
    <h3>Product 2</h3>
    <button>Add to cart</button>
  </li>
</ul>

テキストによるフィルタリング

ロケーターは、Locator.filter()メソッドでテキストによってフィルタリングできます。これは、要素の内部のどこかに、おそらく子孫要素に、大文字と小文字を区別せずに特定の文字列を検索します。正規表現を渡すこともできます。

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasText("Product 2"))
    .getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName("Add to cart"))
    .click();

正規表現を使用する

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHasText(Pattern.compile("Product 2")))
    .getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName("Add to cart"))
    .click();

テキストがないことによるフィルタリング

あるいは、テキストがないことによるフィルタリング

// 5 in-stock items
assertThat(page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasNotText("Out of stock")))
    .hasCount(5);

子/子孫によるフィルタリング

ロケーターは、別のロケーターに一致する子孫がある、またはない要素のみを選択するオプションをサポートしています。したがって、Locator.getByRole()、Locator.getByTestId()、Locator.getByText()などの他のロケーターでフィルタリングできます。

https://:3000

• 製品1

• 製品2

<ul>
  <li>
    <h3>Product 1</h3>
    <button>Add to cart</button>
  </li>
  <li>
    <h3>Product 2</h3>
    <button>Add to cart</button>
  </li>
</ul>

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHas(page.GetByRole(AriaRole.HEADING, new Page.GetByRoleOptions()
        .setName("Product 2"))))
    .getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName("Add to cart"))
    .click();

また、製品カードが1つしかないことを確認するためにアサートすることもできます。

assertThat(page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHas(page.GetByRole(AriaRole.HEADING,
                               new Page.GetByRoleOptions().setName("Product 2")))))
    .hasCount(1);

フィルタリングロケーターは、元のロケーターに対して相対的でなければならず、ドキュメントルートではなく、元のロケーターの一致から照会されます。したがって、以下のコードは機能しません。なぜなら、フィルタリングロケーターが、元のロケーターによって一致した<li>リストアイテムの外側にある<ul>リスト要素から一致を開始するからです。

// ✖ WRONG
assertThat(page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions()
        .setHas(page.GetByRole(AriaRole.LIST)
                    .GetByRole(AriaRole.HEADING,
                               new Page.GetByRoleOptions().setName("Product 2")))))
    .hasCount(1);

子/子孫がないことによるフィルタリング

また、内部に一致する要素がないことでフィルタリングすることもできます。

assertThat(page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasNot(page.getByText("Product 2"))))
    .hasCount(1);

内部ロケーターは、ドキュメントルートからではなく、外部ロケーターから一致することに注意してください。

ロケーター演算子

ロケーター内部でのマッチング

Page.getByText()やLocator.getByRole()のようなロケーターを作成するメソッドを連鎖させて、検索をページの特定のセクションに絞り込むことができます。

この例では、まずlistitemの役割を特定して「product」というロケーターを作成します。次に、テキストでフィルタリングします。製品ロケーターを再度使用してボタンの役割で取得し、クリックした後、アサーションを使用して「Product 2」というテキストを持つ製品が1つだけであることを確認できます。

Locator product = page
    .getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasText("Product 2"));

product
    .getByRole(AriaRole.BUTTON,
               new Locator.GetByRoleOptions().setName("Add to cart"))
    .click();

また、2つのロケーターを連結することもできます。例えば、特定のダイアログ内の「Save」ボタンを見つける場合などです。

Locator saveButton = page.getByRole(AriaRole.BUTTON,
                                    new Page.GetByRoleOptions().setName("Save"));
// ...
Locator dialog = page.getByTestId("settings-dialog");
dialog.locator(saveButton).click();

2つのロケーターの同時一致

Locator.and()メソッドは、追加のロケーターに一致させることで、既存のロケーターを絞り込みます。例えば、Page.getByRole()とPage.getByTitle()を組み合わせて、役割とタイトルの両方で一致させることができます。

Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));

2つの代替ロケーターのいずれかに一致させる

2つ以上の要素のいずれかをターゲットにしたいが、どれがターゲットになるか分からない場合は、Locator.or()を使用して、いずれかまたは両方の代替要素に一致するロケーターを作成します。

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

注

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

Locator newEmail = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("New"));
Locator dialog = page.getByText("Confirm security settings");
assertThat(newEmail.or(dialog).first()).isVisible();
if (dialog.isVisible())
  page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Dismiss")).click();
newEmail.click();

表示されている要素のみに一致させる

注

可視性をチェックするよりも、要素を一意に識別するより信頼性の高い方法を見つける方が通常は優れています。

最初のボタンが非表示で2番目のボタンが表示されているページを考えてみましょう。

<button style='display: none'>Invisible</button>
<button>Visible</button>

• これにより両方のボタンが見つかり、厳密性違反エラーがスローされます。

  page.locator("button").click();

• これにより、2番目のボタンのみが見つかり、クリックされます。なぜなら、それが表示されているからです。

  page.locator("button").filter(new Locator.FilterOptions.setVisible(true)).click();

リスト

リスト内のアイテムを数える

リスト内のアイテムを数えるために、ロケーターをアサートできます。

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

https://:3000

• りんご
• バナナ
• オレンジ

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

カウントアサーションを使用して、リストに3つのアイテムがあることを確認します。

assertThat(page.getByRole(AriaRole.LISTITEM)).hasCount(3);

リスト内のすべてのテキストをアサートする

リスト内のすべてのテキストを見つけるために、ロケーターをアサートできます。

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

https://:3000

• りんご
• バナナ
• オレンジ

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

assertThat(locator).hasText()を使用して、リストに「apple」、「banana」、「orange」というテキストがあることを確認します。

assertThat(page
    .getByRole(AriaRole.LISTITEM))
    .hasText(new String[] { "apple", "banana", "orange" });

特定のアイテムを取得する

リスト内の特定のアイテムを取得する方法はたくさんあります。

テキストで取得する

Page.getByText()メソッドを使用して、リスト内の要素をテキストコンテンツで特定し、クリックします。

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

https://:3000

• りんご
• バナナ
• オレンジ

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

要素をそのテキストコンテンツで特定し、クリックします。

page.getByText("orange").click();

テキストでフィルタリングする

Locator.filter()を使用して、リスト内の特定のアイテムを特定します。

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

https://:3000

• りんご
• バナナ
• オレンジ

<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

「listitem」の役割でアイテムを特定し、次に「orange」のテキストでフィルタリングし、クリックします。

page.getByRole(AriaRole.LISTITEM)
    .filter(new Locator.FilterOptions().setHasText("orange"))
    .click();

テストIDで取得する

Page.getByTestId()メソッドを使用して、リスト内の要素を特定します。テストIDがまだない場合は、htmlを修正してテストIDを追加する必要がある場合があります。

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

https://:3000

• りんご
• バナナ
• オレンジ

<ul>
  <li data-testid='apple'>apple</li>
  <li data-testid='banana'>banana</li>
  <li data-testid='orange'>orange</li>
</ul>

「orange」のテストIDでアイテムを特定し、クリックします。

page.getByTestId("orange").click();

n番目のアイテムで取得する

同一の要素のリストがあり、それらを区別する唯一の方法が順序である場合、Locator.first()、Locator.last()、またはLocator.nth()を使用してリストから特定の要素を選択できます。

Locator banana = page.getByRole(AriaRole.LISTITEM).nth(1);

ただし、この方法は注意して使用してください。多くの場合、ページが変更され、ロケーターが予期していたものとはまったく異なる要素を指す可能性があります。代わりに、厳密性基準を満たす一意のロケーターを作成するようにしてください。

フィルタの連鎖

さまざまな類似点を持つ要素がある場合、Locator.filter()メソッドを使用して適切な要素を選択できます。複数のフィルタを連鎖させて選択範囲を絞り込むこともできます。

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

https://:3000

• ジョン
• メアリー
• ジョン
• メアリー

<ul>
  <li>
    <div>John</div>
    <div><button>Say hello</button></div>
  </li>
  <li>
    <div>Mary</div>
    <div><button>Say hello</button></div>
  </li>
  <li>
    <div>John</div>
    <div><button>Say goodbye</button></div>
  </li>
  <li>
    <div>Mary</div>
    <div><button>Say goodbye</button></div>
  </li>
</ul>

「Mary」と「Say goodbye」を含む行のスクリーンショットを撮るには

Locator rowLocator = page.getByRole(AriaRole.LISTITEM);

rowLocator
    .filter(new Locator.FilterOptions().setHasText("Mary"))
    .filter(new Locator.FilterOptions()
        .setHas(page.getByRole(
            AriaRole.BUTTON,
            new Page.GetByRoleOptions().setName("Say goodbye"))))
    .screenshot(new Page.ScreenshotOptions().setPath("screenshot.png"));

プロジェクトのルートディレクトリに「screenshot.png」ファイルが作成されているはずです。

まれなユースケース

リスト内の各要素で何かをする

要素を反復処理する

for (Locator row : page.getByRole(AriaRole.LISTITEM).all())
  System.out.println(row.textContent());

通常のforループで反復処理する

Locator rows = page.getByRole(AriaRole.LISTITEM);
int count = rows.count();
for (int i = 0; i < count; ++i)
  System.out.println(rows.nth(i).textContent());

ページ内で評価する

Locator.evaluateAll()内部のコードはページ内で実行され、そこで任意のDOM APIを呼び出すことができます。

Locator rows = page.getByRole(AriaRole.LISTITEM);
Object texts = rows.evaluateAll(
    "list => list.map(element => element.textContent)");

厳密性

ロケーターは厳密です。これは、特定のターゲットDOM要素を意味するロケーターに対するすべての操作が、複数の要素が一致した場合に例外をスローすることを意味します。例えば、DOMに複数のボタンがある場合、次の呼び出しは例外をスローします。

複数ある場合にエラーをスローする

page.getByRole(AriaRole.BUTTON).click();

一方、Playwrightは複数の要素操作を実行する場合を理解しているため、ロケーターが複数の要素に解決された場合でも、次の呼び出しは完全に機能します。

複数の要素があっても問題なく動作する

page.getByRole(AriaRole.BUTTON).count();

Locator.first()、Locator.last()、Locator.nth()を介して、複数の要素が一致した場合に使用する要素をPlaywrightに明示的に指示することで、厳密性チェックをオプトアウトできます。これらのメソッドは、ページが変更されたときにPlaywrightが意図しない要素をクリックする可能性があるため、推奨されません。代わりに、上記のベストプラクティスに従って、ターゲット要素を一意に識別するロケーターを作成してください。

その他のロケーター

あまり一般的に使用されないロケーターについては、その他のロケーターガイドを参照してください。