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

その他のロケーター

はじめに​

注記

最も一般的でおすすめのロケーターについては、メインのロケーターガイドをご覧ください。

page.get_by_role()やpage.get_by_text()のような推奨されるロケーターに加えて、Playwright はこのガイドで説明されているさまざまな他のロケーターをサポートしています。

CSS ロケーター​

注記

実装に依存し、ページが変更されたときに壊れる可能性がある CSS を使用する代わりに、テキストやアクセシブルなロールのようなユーザーに見えるロケーターを優先することをお勧めします。

Playwright は CSS セレクターで要素を特定できます。

page.locator("css=button").click()

Playwright は標準の CSS セレクターを 2 つの方法で拡張します。

  • CSS セレクターはシャドウ DOM を透過します。
  • Playwright は、:visible、:has-text()、:has()、:is()、:nth-match()などのカスタム疑似クラスを追加します。

CSS: テキストによるマッチング​

Playwright には、要素をテキストコンテンツでマッチングするための多数の CSS 疑似クラスが含まれています。

  • article:has-text("Playwright") - :has-text() は、指定されたテキストを内部のどこか（子要素または子孫要素内にある可能性あり）に含む任意の要素にマッチングします。マッチングは大文字と小文字を区別せず、空白をトリムし、部分文字列を検索します。

    たとえば、article:has-text("Playwright") は <article><div>Playwright</div></article> にマッチングします。

    :has-text() は他の CSS 指定子と一緒に使用する必要があることに注意してください。そうしないと、<body> を含む、指定されたテキストを含むすべての要素にマッチングします。

    # Wrong, will match many elements including <body>
    page.locator(':has-text("Playwright")').click()
    # Correct, only matches the <article> element
    page.locator('article:has-text("All products")').click()

  • #nav-bar :text("Home") - :text() 疑似クラスは、指定されたテキストを含む最小の要素にマッチングします。マッチングは大文字と小文字を区別せず、空白をトリムし、部分文字列を検索します。

    たとえば、これは #nav-bar 要素内のどこかに "Home" というテキストを持つ要素を見つけます。

    page.locator("#nav-bar :text('Home')").click()

  • #nav-bar :text-is("Home") - :text-is() 疑似クラスは、正確なテキストを持つ最小の要素にマッチングします。正確なマッチングは大文字と小文字を区別し、空白をトリムし、完全な文字列を検索します。

    たとえば、:text-is("Log") は <button>Log in</button> にはマッチングしません。なぜなら、<button> には "Log" と等しくない単一のテキストノード "Log in" が含まれているからです。しかし、:text-is("Log") は <button> Log <span>in</span></button> にマッチングします。なぜなら、<button> にはテキストノード " Log " が含まれているからです。

    同様に、:text-is("Download") は大文字と小文字を区別するため、<button>download</button> にはマッチングしません。

  • #nav-bar :text-matches("reg?ex", "i") - :text-matches() 疑似クラスは、JavaScript のような正規表現にマッチングするテキストコンテンツを持つ最小の要素にマッチングします。

    たとえば、:text-matches("Log\s*in", "i") は <button>Login</button> と <button>log IN</button> にマッチングします。

注記

テキストマッチングは常に空白を正規化します。たとえば、複数のスペースを 1 つに変換し、改行をスペースに変換し、先頭と末尾の空白を無視します。

注記

button および submit タイプの入力要素は、テキストコンテンツの代わりに value でマッチングされます。たとえば、:text("Log in") は <input type=button value="Log in"> にマッチングします。

CSS: 可視要素のみのマッチング​

Playwright は CSS セレクターで :visible 疑似クラスをサポートしています。たとえば、css=button はページ上のすべてのボタンにマッチングしますが、css=button:visible は可視のボタンのみにマッチングします。これは、非常によく似ているが可視性が異なる要素を区別するのに役立ちます。

最初に非表示、次に表示の 2 つのボタンがあるページを考えてみましょう。

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

  • これは両方のボタンを見つけて、strictness 違反エラーをスローします。

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

  • これは 2 番目のボタンのみを見つけ、それが可視であるため、それをクリックします。

    page.locator("button:visible").click()

