メインコンテンツにスキップ

FrameLocator

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

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

厳密性

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

// 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に変換する

Locatorオブジェクトがiframeを指している場合、locator.contentFrame()を使用してFrameLocatorに変換できます。

FrameLocatorをLocatorに変換する

FrameLocatorオブジェクトがある場合、frameLocator.owner()を使用して同じiframeを指すLocatorに変換できます。

メソッド​

frameLocator​

追加バージョン: v1.17 frameLocator.frameLocator

iframeを扱う際、iframe内に入り、そのiframe内の要素を選択できるフレームロケーターを作成できます。

使用法

frameLocator.frameLocator(selector);

引数

  • selector string#

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

戻り値

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です。正規表現で特定する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

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です。正規表現で特定する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

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です。正規表現で特定する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

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('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について詳しくはこちら。

戻り値

詳細

ロールセレクターはアクセシビリティ監査や適合性テストに取って代わるものではなく、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();

引数

戻り値

詳細

デフォルトでは、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です。正規表現で特定する場合は無視されます。完全一致でも空白はトリムされることに注意してください。

戻り値

詳細

テキストによるマッチングは、完全一致の場合でも常に空白を正規化します。例えば、複数のスペースを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​

追加バージョン: v1.17 frameLocator.locator

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

ロケーターについて詳しくはこちら.

使用法

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

引数

  • selectorOrLocator string | Locator#

    DOM要素を解決する際に使用するセレクターまたはロケーター。

  • options Object (オプション)

    • 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 string | RegExp (オプション)追加バージョン: v1.33#

      指定されたテキストを内部（子要素または子孫要素内である可能性あり）に含んでいない要素にマッチします。文字列が渡された場合、大文字と小文字を区別せず、部分文字列を検索します。

    • hasText string | RegExp (オプション)#

      指定されたテキストを内部（子要素または子孫要素内である可能性あり）に含む要素にマッチします。文字列が渡された場合、大文字と小文字を区別せず、部分文字列を検索します。例えば、「Playwright」は<article><div>Playwright</div></article>に一致します。

戻り値

owner​

追加バージョン: v1.43 frameLocator.owner

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

どこかでFrameLocatorオブジェクトを取得し、後でiframe要素と対話したい場合に便利です。

逆操作については、locator.contentFrame()を使用してください。

使用法

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

戻り値

非推奨​

first​

追加バージョン: v1.17 frameLocator.first
非推奨

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

最初に一致するフレームへのロケーターを返します。

使用法

frameLocator.first();

戻り値

last​

追加バージョン: v1.17 frameLocator.last
非推奨

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

最後に一致するフレームへのロケーターを返します。

使用法

frameLocator.last();

戻り値

nth​

追加バージョン: v1.17 frameLocator.nth
非推奨

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

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

使用法

frameLocator.nth(index);

引数

戻り値