ブラウザテストでは、カスタム検索ステップが [ロケーター] フィールドを使用して要素をターゲットにします。このフィールドは、CSS、XPath、Playwrightのロケーター構文を1つの文字列として受け付けます。この記事では、mablがサポートするロケーター構文と、それぞれのタイプの記述方法について説明します。
ブラウザテストのみ
カスタム検索ステップは、ブラウザテストでのみサポートされています。モバイルアプリでの要素のターゲット設定については、モバイルテストで信頼性の高い検索ステップを作成するを参照してください。
カスタム検索ステップを追加するタイミングと方法の詳しい手順については、カスタム検索ステップを作成するを参照してください。ロケーターを使用する前に、まず検索の設定を試すことをおすすめします。メンテナンスが容易で、CSS、Playwright、XPathのクエリ構文の知識を必要としません。
サポートされるロケーター構文
[ロケーター] フィールドは、3つの構文を受け付けます。CSSとXPathは標準的なセレクター言語です。一方、Playwright構文は、text= や role= などのセレクターエンジンに加えて、一致した要素を組み合わせて絞り込むための手法を提供します。
| ロケーターのタイプ | 記述方法 | 例 |
|---|---|---|
| CSS | 接頭辞を付けずに、セレクターを直接入力します。 | button.add-to-cart |
| XPath |
xpath= 接頭辞を追加します。 |
xpath=//button[@id='submit'] |
| Playwright |
text= や role= エンジンなど、Playwright構文を使用します。 |
text=Add to cart |
CSS
CSSセレクターは、接頭辞なしで [ロケーター] フィールドで機能します。たとえば、button.add-to-cart は add-to-cart クラスを持つボタンをターゲットにします。
CSSは、多くの場合、最適な出発点となります。構文が読みやすく、一般的にXPathよりも高速で、XPathでは到達できないShadow DOM内の要素もターゲットにできます。
XPath
XPath式を使用するには、xpath= 接頭辞を追加して、mablがその文字列をCSSではなくXPathとして評価するようにします。たとえば、xpath=//button[@id='submit'] は、id でボタンをターゲットにします。
CSSセレクターとは異なり、XPath式はDOMを上位方向にたどって、子要素から親要素や祖先要素を選択できます。たとえば、表の行に安定した属性がなくても、その行のいずれかのセルに属性がある場合は、そのセルを一致させて行までたどることができます。
xpath=//td[text()='Widget A']/ancestor::tr
XPathは、他のセレクターでは表現できない場合にのみ使用してください。ほとんどのブラウザでは、入れ子になった兄弟要素や表の走査はコストが高いため、汎用的な戦略としてはCSSよりも低速です。
Playwrightロケーター
Playwright構文は、CSSとXPathに加えて2つの機能を提供します。要素を新しい方法で一致させるセレクターエンジンと、一致した要素を組み合わせて絞り込むための手法です。チェーンと序数による選択はPlaywright構文であるため、これらのいずれかを使用すると、チェーンする要素がCSSやXPathであっても、ロケーター全体がPlaywrightロケーターになります。
text エンジンと role エンジン
text= と role= はPlaywrightのエンジンです。text= は要素を表示テキストで一致させ、role= はARIAロールで一致させます。どちらも、要素に安定したクラスや id がない場合に便利です。
text=Add to cart
role=button
チェーン
>> を使用してロケーターをチェーンし、あるロケーターから次のロケーターへと検索範囲を絞り込みます。mablは各ロケーターを順番に評価し、次のロケーターを前のロケーターの結果にスコープします。
たとえば、次のロケーターは「Product 2」というテキストを含むリスト項目を検索し、その項目内の「Add to cart」ボタンを検索します。
li:has-text("Product 2") >> button:has-text("Add to cart")
Playwrightのチェーンを文字列として記述する
Playwrightのドキュメントでは、page.getByRole('listitem').filter({ hasText: 'Product 2' }) のように、コード内でチェーンされたロケーターが主に示されています。[ロケーター] フィールドは単一の文字列値を受け付けるため、同じチェーンを >> を使って次のように表現します。
role=listitem >> text=Product 2
完全な構文リファレンスについては、Playwrightのロケーターを参照してください。
序数による選択
複数の要素が同じロケーターに一致する場合は、nth を使用して、位置で特定の要素をターゲットにします。>> nth= の後にインデックスを追加します。
-
>> nth=0は最初の一致をターゲットにします。 -
>> nth=-1は最後の一致をターゲットにします。
たとえば、.list-item >> nth=0 は、list-item クラスを持つ最初の要素をターゲットにします。負のインデックスは末尾から数えるため、nth=-1 は、実行のたびに一致する要素の数が変わる場合でも、最後の一致を確実にターゲットにできる方法です。
ロケーターでの変数の使用
ロケーターにmabl変数の構文を含めることで、データ駆動型の値で要素をターゲットにできます。変数は {{@varName}} 形式で参照します。
- CSS:
div.{{@sample_var}} - XPath:
xpath=//div[@class="{{@sample_var}}"]
ステップの実行時に、mablは変数を解決し、解決された値でロケーターを評価します。