CSS: 他の要素を含む要素​

:has() 疑似クラスは、実験的な CSS 疑似クラスです。与えられた要素の :scope に相対的なパラメータとして渡されたセレクターのいずれかが少なくとも 1 つの要素にマッチングする場合、要素を返します。

次のスニペットは、内部に <div class=promo> を持つ <article> 要素のテキストコンテンツを返します。

page.locator("article:has(div.promo)").text_content()

CSS: 条件の 1 つにマッチングする要素​

コンマ区切りの CSS セレクターのリストは、そのリスト内のセレクターの 1 つで選択できるすべての要素にマッチングします。

# Clicks a <button> that has either a "Log in" or "Sign in" text.
page.locator('button:has-text("Log in"), button:has-text("Sign in")').click()

:is() 疑似クラスは、要素に追加の条件のリストを指定するのに役立つ可能性がある実験的な CSS 疑似クラスです。

CSS: レイアウトに基づく要素のマッチング​

注記

レイアウトに基づくマッチングは、予期しない結果を生み出す可能性があります。たとえば、レイアウトが 1 ピクセル変化すると、異なる要素がマッチングされる可能性があります。

場合によっては、ターゲット要素に特徴的な機能がない場合、ターゲット要素への適切なセレクターを思い付くのが難しいことがあります。この場合、Playwright レイアウト CSS 疑似クラスを使用すると役立つ可能性があります。これらは、通常の CSS と組み合わせて、複数の選択肢の 1 つを特定できます。

たとえば、input:right-of(:text("Password")) は、テキスト "Password" の右側にある入力フィールドにマッチングします。これは、ページに互いに区別するのが難しい複数の入力がある場合に役立ちます。

レイアウト疑似クラスは、input のような他の何かに加えて役立つことに注意してください。:right-of(:text("Password")) のようにレイアウト疑似クラスを単独で使用すると、探している入力ではなく、テキストとターゲット入力の間にある空の要素が取得される可能性が高くなります。

レイアウト疑似クラスは、要素の距離と相対位置を計算するために、bounding client rect を使用します。

  • :right-of(div > button) - 内部セレクターにマッチングする任意の要素の右側にある要素を、任意の垂直位置でマッチングします。
  • :left-of(div > button) - 内部セレクターにマッチングする任意の要素の左側にある要素を、任意の垂直位置でマッチングします。
  • :above(div > button) - 内部セレクターにマッチングする任意の要素の上にある要素を、任意の水平位置でマッチングします。
  • :below(div > button) - 内部セレクターにマッチングする任意の要素の下にある要素を、任意の水平位置でマッチングします。
  • :near(div > button) - 内部セレクターにマッチングする任意の要素の近く（50 CSS ピクセル以内）にある要素をマッチングします。

結果として得られるマッチングは、アンカー要素までの距離でソートされるため、最も近いものを選択するためにlocator.firstを使用できます。これは、最も近いものが明らかに正しいものである、類似した要素のリストのようなものがある場合にのみ役立ちます。ただし、他のケースでlocator.firstを使用しても、期待どおりに機能しない可能性が高くなります。検索している要素ではなく、ランダムな空の <div> や、スクロールアウトされて現在表示されていない要素のように、最も近い要素になる可能性のある他の要素をターゲットにすることになります。

# Fill an input to the right of "Username".
page.locator("input:right-of(:text(\"Username\"))").fill("value")

# Click a button near the promo card.
page.locator("button:near(.promo-card)").click()

# Click the radio input in the list closest to the "Label 3".
page.locator("[type=radio]:left-of(:text(\"Label 3\"))").first.click()

すべてのレイアウト疑似クラスは、オプションの最大ピクセル距離を最後の引数としてサポートしています。たとえば、button:near(:text("Username"), 120) は、テキスト "Username" を持つ要素から最大 120 CSS ピクセル離れたボタンにマッチングします。

