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.17iframeを操作する場合、iframeに入り、そのiframe内の要素を選択できるフレームロケーターを作成できます。
使用法
FrameLocator.FrameLocator(selector);
引数
戻り値
GetByAltText
追加バージョン: v1.27要素をそのaltテキストで特定できます。
使用法
例えば、このメソッドはaltテキスト「Playwright logo」で画像を見つけます。
<img alt='Playwright logo'>
await page.GetByAltText("Playwright logo").ClickAsync();
引数
-
要素を特定するためのテキスト。
-
optionsFrameLocatorGetByAltTextOptions?(オプション)
戻り値
GetByLabel
追加バージョン: v1.27関連する<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");
引数
-
要素を特定するためのテキスト。
-
optionsFrameLocatorGetByLabelOptions?(オプション)
戻り値
GetByPlaceholder
追加バージョン: v1.27プレースホルダーテキストによって入力要素を特定できます。
使用法
例えば、以下のDOM構造を考えてみましょう。
<input type="email" placeholder="name@example.com" />
プレースホルダーテキストで入力を見つけてから、入力できます。
await page
.GetByPlaceholder("name@example.com")
.FillAsync("playwright@microsoft.com");
引数
-
要素を特定するためのテキスト。
-
optionsFrameLocatorGetByPlaceholderOptions?(オプション)
戻り値
GetByRole
追加バージョン: v1.27要素をその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();
引数
-
roleenum 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ロール。
-
optionsFrameLocatorGetByRoleOptions?(オプション)-
通常、
aria-checkedまたはネイティブの<input type=checkbox>コントロールによって設定される属性。aria-checkedの詳細。 -
通常、
aria-disabledまたはdisabledによって設定される属性。注他のほとんどの属性とは異なり、
disabledはDOM階層を介して継承されます。aria-disabledの詳細。 -
Exactbool? (任意)追加バージョン: v1.28#Name|NameRegexが完全に一致するかどうか（大文字小文字を区別し、文字列全体）。デフォルトはfalseです。Name|NameRegexが正規表現の場合は無視されます。完全一致でも空白文字はトリムされることに注意してください。
-
通常、
aria-expandedによって設定される属性。aria-expandedの詳細。 -
非表示要素が一致するかどうかを制御するオプション。デフォルトでは、ARIAで定義されているように、非表示でない要素のみがロールセレクターによって一致します。
aria-hiddenの詳細。 -
通常、
heading、listitem、row、treeitemのロールに存在する数値属性で、<h1>-<h6>要素のデフォルト値があります。aria-levelの詳細。 -
Name|NameRegexstring? | Regex? (オプション)#アクセシブルネームに一致するオプション。デフォルトでは、大文字小文字を区別せず、部分文字列を検索します。この動作を制御するにはExactを使用します。
アクセシブルネームの詳細。
-
通常、
aria-pressedによって設定される属性。aria-pressedの詳細。 -
通常、
aria-selectedによって設定される属性。aria-selectedの詳細。
-
戻り値
詳細
ロールセレクターは、アクセシビリティ監査や適合性テストを**置き換えるものではなく**、ARIAガイドラインに関する早期のフィードバックを提供します。
多くのHTML要素には、ロールセレクターによって認識される暗黙的に定義されたロールがあります。サポートされているすべてのロールはこちらで確認できます。ARIAガイドラインは、roleおよび/またはaria-*属性をデフォルト値に設定して暗黙的なロールと属性を重複させることを**推奨しません**。
GetByTestId
追加バージョン: v1.27テストIDによって要素を特定します。
使用法
以下のDOM構造を考えてみましょう。
<button data-testid="directions">Itinéraire</button>
テストIDによって要素を特定できます。
await page.GetByTestId("directions").ClickAsync();
引数
戻り値
詳細
デフォルトでは、data-testid 属性がテスト ID として使用されます。必要に応じて、Selectors.SetTestIdAttribute() を使用して別のテスト ID 属性を設定してください。
GetByText
追加バージョン: v1.27指定されたテキストを含む要素を特定できます。
アクセシブルロールなどの別の基準で一致させ、その後テキストコンテンツでフィルタリングできる 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));
引数
-
要素を特定するためのテキスト。
-
optionsFrameLocatorGetByTextOptions?(オプション)
戻り値
詳細
テキストによる一致は、厳密な一致であっても常に空白を正規化します。例えば、複数のスペースを1つにまとめ、改行をスペースに変換し、先頭と末尾の空白を無視します。
buttonおよびsubmit型の入力要素は、テキストコンテンツの代わりにそのvalueによって一致します。例えば、テキスト"Log in"で特定すると、<input type=button value="Log in">が一致します。
GetByTitle
追加バージョン: v1.27要素をそのタイトル属性で特定できます。
使用法
以下のDOM構造を考えてみましょう。
<span title='Issues count'>25 issues</span>
タイトルテキストで問題数を特定した後、確認できます。
await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");
引数
-
要素を特定するためのテキスト。
-
optionsFrameLocatorGetByTitleOptions?(オプション)
戻り値
Locator
追加バージョン: v1.17このメソッドは、ロケーターのサブツリー内で指定されたセレクターに一致する要素を検索します。Locator.Filter()メソッドと同様に、フィルターオプションも受け入れます。
使用法
FrameLocator.Locator(selectorOrLocator, options);
引数
-
selectorOrLocatorstring | Locator#DOM要素を解決するときに使用するセレクターまたはロケーター。
-
optionsFrameLocatorLocatorOptions?(オプション)-
この相対ロケーターに一致する要素を含む結果にメソッドの結果を絞り込みます。例えば、
text=Playwrightを持つarticleは<article><div>Playwright</div></article>に一致します。内部ロケーターは**外部ロケーターに対して相対的**でなければならず、ドキュメントルートではなく外部ロケーターの一致からクエリが開始されます。例えば、
<article><content><div>Playwright</div></content></article>でdivを持つcontentを見つけることができます。しかし、article divを持つcontentを探すと、内部ロケーターは相対的でなければならず、contentの外部の要素を使用すべきではないため、失敗します。外部ロケーターと内部ロケーターは同じフレームに属している必要があります。内部ロケーターには FrameLocator を含めることはできません。
-
HasNotLocator? (任意)追加バージョン: v1.33#内部ロケーターに一致する要素を含まない要素に一致します。内部ロケーターは外部ロケーターに対してクエリされます。例えば、
divを持たないarticleは<article><span>Playwright</span></article>に一致します。外部ロケーターと内部ロケーターは同じフレームに属している必要があります。内部ロケーターには FrameLocator を含めることはできません。
-
HasNotText|HasNotTextRegexstring? | Regex? (任意)追加バージョン: v1.33#指定されたテキストを、子要素または子孫要素内にどこかに含まない要素に一致します。string が渡された場合、大文字小文字を区別せずに部分文字列を検索します。
-
HasText|HasTextRegexstring? | Regex? (オプション)#指定されたテキストを、子要素または子孫要素内にどこかに含む要素に一致します。string が渡された場合、大文字小文字を区別せずに部分文字列を検索します。例えば、
"Playwright"は
-
戻り値
Owner
追加バージョン: v1.43このフレームロケーターと同じiframeを指すLocatorオブジェクトを返します。
どこかで取得したFrameLocatorオブジェクトがあり、後でiframe要素とやり取りしたい場合に便利です。
逆の操作を行うには、Locator.ContentFrameを使用します。
使用法
var frameLocator = Page.Locator("iframe[name=\"embedded\"]").ContentFrame;
// ...
var locator = frameLocator.Owner;
await Expect(locator).ToBeVisibleAsync();
戻り値
非推奨
First
追加バージョン: v1.17代わりに、Locator.Firstの後にLocator.ContentFrameを使用してください。
最初の一致するフレームへのロケーターを返します。
使用法
FrameLocator.First
戻り値
Last
追加バージョン: v1.17代わりに、Locator.Lastの後にLocator.ContentFrameを使用してください。
最後の一致するフレームへのロケーターを返します。
使用法
FrameLocator.Last
戻り値
Nth
追加バージョン: v1.17代わりに、Locator.Nth()の後にLocator.ContentFrameを使用してください。
n番目の一致するフレームへのロケーターを返します。0ベースで、nth(0)は最初のフレームを選択します。
使用法
FrameLocator.Nth(index);
引数
戻り値