FrameLocator

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

var locator = page.Locator("#my-frame").ContentFrame.GetByText("Submit");
await locator.ClickAsync();

厳密性

フレームロケーターは厳密です。これは、特定のセレクターに複数の要素が一致する場合、フレームロケーターに対するすべての操作がエラーをスローすることを意味します。

// Throws if there are several frames in DOM:
await page.Locator(".result-frame").ContentFrame.GetByRole(AriaRole.Button).ClickAsync();

// Works because we explicitly tell locator to pick the first frame:
await page.Locator(".result-frame").First.ContentFrame.getByRole(AriaRole.Button).ClickAsync();

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'>

await page.GetByAltText("Playwright logo").ClickAsync();

引数

text string | Regex #

要素を特定するためのテキスト。
options FrameLocatorGetByAltTextOptions? (任意)
- Exact bool? (任意)#
  
  完全一致を見つけるかどうか: 大文字小文字を区別し、文字列全体を一致させます。デフォルトは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">

await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");

引数

text string | Regex #

要素を特定するためのテキスト。
options FrameLocatorGetByLabelOptions? (任意)
- Exact bool? (任意)#
  
  完全一致を見つけるかどうか: 大文字小文字を区別し、文字列全体を一致させます。デフォルトはfalseです。正規表現による特定の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator #

GetByPlaceholder

追加されたバージョン: v1.27

frameLocator.GetByPlaceholder

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

使用方法

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

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

プレースホルダーテキストで入力を特定した後、入力できます

await page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

引数

text string | Regex #

要素を特定するためのテキスト。
options FrameLocatorGetByPlaceholderOptions? (任意)
- Exact bool? (任意)#
  
  完全一致を見つけるかどうか: 大文字小文字を区別し、文字列全体を一致させます。デフォルトはfalseです。正規表現による特定の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator #

GetByRole

追加されたバージョン: v1.27

frameLocator.GetByRole

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

使用方法

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

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

各要素をその暗黙的なロールで特定できます

await Expect(Page
    .GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
    .ToBeVisibleAsync();

await page
    .GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
    .CheckAsync();

await page
    .GetByRole(AriaRole.Button, new() {
        NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
    })
    .ClickAsync();

引数

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 FrameLocatorGetByRoleOptions? (任意)
- Checked bool? (任意)#
  
  通常、aria-checkedまたはネイティブの<input type=checkbox>コントロールによって設定される属性。
  
  aria-checkedについて詳しく学ぶ。
- Disabled bool? (任意)#
  
  通常、aria-disabledまたはdisabledによって設定される属性。
  
  注意
  他のほとんどの属性とは異なり、disabledはDOM階層を通じて継承されます。aria-disabledについて詳しく学ぶ。
- Exact bool? (任意)追加されたバージョン: v1.28#
  
  Name|NameRegexが正確に一致するかどうか: 大文字小文字を区別し、文字列全体を一致させます。デフォルトはfalseです。Name|NameRegexが正規表現の場合は無視されます。完全一致の場合でも空白はトリムされます。
- Expanded bool? (任意)#
  
  通常、aria-expandedによって設定される属性。
  
  aria-expandedについて詳しく学ぶ。
- IncludeHidden bool? (任意)#
  
  非表示の要素も一致させるかどうかを制御するオプション。デフォルトでは、ARIAで定義されている非非表示要素のみがロールセレクターによって一致されます。
  
  aria-hiddenについて詳しく学ぶ。
- Level int? (任意)#
  
  heading、listitem、row、treeitemのロールに対して通常存在する数値属性で、<h1>-<h6>要素のデフォルト値があります。
  
  aria-levelについて詳しく学ぶ。
- Name|NameRegex string? | Regex? (任意)#
  
  アクセシブルネームに一致させるオプション。デフォルトでは、大文字小文字を区別せず、部分文字列を検索します。Exactを使用してこの動作を制御します。
  
  アクセシブルネームについて詳しく学ぶ。
- Pressed bool? (任意)#
  
  通常、aria-pressedによって設定される属性。
  
  aria-pressedについて詳しく学ぶ。
- Selected bool? (任意)#
  
  通常、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で特定できます

await page.GetByTestId("directions").ClickAsync();

引数

testId string | Regex #

要素を特定するための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() { Exact = true });

// Matches both <div>s
page.GetByText(new Regex("Hello"));

// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

引数

text string | Regex #

要素を特定するためのテキスト。
options FrameLocatorGetByTextOptions? (任意)
- Exact bool? (任意)#
  
  完全一致を見つけるかどうか: 大文字小文字を区別し、文字列全体を一致させます。デフォルトは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>

タイトルテキストで特定した後、問題の数をチェックできます

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

引数

text string | Regex #

要素を特定するためのテキスト。
options FrameLocatorGetByTitleOptions? (任意)
- Exact bool? (任意)#
  
  完全一致を見つけるかどうか: 大文字小文字を区別し、文字列全体を一致させます。デフォルトはfalseです。正規表現による特定の場合は無視されます。完全一致の場合でも空白はトリムされます。

戻り値

Locator #

Locator

追加されたバージョン: v1.17

frameLocator.Locator

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

ロケーターについて詳しく学ぶ.

使用方法

FrameLocator.Locator(selectorOrLocator, options);

引数

selectorOrLocator string | Locator #

DOM要素を解決する際に使用するセレクターまたはロケーター。
options FrameLocatorLocatorOptions? (任意)
- Has Locator? (任意)#
  
  この相対ロケーターに一致する要素を含む結果に絞り込みます。例えば、text=Playwrightを持つarticleは<article><div>Playwright</div></article>に一致します。
  
  内部ロケーターは、外部ロケーターに対して**相対的である必要があり**、ドキュメントのルートからではなく、外部ロケーターの一致からクエリが開始されます。例えば、<article><content><div>Playwright</div></content></article>内のdivを持つcontentを見つけることができます。ただし、article divを持つcontentを探すと失敗します。なぜなら、内部ロケーターは相対的である必要があり、contentの外部の要素を使用してはいけないからです。
  
  外部ロケーターと内部ロケーターは同じフレームに属している必要があります。内部ロケーターはFrameLocatorを含んではいけません。
- HasNot Locator? (任意)追加されたバージョン: v1.33#
  
  内部ロケーターに一致する要素を含まない要素に一致します。内部ロケーターは外部ロケーターに対してクエリされます。例えば、divを持たないarticleは<article><span>Playwright</span></article>に一致します。
  
  外部ロケーターと内部ロケーターは同じフレームに属している必要があります。内部ロケーターはFrameLocatorを含んではいけません。
- HasNotText|HasNotTextRegex string? | Regex? (任意)追加されたバージョン: v1.33#
  
  指定されたテキストを内部のどこかに、おそらく子要素または子孫要素に、含まない要素に一致します。stringが渡された場合、大文字と小文字を区別せず、部分文字列を検索します。
- HasText|HasTextRegex string? | Regex? (任意)#
  
  指定されたテキストを内部のどこかに、おそらく子要素または子孫要素に、含む要素に一致します。stringが渡された場合、大文字と小文字を区別せず、部分文字列を検索します。例えば、"Playwright"は<article><div>Playwright</div></article>に一致します。

戻り値

Locator #

Owner

追加されたバージョン: v1.43

frameLocator.Owner

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

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

逆の操作を行うには、Locator.ContentFrameを使用します。

使用方法

var frameLocator = Page.Locator("iframe[name=\"embedded\"]").ContentFrame;
// ...
var locator = frameLocator.Owner;
await Expect(locator).ToBeVisibleAsync();

戻り値

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