CSS: クエリ結果から n 番目のマッチングを選択​

注記

通常、ページ変更に対してより回復力のある属性またはテキストコンテンツによって要素を区別することが可能です。

ページに多数の類似した要素が含まれており、特定の要素を選択するのが難しい場合があります。たとえば

<section> <button>Buy</button> </section>
<article><div> <button>Buy</button> </div></article>
<div><div> <button>Buy</button> </div></div>

この場合、:nth-match(:text("Buy"), 3) は上記のコードスニペットから 3 番目のボタンを選択します。インデックスは 1 から始まることに注意してください。

# Click the third "Buy" button
page.locator(":nth-match(:text('Buy'), 3)").click()

:nth-match() は、locator.wait_for() を使用して、指定された数の要素が表示されるまで待機する場合にも役立ちます。

# Wait until all three buttons are visible
page.locator(":nth-match(:text('Buy'), 3)").wait_for()
注記

:nth-child() とは異なり、要素は兄弟である必要はなく、ページのどこにあってもかまいません。上記のコードスニペットでは、3 つのボタンすべてが :text("Buy") セレクターにマッチングし、:nth-match() は 3 番目のボタンを選択します。

N 番目の要素ロケーター​

ゼロベースのインデックスを渡す nth= ロケーターを使用して、クエリを n 番目のマッチングに絞り込むことができます。

# Click first button
page.locator("button").locator("nth=0").click()

# Click last button
page.locator("button").locator("nth=-1").click()

親要素ロケーター​

他の要素の親要素をターゲットにする必要がある場合、ほとんどの場合、子ロケーターによってlocator.filter()を使用する必要があります。たとえば、次の DOM 構造を考えてみましょう。

<li><label>Hello</label></li>
<li><label>World</label></li>

テキスト "Hello" を持つラベルの親 <li> をターゲットにしたい場合は、locator.filter() を使用するのが最適です。

child = page.get_by_text("Hello")
parent = page.get_by_role("listitem").filter(has=child)

または、親要素に適したロケーターが見つからない場合は、xpath=.. を使用します。この方法は信頼性が低いことに注意してください。DOM 構造への変更はテストを壊すためです。可能な場合は、locator.filter() を優先してください。

parent = page.get_by_text("Hello").locator('xpath=..')

React ロケーター​

注記

React ロケーターは実験的であり、_ がプレフィックスとして付いています。機能は将来変更される可能性があります。

React ロケーターを使用すると、コンポーネント名とプロパティ値で要素を見つけることができます。構文はCSS 属性セレクターと非常によく似ており、すべての CSS 属性セレクター演算子をサポートしています。

React ロケーターでは、コンポーネント名はキャメルケースで記述されます。

page.locator("_react=BookItem").click()

その他の例

  • コンポーネントでマッチング: _react=BookItem
  • コンポーネントと正確なプロパティ値（大文字と小文字を区別）でマッチング: _react=BookItem[author = "Steven King"]
  • プロパティ値のみでマッチング（大文字と小文字を区別しない）: _react=[author = "steven king" i]
  • コンポーネントと真偽値のプロパティ値でマッチング: _react=MyButton[enabled]
  • コンポーネントとブール値でマッチング: _react=MyButton[enabled = false]
  • プロパティの値の部分文字列でマッチング: _react=[author *= "King"]
  • コンポーネントと複数のプロパティでマッチング: _react=BookItem[author *= "king" i][year = 1990]
  • ネストされたプロパティ値でマッチング: _react=[some.nested.value = 12]
  • コンポーネントとプロパティ値のプレフィックスでマッチング: _react=BookItem[author ^= "Steven"]
  • コンポーネントとプロパティ値のサフィックスでマッチング: _react=BookItem[author $= "Steven"]
  • コンポーネントとキーでマッチング: _react=BookItem[key = '2']
  • プロパティ値の正規表現でマッチング: _react=[author = /Steven(\\s+King)?/i]

ツリー内の React 要素名を見つけるには、React DevTools を使用してください。

注記

