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>

タイトルテキストで検索した後、issue の数を確認できます

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