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

非同期

locator = page.locator("#my-frame").content_frame.get_by_text("Submit")
await 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()

非同期

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

# Works because we explicitly tell locator to pick the first frame:
await 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 要素を解決する際に使用するセレクターです。

戻り値

• FrameLocator#

---

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

非同期

await page.get_by_alt_text("Playwright logo").click()

引数

• text str | Pattern#

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

• exact bool (オプション)#

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

戻り値

• Locator#

---

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

非同期

await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")

引数

• text str | Pattern#

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

• exact bool (オプション)#

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

戻り値

• Locator#

---

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

非同期

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

引数

• text str | Pattern#

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

• exact bool (オプション)#

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

戻り値

• Locator#

---

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

非同期

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

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

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

戻り値

• Locator#

詳細

ロールセレクターはアクセシビリティ監査や適合性テストを置き換えるものではなく、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()

非同期

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

引数

• test_id str | Pattern#

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

戻り値

• Locator#

詳細

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

非同期

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

戻り値

• Locator#

詳細

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

非同期

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

引数

• text str | Pattern#

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

• exact bool (オプション)#

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

戻り値

• Locator#

---

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#

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

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

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

戻り値

• Locator#

---

プロパティ

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

非同期

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

戻り値

• Locator#

---

非推奨

first

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

非推奨

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

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

使用方法

frame_locator.first

戻り値

• FrameLocator#

---

last

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

非推奨

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

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

使用方法

frame_locator.last

戻り値

• FrameLocator#

---

nth

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

非推奨

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

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

使用方法

frame_locator.nth(index)

引数

• index int#

戻り値

• FrameLocator#