FrameLocator

FrameLocator は、ページ上の iframe へのビューを表します。これは、iframe を取得し、その iframe 内の要素を特定するのに十分なロジックをキャプチャします。FrameLocator は、Locator.contentFrame()、Page.frameLocator()、または Locator.frameLocator() メソッドのいずれかで作成できます。

Locator locator = page.locator("#my-frame").contentFrame().getByText("Submit");
locator.click();

厳密性

フレームロケーターは厳密です。これは、フレームロケーターに対するすべての操作は、与えられたセレクターに複数の一致する要素がある場合に例外をスローすることを意味します。

// Throws if there are several frames in DOM:
page.locator(".result-frame").contentFrame().getByRole(AriaRole.BUTTON).click();

// Works because we explicitly tell locator to pick the first frame:
page.locator(".result-frame").first().contentFrame().getByRole(AriaRole.BUTTON).click();

Locator から FrameLocator への変換

iframe を指す Locator オブジェクトがある場合、Locator.contentFrame() を使用して FrameLocator に変換できます。

FrameLocator から Locator への変換

FrameLocator オブジェクトがある場合、FrameLocator.owner() を使用して、同じ iframe を指す Locator に変換できます。

メソッド

frameLocator

バージョン v1.17 で追加

frameLocator.frameLocator

iframe を操作する場合、iframe に入り、その iframe 内の要素を選択できるようにするフレームロケーターを作成できます。

使用例

FrameLocator.frameLocator(selector);

引数

selector String #

DOM 要素を解決するときに使用するセレクター。

戻り値

FrameLocator #

getByAltText

バージョン v1.27 で追加

frameLocator.getByAltText

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

使用例

たとえば、このメソッドは alt テキスト "Playwright logo" で画像を検索します。

<img alt='Playwright logo'>

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

引数

text String | Pattern #

要素を特定するためのテキスト。
options FrameLocator.GetByAltTextOptions (オプション)
- setExact boolean (オプション)#
  
  完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体。デフォルトは false です。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

Locator #

getByLabel

バージョン v1.27 で追加

frameLocator.getByLabel

関連付けられた <label> または aria-labelledby 要素のテキスト、または aria-label 属性によって入力要素を特定できます。

使用例

たとえば、このメソッドは次の DOM でラベル "Username" および "Password" で入力を検索します。

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

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

引数

text String | Pattern #

要素を特定するためのテキスト。
options FrameLocator.GetByLabelOptions (オプション)
- setExact boolean (オプション)#
  
  完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体。デフォルトは false です。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

Locator #

getByPlaceholder

バージョン v1.27 で追加

frameLocator.getByPlaceholder

プレースホルダーテキストで入力要素を特定できます。

使用例

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

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

プレースホルダーテキストで特定した後、入力を埋めることができます。

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

引数

text String | Pattern #

要素を特定するためのテキスト。
options FrameLocator.GetByPlaceholderOptions (オプション)
- setExact boolean (オプション)#
  
  完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体。デフォルトは false です。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

Locator #

getByRole

バージョン v1.27 で追加

frameLocator.getByRole

ARIA ロール、ARIA 属性、およびアクセシブルネームで要素を特定できます。

使用例

次の DOM 構造を考えてみましょう。

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

引数

role enum AriaRole { ALERT, ALERTDIALOG, APPLICATION, ARTICLE, BANNER, BLOCKQUOTE, BUTTON, CAPTION, CELL, CHECKBOX, CODE, COLUMNHEADER, COMBOBOX, COMPLEMENTARY, CONTENTINFO, DEFINITION, DELETION, DIALOG, DIRECTORY, DOCUMENT, EMPHASIS, FEED, FIGURE, FORM, GENERIC, GRID, GRIDCELL, GROUP, HEADING, IMG, INSERTION, LINK, LIST, LISTBOX, LISTITEM, LOG, MAIN, MARQUEE, MATH, METER, MENU, MENUBAR, MENUITEM, MENUITEMCHECKBOX, MENUITEMRADIO, NAVIGATION, NONE, NOTE, OPTION, PARAGRAPH, PRESENTATION, PROGRESSBAR, RADIO, RADIOGROUP, REGION, ROW, ROWGROUP, ROWHEADER, SCROLLBAR, SEARCH, SEARCHBOX, SEPARATOR, SLIDER, SPINBUTTON, STATUS, STRONG, SUBSCRIPT, SUPERSCRIPT, SWITCH, TAB, TABLE, TABLIST, TABPANEL, TERM, TEXTBOX, TIME, TIMER, TOOLBAR, TOOLTIP, TREE, TREEGRID, TREEITEM }#

