Class: Playwright::FrameLocator

Inherits:
PlaywrightApi show all
Defined in:
lib/playwright_api/frame_locator.rb,
sig/playwright.rbs

Overview

FrameLocator represents a view to the iframe on the page. It captures the logic sufficient to retrieve the iframe and locate elements in that iframe. FrameLocator can be created with either [method: Locator.contentFrame], [method: Page.frameLocator] or [method: Locator.frameLocator] method.

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

Strictness

Frame locators are strict. This means that all operations on frame locators will throw if more than one element matches a given selector.

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

Any frame

Calling [method: Page.frameLocator] or [method: Frame.frameLocator] without a selector creates a frame locator that starts the search in any frame of the subtree - so that you don't need to locate the iframe first.

# Finds the button in any frame on the page:
page.frame_locator().get_by_role("button").click()

# Finds the iframe with id "my-frame" anywhere on the page, and clicks the button inside it:
page.frame_locator().locator("#my-frame").content_frame.get_by_role("button").click()

Only the start of the search is affected - the rest of the locator is resolved inside a single frame, just like any other locator. Following the strictness rules above, an error is thrown when elements are matched in multiple frames.

Such a frame locator does not point to a particular iframe, so [method: FrameLocator.owner], [method: FrameLocator.first], [method: FrameLocator.last] and [method: FrameLocator.nth] are not supported on it.

Converting Locator to FrameLocator

If you have a Locator object pointing to an iframe it can be converted to FrameLocator using [method: Locator.contentFrame].

Converting FrameLocator to Locator

If you have a FrameLocator object it can be converted to Locator pointing to the same iframe using [method: FrameLocator.owner].

Instance Method Summary collapse

Methods inherited from PlaywrightApi

#initialize, unwrap, wrap

Constructor Details

This class inherits a constructor from Playwright::PlaywrightApi

Instance Method Details

#first ⇒ FrameLocator

Deprecated.

Use [method: Locator.first] followed by [method: Locator.contentFrame] instead.

Returns locator to the first matching frame.

Returns:



55
56
57
 
# File 'lib/playwright_api/frame_locator.rb', line 55

def first
  wrap_impl(@impl.first)
end

#frame_locator(selector) ⇒ FrameLocator

When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.

Parameters:

  • selector (String)

Returns:



62
63
64
 
# File 'lib/playwright_api/frame_locator.rb', line 62

def frame_locator(selector)
  wrap_impl(@impl.frame_locator(unwrap_impl(selector)))
end

#get_by_alt_text(text, exact: nil) ⇒ Locator

Allows locating elements by their alt text.

Usage

For example, this method will find the image by alt text "Playwright logo":

<img alt='Playwright logo'>

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

Parameters:

  • text (String, Regexp)
  • exact: (Boolean) (defaults to: nil)

Returns:



80
81
82
 
# File 'lib/playwright_api/frame_locator.rb', line 80

def get_by_alt_text(text, exact: nil)
  wrap_impl(@impl.get_by_alt_text(unwrap_impl(text), exact: unwrap_impl(exact)))
end

#get_by_label(text, exact: nil) ⇒ Locator

Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute.

Usage

For example, this method will find inputs by label "Username" and "Password" in the following DOM:

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

Parameters:

  • text (String, Regexp)
  • exact: (Boolean) (defaults to: nil)

Returns:



101
102
103
 
# File 'lib/playwright_api/frame_locator.rb', line 101

def get_by_label(text, exact: nil)
  wrap_impl(@impl.get_by_label(unwrap_impl(text), exact: unwrap_impl(exact)))
end

#get_by_placeholder(text, exact: nil) ⇒ Locator

Allows locating input elements by the placeholder text.

Usage

For example, consider the following DOM structure.

<input type="email" placeholder="[email protected]" />

You can fill the input after locating it by the placeholder text:

page.get_by_placeholder("[email protected]").fill("[email protected]")

Parameters:

  • text (String, Regexp)
  • exact: (Boolean) (defaults to: nil)

Returns:



121
122
123
 
# File 'lib/playwright_api/frame_locator.rb', line 121

def get_by_placeholder(text, exact: nil)
  wrap_impl(@impl.get_by_placeholder(unwrap_impl(text), exact: unwrap_impl(exact)))
end

#get_by_role(role, checked: nil, description: nil, disabled: nil, exact: nil, expanded: nil, includeHidden: nil, level: nil, name: nil, pressed: nil, selected: nil) ⇒ Locator

Allows locating elements by their ARIA role, ARIA attributes and accessible name.

Usage

Consider the following DOM structure.

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

You can locate each element by its implicit role:

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

Details

Role selector does not replace accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.

Many html elements have an implicitly defined role that is recognized by the role selector. You can find all the supported roles here. ARIA guidelines do not recommend duplicating implicit roles and attributes by setting role and/or aria-* attributes to default values.

Parameters:

  • 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")
  • checked: (Boolean) (defaults to: nil)
  • description: (String, Regexp) (defaults to: nil)
  • disabled: (Boolean) (defaults to: nil)
  • exact: (Boolean) (defaults to: nil)
  • expanded: (Boolean) (defaults to: nil)
  • includeHidden: (Boolean) (defaults to: nil)
  • level: (Integer) (defaults to: nil)
  • name: (String, Regexp) (defaults to: nil)
  • pressed: (Boolean) (defaults to: nil)
  • selected: (Boolean) (defaults to: nil)

