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

FrameLocator

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

locator = page.locator("my-frame").content_frame.get_by_text("Submit")
locator.click()

厳格性

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

# Throws if there are several frames in DOM:
page.locator('.result-frame').content_frame.get_by_role('button').click()

# Works because we explicitly tell locator to pick the first frame:
page.locator('.result-frame').first.content_frame.get_by_role('button').click()

LocatorをFrameLocatorに変換する

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

FrameLocatorをLocatorに変換する

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

メソッド​

frame_locator​

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

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

使用法

frame_locator.frame_locator(selector)

引数

  • selector str#

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

戻り値

get_by_alt_text​

追加バージョン: v1.27 frameLocator.get_by_alt_text

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

使用法

例えば、このメソッドはaltテキスト「Playwright logo」で画像を見つけます。

<img alt='Playwright logo'>
page.get_by_alt_text("Playwright logo").click()

引数

  • text str | Pattern#

    要素を特定するためのテキスト。

  • exact bool (オプション)#

    完全一致（大文字小文字を区別し、文字列全体）を見つけるかどうか。デフォルトはfalse。正規表現で特定する場合は無視されます。正確な一致でも空白はトリムされることに注意してください。

戻り値

get_by_label​

追加バージョン: v1.27 frameLocator.get_by_label

関連する<label>またはaria-labelledby要素のテキスト、またはaria-label属性によって入力要素を特定できます。

使用法

例えば、このメソッドは以下のDOMでラベル「Username」と「Password」を持つ入力を見つけます。

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

引数

  • text str | Pattern#

    要素を特定するためのテキスト。

  • exact bool (オプション)#

    完全一致（大文字小文字を区別し、文字列全体）を見つけるかどうか。デフォルトはfalse。正規表現で特定する場合は無視されます。正確な一致でも空白はトリムされることに注意してください。

戻り値

get_by_placeholder​

追加バージョン: v1.27 frameLocator.get_by_placeholder

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

使用法

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

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

プレースホルダーテキストで入力を見つけてから、入力できます。

page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

引数

  • text str | Pattern#

    要素を特定するためのテキスト。

  • exact bool (オプション)#

    完全一致（大文字小文字を区別し、文字列全体）を見つけるかどうか。デフォルトはfalse。正規表現で特定する場合は無視されます。正確な一致でも空白はトリムされることに注意してください。

戻り値

get_by_role​

追加バージョン: v1.27 frameLocator.get_by_role

要素をそのARIAロール、ARIA属性、およびアクセシブルネームで特定できます。

使用法

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

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

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

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).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ロール。

  • checked bool (オプション)#

    通常、aria-checkedまたはネイティブの<input type=checkbox>コントロールによって設定される属性。

    aria-checkedの詳細。

  • disabled bool (オプション)#

    通常、aria-disabledまたはdisabledによって設定される属性。

    注

    他のほとんどの属性とは異なり、disabledはDOM階層を介して継承されます。aria-disabledの詳細。

  • exact bool (オプション)追加バージョン: v1.28#

    nameが完全に一致するかどうか: 大文字と小文字を区別し、文字列全体を対象とします。デフォルトはfalseです。nameが正規表現の場合は無視されます。完全一致でも空白はトリムされることに注意してください。

  • expanded bool (オプション)#

    通常、aria-expandedによって設定される属性。

    aria-expandedの詳細。

  • include_hidden bool (オプション)#

    非表示要素が一致するかどうかを制御するオプション。デフォルトでは、ARIAで定義されているように、非表示でない要素のみがロールセレクターによって一致します。

    aria-hiddenの詳細。

  • level int (オプション)#

    通常、heading、listitem、row、treeitemのロールに存在する数値属性で、<h1>-<h6>要素のデフォルト値があります。

    aria-levelの詳細。

  • name str | Pattern (オプション)#

    アクセシブルネームと一致させるオプションです。デフォルトでは、大文字と小文字を区別せず、部分文字列を検索します。この動作を制御するにはexactを使用します。

    アクセシブルネームの詳細。

  • pressed bool (オプション)#

    通常、aria-pressedによって設定される属性。

    aria-pressedの詳細。

  • selected bool (オプション)#

    通常、aria-selectedによって設定される属性。

    aria-selectedの詳細。

戻り値

詳細

ロールセレクターは、アクセシビリティ監査や適合性テストを**置き換えるものではなく**、ARIAガイドラインに関する早期のフィードバックを提供します。

多くのHTML要素には、ロールセレクターによって認識される暗黙的に定義されたロールがあります。サポートされているすべてのロールはこちらで確認できます。ARIAガイドラインは、roleおよび/またはaria-*属性をデフォルト値に設定して暗黙的なロールと属性を重複させることを**推奨しません**。

