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

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()

引数

  • test_id str | Pattern#

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

戻り値

詳細

デフォルトでは、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

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 Locator (オプション)追加: 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 番目の一致フレームへのロケーターを返します。ゼロベースで、nth(0) は最初のフレームを選択します。

使用法

frame_locator.nth(index)

引数

戻り値