Returns:



156
157
158
159
160
161
162
163
164
165
166
167
168
169
 
# File 'lib/playwright_api/frame_locator.rb', line 156

def get_by_role(
      role,
      checked: nil,
      description: nil,
      disabled: nil,
      exact: nil,
      expanded: nil,
      includeHidden: nil,
      level: nil,
      name: nil,
      pressed: nil,
      selected: nil)
  wrap_impl(@impl.get_by_role(unwrap_impl(role), checked: unwrap_impl(checked), description: unwrap_impl(description), disabled: unwrap_impl(disabled), exact: unwrap_impl(exact), expanded: unwrap_impl(expanded), includeHidden: unwrap_impl(includeHidden), level: unwrap_impl(level), name: unwrap_impl(name), pressed: unwrap_impl(pressed), selected: unwrap_impl(selected)))
end

#get_by_test_id(testId) ⇒ Locator Also known as: get_by_testid

Locate element by the test id.

Usage

Consider the following DOM structure.

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

You can locate the element by its test id:

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

Details

By default, the data-testid attribute is used as a test id. Use [method: Selectors.setTestIdAttribute] to configure a different test id attribute if necessary.

Parameters:

  • testId (String, Regexp)

Returns:



191
192
193
 
# File 'lib/playwright_api/frame_locator.rb', line 191

def get_by_test_id(testId)
  wrap_impl(@impl.get_by_test_id(unwrap_impl(testId)))
end

#get_by_text(text, exact: nil) ⇒ Locator

Allows locating elements that contain given text.

See also [method: Locator.filter] that allows to match by another criteria, like an accessible role, and then filter by the text content.

Usage

Consider the following DOM structure:

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

You can locate by text substring, exact string, or a regular expression:

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

Details

Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.

Input elements of the type button and submit are matched by their value instead of the text content. For example, locating by text "Log in" matches <input type=button value="Log in">.

Parameters:

  • text (String, Regexp)
  • exact: (Boolean) (defaults to: nil)

Returns:



234
235
236
 
# File 'lib/playwright_api/frame_locator.rb', line 234

def get_by_text(text, exact: nil)
  wrap_impl(@impl.get_by_text(unwrap_impl(text), exact: unwrap_impl(exact)))
end

#get_by_title(text, exact: nil) ⇒ Locator

Allows locating elements by their title attribute.

Usage

Consider the following DOM structure.

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

You can check the issues count after locating it by the title text:

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

Parameters:

  • text (String, Regexp)
  • exact: (Boolean) (defaults to: nil)

Returns:



254
255
256
 
# File 'lib/playwright_api/frame_locator.rb', line 254

def get_by_title(text, exact: nil)
  wrap_impl(@impl.get_by_title(unwrap_impl(text), exact: unwrap_impl(exact)))
end

#last ⇒ FrameLocator

Deprecated.

Use [method: Locator.last] followed by [method: Locator.contentFrame] instead.

Returns locator to the last matching frame.

Returns:



262
263
264
 
# File 'lib/playwright_api/frame_locator.rb', line 262

def last
  wrap_impl(@impl.last)
end

#locator(selectorOrLocator, has: nil, hasNot: nil, hasNotText: nil, hasText: nil) ⇒ Locator

The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to [method: Locator.filter] method.

Learn more about locators.

Parameters:

  • selectorOrLocator (String, Locator)
  • has: (Locator) (defaults to: nil)
  • hasNot: (Locator) (defaults to: nil)
  • hasNotText: (String, Regexp) (defaults to: nil)
  • hasText: (String, Regexp) (defaults to: nil)

Returns:



270
271
272
273
274
275
276
277
 
# File 'lib/playwright_api/frame_locator.rb', line 270

def locator(
      selectorOrLocator,
      has: nil,
      hasNot: nil,
      hasNotText: nil,
      hasText: nil)
  wrap_impl(@impl.locator(unwrap_impl(selectorOrLocator), has: unwrap_impl(has), hasNot: unwrap_impl(hasNot), hasNotText: unwrap_impl(hasNotText), hasText: unwrap_impl(hasText)))
end

#nth(index) ⇒ FrameLocator

Deprecated.

Use [method: Locator.nth] followed by [method: Locator.contentFrame] instead.

Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.

Parameters:

  • index (Integer)

Returns:



283
284
285
 
# File 'lib/playwright_api/frame_locator.rb', line 283

def nth(index)
  wrap_impl(@impl.nth(unwrap_impl(index)))
end

#owner ⇒ Locator

Returns a Locator object pointing to the same iframe as this frame locator.

Useful when you have a FrameLocator object obtained somewhere, and later on would like to interact with the iframe element.

For a reverse operation, use [method: Locator.contentFrame].

Usage

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

Returns:



302
303
304
 
# File 'lib/playwright_api/frame_locator.rb', line 302

def owner
  wrap_impl(@impl.owner)
end