React ロケーターは React 15 以降をサポートしています。

注記

React ロケーターは、React DevTools と同様に、minify されていないアプリケーションビルドに対してのみ機能します。

Vue ロケーター​

注記

Vue ロケーターは実験的であり、_ がプレフィックスとして付いています。機能は将来変更される可能性があります。

Vue ロケーターを使用すると、コンポーネント名とプロパティ値で要素を見つけることができます。構文はCSS 属性セレクターと非常によく似ており、すべての CSS 属性セレクター演算子をサポートしています。

Vue ロケーターでは、コンポーネント名はケバブケースで記述されます。

page.locator("_vue=book-item").click()

その他の例

  • コンポーネントでマッチング: _vue=book-item
  • コンポーネントと正確なプロパティ値（大文字と小文字を区別）でマッチング: _vue=book-item[author = "Steven King"]
  • プロパティ値のみでマッチング（大文字と小文字を区別しない）: _vue=[author = "steven king" i]
  • コンポーネントと真偽値のプロパティ値でマッチング: _vue=my-button[enabled]
  • コンポーネントとブール値でマッチング: _vue=my-button[enabled = false]
  • プロパティの値の部分文字列でマッチング: _vue=[author *= "King"]
  • コンポーネントと複数のプロパティでマッチング: _vue=book-item[author *= "king" i][year = 1990]
  • ネストされたプロパティ値でマッチング: _vue=[some.nested.value = 12]
  • コンポーネントとプロパティ値のプレフィックスでマッチング: _vue=book-item[author ^= "Steven"]
  • コンポーネントとプロパティ値のサフィックスでマッチング: _vue=book-item[author $= "Steven"]
  • プロパティ値の正規表現でマッチング: _vue=[author = /Steven(\\s+King)?/i]

ツリー内の Vue 要素名を見つけるには、Vue DevTools を使用してください。

注記

Vue ロケーターは Vue2 以降をサポートしています。

注記

Vue ロケーターは、Vue DevTools と同様に、minify されていないアプリケーションビルドに対してのみ機能します。

XPath ロケーター​

警告

実装に依存し、ページが変更されたときに簡単に壊れる XPath を使用する代わりに、テキストやアクセシブルなロールのようなユーザーに見えるロケーターを優先することをお勧めします。

XPath ロケーターは、Document.evaluate の呼び出しと同等です。

page.locator("xpath=//button").click()
注記

// または .. で始まるセレクター文字列は、xpath セレクターと見なされます。たとえば、Playwright は '//html/body' を 'xpath=//html/body' に変換します。

注記

XPath はシャドウルートを透過しません。

XPath ユニオン​

パイプ演算子 (|) を使用して、XPath で複数のセレクターを指定できます。それは、そのリスト内のセレクターの 1 つで選択できるすべての要素にマッチングします。

# Waits for either confirmation dialog or load spinner.
page.locator("//span[contains(@class, 'spinner__loading')]|//div[@id='confirmation']").wait_for()

ラベルからフォームコントロールへのリターゲティング​

警告

ラベルからコントロールへのリターゲティングに依存する代わりに、ラベルテキストでロケートすることをお勧めします。

Playwright のターゲット入力アクションは、ラベルとコントロールを自動的に区別するため、関連付けられたコントロールに対してアクションを実行するためにラベルをターゲットにすることができます。

たとえば、次の DOM 構造を考えてみましょう: <label for="password">Password:</label><input id="password" type="password">。page.get_by_text() を使用して、その "Password" テキストでラベルをターゲットにすることができます。ただし、次のアクションはラベルの代わりに input で実行されます。

# Fill the input by targeting the label.
page.get_by_text("Password").fill("secret")

ただし、他のメソッドはラベル自体をターゲットにします。たとえば、expect(locator).to_have_text() は、入力フィールドではなく、ラベルのテキストコンテンツをアサートします。

# Fill the input by targeting the label.
expect(page.locator("label")).to_have_text("Password")

レガシーテキストロケーター​

警告

代わりに、最新のテキストロケーターをお勧めします。