必須の aria ロール。
options FrameLocator.GetByRoleOptions (オプション)
- setChecked boolean (オプション)#
  
  通常、aria-checked またはネイティブの <input type=checkbox> コントロールによって設定される属性。
  
  aria-checked について詳しくはこちらをご覧ください。
- setDisabled boolean (オプション)#
  
  通常、aria-disabled または disabled によって設定される属性。
  
  note
  他のほとんどの属性とは異なり、disabled は DOM 階層を介して継承されます。aria-disabled について詳しくはこちらをご覧ください。
- setExact boolean (オプション)バージョン v1.28 で追加#
  
  setName が完全に一致するかどうか：大文字と小文字を区別し、文字列全体。デフォルトは false です。setName が正規表現の場合は無視されます。完全一致でも空白はトリムされることに注意してください。
- setExpanded boolean (オプション)#
  
  通常、aria-expanded によって設定される属性。
  
  aria-expanded について詳しくはこちらをご覧ください。
- setIncludeHidden boolean (オプション)#
  
  非表示要素を一致させるかどうかを制御するオプション。デフォルトでは、ARIA によって定義されている、非表示でない要素のみがロールセレクターによって一致されます。
  
  aria-hidden について詳しくはこちらをご覧ください。
- setLevel int (オプション)#
  
  通常、ロール heading、listitem、row、treeitem に存在する数値属性。<h1>-<h6> 要素のデフォルト値があります。
  
  aria-level について詳しくはこちらをご覧ください。
- setName String | Pattern (オプション)#
  
  アクセシブルネームを一致させるためのオプション。デフォルトでは、一致は大文字と小文字を区別せず、部分文字列を検索します。setExact を使用して、この動作を制御します。
  
  アクセシブルネームについて詳しくはこちらをご覧ください。
- setPressed boolean (オプション)#
  
  通常、aria-pressed によって設定される属性。
  
  aria-pressed について詳しくはこちらをご覧ください。
- setSelected boolean (オプション)#
  
  通常、aria-selected によって設定される属性。
  
  aria-selected について詳しくはこちらをご覧ください。

戻り値

Locator #

詳細

ロールセレクターは、アクセシビリティ監査および適合性テストを置き換えるものではありませんが、ARIA ガイドラインに関する早期フィードバックを提供します。

多くの html 要素には、ロールセレクターによって認識される暗黙的に定義されたロールがあります。サポートされているすべてのロールはこちらにあります。ARIA ガイドラインは、デフォルト値に role および/または aria-* 属性を設定して、暗黙的なロールと属性を複製することを推奨していません。

getByTestId

バージョン v1.27 で追加

frameLocator.getByTestId

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

使用例

次の DOM 構造を考えてみましょう。

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

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

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

引数

testId String | Pattern #

要素を特定するための ID。

戻り値

Locator #

詳細

デフォルトでは、data-testid 属性がテスト ID として使用されます。必要に応じて別のテスト ID 属性を設定するには、Selectors.setTestIdAttribute() を使用します。

getByText

バージョン v1.27 で追加

frameLocator.getByText

指定されたテキストを含む要素を特定できます。

アクセシブルロールなどの別の基準で一致させ、テキストコンテンツでフィルター処理できる Locator.filter() も参照してください。

使用例

次の DOM 構造を考えてみましょう。

<div>Hello <span>world</span></div>
<div>Hello</div>

テキスト部分文字列、完全一致文字列、または正規表現で特定できます。

// Matches <span>
page.getByText("world");

// Matches first <div>
page.getByText("Hello world");

// Matches second <div>
page.getByText("Hello", new Page.GetByTextOptions().setExact(true));

// Matches both <div>s
page.getByText(Pattern.compile("Hello"));

// Matches second <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));

引数

text String | Pattern #

要素を特定するためのテキスト。
options FrameLocator.GetByTextOptions (オプション)
- setExact boolean (オプション)#
  
  完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体。デフォルトは false です。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

Locator #

詳細

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

タイプ button および submit の入力要素は、テキストコンテンツの代わりに value で一致します。たとえば、テキスト "Log in" で検索すると、<input type=button value="Log in"> が一致します。

getByTitle

バージョン v1.27 で追加

frameLocator.getByTitle

title 属性で要素を特定できます。

使用例

次の DOM 構造を考えてみましょう。

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

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

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

引数

text String | Pattern #

