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によって設定される属性。
  
  注
  他のほとんどの属性とは異なり、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

要素をそのタイトル属性で特定できます。

使用方法

以下の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#
  
  子要素または子孫要素など、内部のどこかに指定されたテキストを含まない要素に一致します。文字列が渡された場合、大文字小文字を区別せずに部分文字列を検索します。
- setHasText String | Pattern (オプション)#
  
  子要素または子孫要素など、内部のどこかに指定されたテキストを含む要素に一致します。文字列が渡された場合、大文字小文字を区別せずに部分文字列を検索します。例えば、"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