レガシーテキストロケーターは、渡されたテキストを含む要素にマッチングします。

page.locator("text=Log in").click()

レガシーテキストロケーターにはいくつかのバリエーションがあります。

  • text=Log in - デフォルトのマッチングは大文字と小文字を区別せず、空白をトリムし、部分文字列を検索します。たとえば、text=Log は <button>Log in</button> にマッチングします。

    page.locator("text=Log in").click()

  • text="Log in" - テキスト本体は、空白をトリムした後の正確なコンテンツを持つテキストノードを検索するために、単一引用符または二重引用符でエスケープできます。

    たとえば、text="Log" は <button>Log in</button> にはマッチングしません。なぜなら、<button> には "Log" と等しくない単一のテキストノード "Log in" が含まれているからです。しかし、text="Log" は <button> Log <span>in</span></button> にマッチングします。なぜなら、<button> にはテキストノード " Log " が含まれているからです。この正確なモードは大文字と小文字を区別するマッチングを意味するため、text="Download" は <button>download</button> にはマッチングしません。

    引用符で囲まれた本体は、通常のエスケープ規則に従います。たとえば、二重引用符で囲まれた文字列で二重引用符をエスケープするには \" を使用します: text="foo\"bar"。

    page.locator("text='Log in'").click()

  • /Log\s*in/i - 本体は / 記号で囲まれた JavaScript のような正規表現にすることができます。たとえば、text=/Log\s*in/i は <button>Login</button> と <button>log IN</button> にマッチングします。

    page.locator("text=/Log\s*in/i").click()
注記

引用符 (" または ') で始まり、終わる文字列セレクターは、レガシーテキストロケーターと見なされます。たとえば、"Log in" は内部的に text="Log in" に変換されます。

注記

マッチングは常に空白を正規化します。たとえば、複数のスペースを 1 つに変換し、改行をスペースに変換し、先頭と末尾の空白を無視します。

注記

button および submit タイプの入力要素は、テキストコンテンツの代わりに value でマッチングされます。たとえば、text=Log in は <input type=button value="Log in"> にマッチングします。

id, data-testid, data-test-id, data-test セレクター​

警告

代わりに、テスト ID でロケートすることをお勧めします。

Playwright は、特定の属性を使用して要素を選択するための省略形をサポートしています。現在、次の属性のみがサポートされています。

  • id
  • data-testid
  • data-test-id
  • data-test
# Fill an input with the id "username"
page.locator('id=username').fill('value')

# Click an element with data-test-id "submit"
page.locator('data-test-id=submit').click()
注記

属性セレクターは CSS セレクターではないため、:enabled のような CSS 固有のものはサポートされていません。より多くの機能については、適切な css セレクターを使用してください。例: css=[data-test="login"]:enabled。

セレクターのチェイン​

警告

代わりに、ロケーターのチェインをお勧めします。

engine=body または短縮形で定義されたセレクターは、>> トークンと組み合わせることができます。例: selector1 >> selector2 >> selectors3。セレクターがチェインされると、次のセレクターは前のセレクターの結果に相対的にクエリされます。

たとえば、

css=article >> css=.bar > .baz >> css=span[attr=value]

は下記と同じです

document
    .querySelector('article')
    .querySelector('.bar > .baz')
    .querySelector('span[attr=value]');

セレクターが本体に >> を含める必要がある場合は、チェイン区切り文字と混同されないように、文字列内でエスケープする必要があります。例: text="some >> text"。

中間マッチング​

警告

他の要素を含む要素をロケートするには、別のロケーターでフィルタリングすることをお勧めします。

デフォルトでは、チェインされたセレクターは、最後のセレクターによってクエリされた要素に解決されます。セレクターには、中間セレクターによってクエリされた要素をキャプチャするために * をプレフィックスとして付けることができます。

たとえば、css=article >> text=Hello はテキスト Hello を持つ要素をキャプチャし、*css=article >> text=Hello (* に注意) はテキスト Hello を持つ要素を含む article 要素をキャプチャします。