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

ロケーター

はじめに​

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

クイックガイド​

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

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

await page.getByLabel('Password').fill('secret-password');

await page.getByRole('button', { name: 'Sign in' }).click();

await expect(page.getByText('Welcome, John!')).toBeVisible();

要素の特定​

Playwrightには複数の組み込みロケーターが付属しています。テストを堅牢にするために、page.getByRole() のようなユーザー向けの属性と明示的な契約を優先することをお勧めします。

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

https://:3000
<button>Sign in</button>

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

await page.getByRole('button', { name: 'Sign in' }).click();
注

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

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

const locator = page.getByRole('button', { name: 'Sign in' });

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

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

const locator = page
    .frameLocator('#my-frame')
    .getByRole('button', { name: 'Sign in' });

await locator.click();

役割による特定​

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

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

https://:3000

サインアップ

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

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

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

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

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

ラベルによる特定​

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

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

https://:3000
<label>Password <input type="password" /></label>

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

await page.getByLabel('Password').fill('secret');
ラベルロケーターを使用する場合

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

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

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

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

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

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

await page
    .getByPlaceholder('name@example.com')
    .fill('playwright@microsoft.com');
プレースホルダーロケーターを使用する場合

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

テキストによる特定​

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

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

https://:3000
ようこそ、ジョンさん
<span>Welcome, John</span>

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

await expect(page.getByText('Welcome, John')).toBeVisible();

厳密な一致を設定する

await expect(page.getByText('Welcome, John', { exact: true })).toBeVisible();

正規表現で一致

await expect(page.getByText(/welcome, [A-Za-z]+$/i)).toBeVisible();
注

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

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

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

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

altテキストによる特定​

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

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

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

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

await page.getByAltText('playwright logo').click();
altロケーターを使用する場合

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

タイトルによる特定​

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

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

https://:3000
25件の問題
<span title='Issues count'>25 issues</span>

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

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');
タイトルロケーターを使用する場合

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

テストIDによる特定​

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

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

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

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

await page.getByTestId('directions').click();
testidロケーターを使用する場合

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

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

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

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

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  }
});

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

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

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

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

CSSまたはXPathによる特定​

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

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

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

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

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

await page
    .locator('//*[@id="tsf"]/div[2]/div[1]/div[1]/div/div[2]/input')
    .click();
これを使用する場合

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

Shadow DOMでの特定​

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

カスタム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>をクリックするには

await 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>をクリックするには

await page.locator('x-details', { hasText: '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」というテキストが含まれていることを確認するには

await expect(page.locator('x-details')).toContainText('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() メソッドでテキストによってフィルタリングできます。これは、要素の内部のどこか、おそらく子孫要素の内部で、大文字と小文字を区別せずに特定の文字列を検索します。正規表現を渡すこともできます。

await page
    .getByRole('listitem')
    .filter({ hasText: 'Product 2' })
    .getByRole('button', { name: 'Add to cart' })
    .click();

正規表現を使用する

await page
    .getByRole('listitem')
    .filter({ hasText: /Product 2/ })
    .getByRole('button', { name: 'Add to cart' })
    .click();

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

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

// 5 in-stock items
await expect(page.getByRole('listitem').filter({ hasNotText: 'Out of stock' })).toHaveCount(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>
await page
    .getByRole('listitem')
    .filter({ has: page.getByRole('heading', { name: 'Product 2' }) })
    .getByRole('button', { name: 'Add to cart' })
    .click();

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

await expect(page
    .getByRole('listitem')
    .filter({ has: page.getByRole('heading', { name: 'Product 2' }) }))
    .toHaveCount(1);

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

// ✖ WRONG
await expect(page
    .getByRole('listitem')
    .filter({ has: page.getByRole('list').getByText('Product 2') }))
    .toHaveCount(1);

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

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

await expect(page
    .getByRole('listitem')
    .filter({ hasNot: page.getByText('Product 2') }))
    .toHaveCount(1);

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

ロケーター演算子​

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

page.getByText() や locator.getByRole() のようにロケーターを作成するメソッドをチェーンして、検索をページの特定の部分に絞り込むことができます。

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

const product = page.getByRole('listitem').filter({ hasText: 'Product 2' });

await product.getByRole('button', { name: 'Add to cart' }).click();

await expect(product).toHaveCount(1);

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

const saveButton = page.getByRole('button', { name: 'Save' });
// ...
const dialog = page.getByTestId('settings-dialog');
await dialog.locator(saveButton).click();

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

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

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

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

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

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

注

"New email" ボタンとセキュリティダイアログの両方が画面に表示された場合、"or" ロケーターは両方に一致し、"strict mode violation" エラーをスローする可能性があります。この場合、locator.first() を使用して、いずれか1つのみに一致させることができます。

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

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

注

通常、可視性をチェックするよりも、要素を一意に識別するより信頼性の高い方法を見つける方が良いでしょう。

2つのボタンがあるページを考えます。最初のボタンは非表示で、2番目のボタンは表示されています。

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

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

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

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

    await page.locator('button').filter({ visible: true }).click();

リスト​

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

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

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

https://:3000
  • りんご
  • バナナ
  • オレンジ
<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

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

await expect(page.getByRole('listitem')).toHaveCount(3);

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

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

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

https://:3000
  • りんご
  • バナナ
  • オレンジ
<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

リストに「apple」、「banana」、「orange」のテキストが含まれていることを確認するには、expect(locator).toHaveText() を使用します。

await expect(page
    .getByRole('listitem'))
    .toHaveText(['apple', 'banana', 'orange']);

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

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

テキストで取得する​

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

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

https://:3000
  • りんご
  • バナナ
  • オレンジ
<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

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

await page.getByText('orange').click();

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

リスト内の特定の項目を特定するには、locator.filter() を使用します。

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

https://:3000
  • りんご
  • バナナ
  • オレンジ
<ul>
  <li>apple</li>
  <li>banana</li>
  <li>orange</li>
</ul>

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

await page
    .getByRole('listitem')
    .filter({ hasText: '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でアイテムを特定し、クリックします。

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

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

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

const banana = await page.getByRole('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」を含む行のスクリーンショットを撮るには

const rowLocator = page.getByRole('listitem');

await rowLocator
    .filter({ hasText: 'Mary' })
    .filter({ has: page.getByRole('button', { name: 'Say goodbye' }) })
    .screenshot({ path: 'screenshot.png' });

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

まれなユースケース​

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

要素を反復処理する

for (const row of await page.getByRole('listitem').all())
  console.log(await row.textContent());

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

const rows = page.getByRole('listitem');
const count = await rows.count();
for (let i = 0; i < count; ++i)
  console.log(await rows.nth(i).textContent());

ページ内で評価する​

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

const rows = page.getByRole('listitem');
const texts = await rows.evaluateAll(
    list => list.map(element => element.textContent));

厳密性​

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

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

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

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

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

await page.getByRole('button').count();

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

その他のロケーター​

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