FrameLocator

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

const locator = page.locator('#my-frame').contentFrame().getByText('Submit');
await locator.click();

厳密性

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

// Throws if there are several frames in DOM:
await page.locator('.result-frame').contentFrame().getByRole('button').click();

// Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').contentFrame().first().getByRole('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.frameLocator(selector);

引数

selector string #

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

戻り値

FrameLocator #

getByAltText

バージョン v1.27 で追加

frameLocator.getByAltText

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

使用法

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

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

引数

text string | RegExp #

要素を特定するためのテキスト。
options Object (オプション)
- exact 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">

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

引数

text string | RegExp #

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

戻り値

Locator #

getByPlaceholder

バージョン v1.27 で追加

frameLocator.getByPlaceholder

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

使用法

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

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

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

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

引数

text string | RegExp #

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

戻り値

Locator #

getByRole

バージョン v1.27 で追加

frameLocator.getByRole

ARIA role、ARIA 属性、およびアクセシブル名によって要素を特定できます。

使用法

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

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

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

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).click();

引数

role "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 Object (オプション)
- checked boolean (オプション)#
  
  通常 aria-checked またはネイティブ <input type=checkbox> コントロールによって設定される属性。
  
  aria-checked の詳細はこちら。
- disabled boolean (オプション)#
  
  通常 aria-disabled または disabled によって設定される属性。
  
  注記
  他のほとんどの属性とは異なり、disabled は DOM 階層を介して継承されます。aria-disabled の詳細はこちら。
- exact boolean (オプション)バージョン v1.28 で追加#
  
  name が完全一致するかどうか: 大文字と小文字を区別し、文字列全体を比較します。デフォルトは false です。name が正規表現の場合は無視されます。完全一致でも空白はトリムされることに注意してください。
- expanded boolean (オプション)#
  
  通常 aria-expanded によって設定される属性。
  
  aria-expanded の詳細はこちら。
- includeHidden boolean (オプション)#
  
  非表示要素を一致させるかどうかを制御するオプション。デフォルトでは、ARIA で定義されている非表示でない要素のみがロールセレクターによって一致されます。
  
  aria-hidden の詳細はこちら。
- level number (オプション)#
  
  通常、ロール heading、listitem、row、treeitem に存在する数値属性で、<h1>-<h6> 要素のデフォルト値があります。
  
  aria-level の詳細はこちら。
- name string | RegExp (オプション)#
  
  アクセシブル名を一致させるためのオプション。デフォルトでは、一致は大文字と小文字を区別せず、部分文字列を検索します。この動作を制御するには exact を使用します。
  
  アクセシブル名の詳細はこちら。
- pressed boolean (オプション)#
  
  通常 aria-pressed によって設定される属性。
  
  aria-pressed の詳細はこちら。
- selected 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 で特定できます

await page.getByTestId('directions').click();

引数

testId string | RegExp #

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

戻り値

Locator #

詳細

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

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

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', { exact: true });

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

// Matches second <div>
page.getByText(/^hello$/i);

引数

text string | RegExp #

要素を特定するためのテキスト。
options Object (オプション)
- exact 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>

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

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

引数

text string | RegExp #

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

戻り値

Locator #

locator

バージョン v1.17 で追加

frameLocator.locator

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

locator の詳細はこちら.

使用法

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

引数

selectorOrLocator string | Locator #

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

戻り値

Locator #

owner

バージョン v1.43 で追加

frameLocator.owner

この FrameLocator と同じ iframe を指す Locator オブジェクトを返します。

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

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

使用法

const frameLocator = page.locator('iframe[name="embedded"]').contentFrame();
// ...
const locator = frameLocator.owner();
await expect(locator).toBeVisible();

戻り値

Locator #

非推奨

first

バージョン v1.17 で追加

frameLocator.first

非推奨

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

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

使用法

frameLocator.first();

戻り値

FrameLocator #

last

バージョン v1.17 で追加

frameLocator.last

非推奨

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

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

使用法

frameLocator.last();

戻り値

FrameLocator #

nth

バージョン v1.17 で追加

frameLocator.nth

非推奨

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

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

使用法

frameLocator.nth(index);

引数

index number #

戻り値

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