要素を特定するためのテキスト。
options FrameLocator.GetByTitleOptions (オプション)
- setExact boolean (オプション)#
  
  完全一致を検索するかどうか：大文字と小文字を区別し、文字列全体。デフォルトは false です。正規表現で検索する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

Locator #

locator

バージョン v1.17 で追加

frameLocator.locator

このメソッドは、ロケーターのサブツリー内で指定されたセレクターに一致する要素を検索します。また、Locator.filter() メソッドと同様に、フィルターオプションも受け入れます。

ロケーターの詳細はこちら.

使用例

FrameLocator.locator(selectorOrLocator);
FrameLocator.locator(selectorOrLocator, options);

引数

selectorOrLocator String | Locator #

DOM 要素を解決するときに使用するセレクターまたはロケーター。
options FrameLocator.LocatorOptions (オプション)
- setHas Locator (オプション)#
  
  この相対ロケーターに一致する要素を含む結果にメソッドの結果を絞り込みます。たとえば、text=Playwright を持つ article は、<article><div>Playwright</div></article> に一致します。
  
  内部ロケーターは、外部ロケーターに対して相対的でなければならず、ドキュメントルートではなく、外部ロケーターの一致から始まるクエリが実行されます。たとえば、<article><content><div>Playwright</div></content></article> 内に div を持つ content を見つけることができます。ただし、article div を持つ content を検索すると失敗します。これは、内部ロケーターが相対的でなければならず、content の外部の要素を使用すべきではないためです。
  
  外部ロケーターと内部ロケーターは、同じフレームに属している必要があることに注意してください。内部ロケーターに FrameLocator を含めることはできません。
- setHasNot Locator (オプション)バージョン v1.33 で追加#
  
  内部ロケーターに一致する要素を含まない要素に一致します。内部ロケーターは外部ロケーターに対してクエリされます。たとえば、div を持たない article は、<article><span>Playwright</span></article> に一致します。
  
  外部ロケーターと内部ロケーターは、同じフレームに属している必要があることに注意してください。内部ロケーターに FrameLocator を含めることはできません。
- setHasNotText String | Pattern (オプション)バージョン v1.33 で追加#
  
  子要素または子孫要素のどこかに指定されたテキストを含まない要素に一致します。string が渡されると、マッチングは大文字と小文字を区別せず、部分文字列を検索します。
- setHasText String | Pattern (オプション)#
  
  子要素または子孫要素のどこかに指定されたテキストを含む要素に一致します。string が渡されると、マッチングは大文字と小文字を区別せず、部分文字列を検索します。たとえば、"Playwright" は <article><div>Playwright</div></article> に一致します。

戻り値

Locator #

owner

バージョン v1.43 で追加

frameLocator.owner

このフレームロケーターと同じ iframe を指す Locator オブジェクトを返します。

どこかで取得した FrameLocator オブジェクトがあり、後で iframe 要素を操作したい場合に便利です。

逆の操作には、Locator.contentFrame() を使用します。

使用例

FrameLocator frameLocator = page.locator("iframe[name=\"embedded\"]").contentFrame();
// ...
Locator locator = frameLocator.owner();
assertThat(locator).isVisible();

戻り値

Locator #

非推奨

first

バージョン v1.17 で追加

frameLocator.first

非推奨

代わりに Locator.first() の後に Locator.contentFrame() を続けて使用してください。

最初の一致するフレームへのロケーターを返します。

使用例

FrameLocator.first();

戻り値

FrameLocator #

last

バージョン v1.17 で追加

frameLocator.last

非推奨

代わりに Locator.last() の後に Locator.contentFrame() を続けて使用してください。

最後の一致するフレームへのロケーターを返します。

使用例

FrameLocator.last();

戻り値

FrameLocator #

nth

バージョン v1.17 で追加

frameLocator.nth

非推奨

代わりに Locator.nth() の後に Locator.contentFrame() を続けて使用してください。

n 番目の一致するフレームへのロケーターを返します。ゼロベースであり、nth(0) は最初のフレームを選択します。

使用例

FrameLocator.nth(index);

引数

index int #

戻り値

FrameLocator #

メソッド​

frameLocator​

getByAltText​

getByLabel​

getByPlaceholder​

getByRole​

getByTestId​

getByText​

getByTitle​

locator​

owner​

非推奨​

first​

last​

nth​

メソッド

frameLocator

getByAltText

getByLabel

getByPlaceholder

getByRole

getByTestId

getByText

getByTitle

locator

owner

非推奨

first

last

nth