Class: Playwright::FrameLocator

Inherits:
PlaywrightApi show all
Defined in:
lib/playwright_api/frame_locator.rb

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: Page.frameLocator`] or [`method: Locator.frameLocator`] method.

“‘python sync locator = page.frame_locator(“my-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.

“‘python sync # Throws if there are several frames in DOM: page.frame_locator(’.result-frame’).get_by_role(‘button’).click()

# Works because we explicitly tell locator to pick the first frame: page.frame_locator(‘.result-frame’).first.get_by_role(‘button’).click() “‘

**Converting Locator to FrameLocator**

If you have a ‘Locator` object pointing to an `iframe` it can be converted to `FrameLocator` using [`:scope`](developer.mozilla.org/en-US/docs/Web/CSS/:scope) CSS selector:

“‘python sync frameLocator = locator.frame_locator(“:scope”) “`

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 ⇒ Object

Returns locator to the first matching frame.



33
34
35
 
# File 'lib/playwright_api/frame_locator.rb', line 33

def first
  wrap_impl(@impl.first)
end

#frame_locator(selector) ⇒ Object

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



40
41
42
 
# File 'lib/playwright_api/frame_locator.rb', line 40

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

#get_by_alt_text(text, exact: nil) ⇒ Object

Allows locating elements by their alt text.

Usage

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

“‘html <img alt=’Playwright logo’> “‘

“‘python sync page.get_by_alt_text(“Playwright logo”).click() “`



58
59
60
 
# File 'lib/playwright_api/frame_locator.rb', line 58

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) ⇒ Object

Allows locating input elements by the text of the associated label.

Usage

For example, this method will find the input by label text “Password” in the following DOM:

“‘html <label for=“password-input”>Password:</label> <input id=“password-input”> “`

“‘python sync page.get_by_label(“Password”).fill(“secret”) “`



77
78
79
 
# File 'lib/playwright_api/frame_locator.rb', line 77

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) ⇒ Object

Allows locating input elements by the placeholder text.

Usage

For example, consider the following DOM structure.

“‘html <input type=“email” placeholder=“[email protected]” /> “`

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

“‘python sync page.get_by_placeholder(“[email protected]”).fill(“[email protected]”) “`



97
98
99
 
# File 'lib/playwright_api/frame_locator.rb', line 97

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, disabled: nil, exact: nil, expanded: nil, includeHidden: nil, level: nil, name: nil, pressed: nil, selected: nil) ⇒ Object

Allows locating elements by their [ARIA role](www.w3.org/TR/wai-aria-1.2/#roles), [ARIA attributes](www.w3.org/TR/wai-aria-1.2/#aria-attributes) and [accessible name](w3c.github.io/accname/#dfn-accessible-name).

Usage

Consider the following DOM structure.

“‘html <h3>Sign up</h3> <label>

<input type="checkbox" /> Subscribe

</label> <br/> <button>Submit</button> “‘

You can locate each element by it’s implicit role:

“‘python sync 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](w3c.github.io/html-aam/#html-element-role-mappings) that is recognized by the role selector. You can find all the [supported roles here](www.w3.org/TR/wai-aria-1.2/#role_definitions). ARIA guidelines **do not recommend** duplicating implicit roles and attributes by setting ‘role` and/or `aria-*` attributes to default values.



132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/playwright_api/frame_locator.rb', line 132

def get_by_role(
      role,
      checked: 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), 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) ⇒ Object

Locate element by the test id.

Usage

Consider the following DOM structure.

“‘html <button data-testid=“directions”>Itinéraire</button> “`

You can locate the element by it’s test id:

“‘python sync 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.



166
167
168
 
# File 'lib/playwright_api/frame_locator.rb', line 166

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

#get_by_text(text, exact: nil) ⇒ Object

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:

“‘html <div>Hello <span>world</span></div> <div>Hello</div> “`

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

“‘python sync # 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”>`.



208
209
210
 
# File 'lib/playwright_api/frame_locator.rb', line 208

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) ⇒ Object

Allows locating elements by their title attribute.

Usage

Consider the following DOM structure.

“‘html <span title=’Issues count’>25 issues</span> “‘

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

“‘python sync expect(page.get_by_title(“Issues count”)).to_have_text(“25 issues”) “`



228
229
230
 
# File 'lib/playwright_api/frame_locator.rb', line 228

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

#last ⇒ Object

Returns locator to the last matching frame.



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

def last
  wrap_impl(@impl.last)
end

#locator(selector, has: nil, hasText: nil) ⇒ Object

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](../locators.md).



242
243
244
 
# File 'lib/playwright_api/frame_locator.rb', line 242

def locator(selector, has: nil, hasText: nil)
  wrap_impl(@impl.locator(unwrap_impl(selector), has: unwrap_impl(has), hasText: unwrap_impl(hasText)))
end

#nth(index) ⇒ Object

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



248
249
250
 
# File 'lib/playwright_api/frame_locator.rb', line 248

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