get_by_test_id​

追加バージョン: v1.27 frameLocator.get_by_test_id

テストIDによって要素を特定します。

使用法

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

<button data-testid="directions">Itinéraire</button>

テストIDによって要素を特定できます。

page.get_by_test_id("directions").click()

引数

戻り値

詳細

デフォルトでは、data-testid 属性がテスト ID として使用されます。必要に応じて異なるテスト ID 属性を設定するには、selectors.set_test_id_attribute() を使用します。

get_by_text​

追加バージョン: v1.27 frameLocator.get_by_text

指定されたテキストを含む要素を特定できます。

アクセス可能なロールなどの別の基準で一致させ、その後テキストコンテンツでフィルタリングできる locator.filter() メソッドも参照してください。

使用法

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

<div>Hello <span>world</span></div>
<div>Hello</div>

テキストの部分文字列、完全な文字列、または正規表現で特定できます。

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

引数

  • text str | Pattern#

    要素を特定するためのテキスト。

  • exact bool (オプション)#

    完全一致（大文字小文字を区別し、文字列全体）を見つけるかどうか。デフォルトはfalse。正規表現で特定する場合は無視されます。正確な一致でも空白はトリムされることに注意してください。

戻り値

詳細

テキストによる一致は、厳密な一致であっても常に空白を正規化します。例えば、複数のスペースを1つにまとめ、改行をスペースに変換し、先頭と末尾の空白を無視します。

buttonおよびsubmit型の入力要素は、テキストコンテンツの代わりにそのvalueによって一致します。例えば、テキスト"Log in"で特定すると、<input type=button value="Log in">が一致します。

get_by_title​

追加バージョン: v1.27 frameLocator.get_by_title

要素をそのタイトル属性で特定できます。

使用法

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

<span title='Issues count'>25 issues</span>

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

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

引数

  • text str | Pattern#

    要素を特定するためのテキスト。

  • exact bool (オプション)#

    完全一致（大文字小文字を区別し、文字列全体）を見つけるかどうか。デフォルトはfalse。正規表現で特定する場合は無視されます。正確な一致でも空白はトリムされることに注意してください。

戻り値

locator​

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

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

ロケーターの詳細.

使用法

frame_locator.locator(selector_or_locator)
frame_locator.locator(selector_or_locator, **kwargs)

引数

  • selector_or_locator str | Locator#

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

  • has Locator (オプション)#

    この相対ロケーターに一致する要素を含む結果にメソッドの結果を絞り込みます。例えば、text=Playwrightを持つarticleは<article><div>Playwright</div></article>に一致します。

    内部ロケーターは**外部ロケーターに対して相対的**でなければならず、ドキュメントルートではなく外部ロケーターの一致からクエリが開始されます。例えば、<article><content><div>Playwright</div></content></article>でdivを持つcontentを見つけることができます。しかし、article divを持つcontentを探すと、内部ロケーターは相対的でなければならず、contentの外部の要素を使用すべきではないため、失敗します。

    外側のロケーターと内側のロケーターは同じフレームに属している必要があります。内側のロケーターには FrameLocator を含めることはできません。

  • has_not ロケーター (オプション)追加バージョン: v1.33#

    内部ロケーターに一致する要素を含まない要素に一致します。内部ロケーターは外部ロケーターに対してクエリされます。例えば、divを持たないarticleは<article><span>Playwright</span></article>に一致します。

    外側のロケーターと内側のロケーターは同じフレームに属している必要があります。内側のロケーターには FrameLocator を含めることはできません。

  • has_not_text str | Pattern (オプション)追加バージョン: v1.33#

    指定されたテキストを、おそらく子または子孫要素内にどこかに含まない要素と一致します。 [string] が渡された場合、大文字と小文字を区別せず、部分文字列を検索します。

  • has_text str | Pattern (オプション)#

    指定されたテキストを、おそらく子または子孫要素内にどこかに含む要素と一致します。 [string] が渡された場合、大文字と小文字を区別せず、部分文字列を検索します。たとえば、"Playwright" は <article><div>Playwright</div></article> と一致します。

戻り値

プロパティ​

owner​

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

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

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

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

使用法

frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
expect(locator).to_be_visible()

戻り値

非推奨​

first​

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

locator.firstの後にlocator.content_frameを使用してください。

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

使用法

frame_locator.first

戻り値

last​

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

locator.lastの後にlocator.content_frameを使用してください。

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

使用法

frame_locator.last

戻り値

nth​

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

locator.nth()の後にlocator.content_frameを使用してください。

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

使用法

frame_locator.nth(index)

引数

戻り値