Class: Playwright::FrameLocator
- Inherits:
-
PlaywrightApi
- Object
- PlaywrightApi
- Playwright::FrameLocator
- 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
-
#first ⇒ Object
Returns locator to the first matching frame.
-
#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.
-
#get_by_alt_text(text, exact: nil) ⇒ Object
Allows locating elements by their alt text.
-
#get_by_label(text, exact: nil) ⇒ Object
Allows locating input elements by the text of the associated label.
-
#get_by_placeholder(text, exact: nil) ⇒ Object
Allows locating input elements by the placeholder text.
-
#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).
-
#get_by_test_id(testId) ⇒ Object
Locate element by the test id.
-
#get_by_text(text, exact: nil) ⇒ Object
Allows locating elements that contain given text.
-
#get_by_title(text, exact: nil) ⇒ Object
Allows locating elements by their title.
-
#last ⇒ Object
Returns locator to the last matching frame.
-
#locator(selector, has: nil, hasText: nil) ⇒ Object
The method finds an element matching the specified selector in the locator’s subtree.
-
#nth(index) ⇒ Object
Returns locator to the n-th matching frame.
Methods inherited from PlaywrightApi
Constructor Details
This class inherits a constructor from Playwright::PlaywrightApi
Instance Method Details
#first ⇒ Object
Returns locator to the first matching frame.
35 36 37 |
# File 'lib/playwright_api/frame_locator.rb', line 35 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.
41 42 43 |
# File 'lib/playwright_api/frame_locator.rb', line 41 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. For example, this method will find the image by alt text “Castle”:
“‘html <img alt=’Castle’> “‘
50 51 52 |
# File 'lib/playwright_api/frame_locator.rb', line 50 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. 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”> “`
61 62 63 |
# File 'lib/playwright_api/frame_locator.rb', line 61 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. For example, this method will find the input by placeholder “Country”:
“‘html <input placeholder=“Country”> “`
71 72 73 |
# File 'lib/playwright_api/frame_locator.rb', line 71 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). Note that role selector **does not replace** accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
Note that 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.
84 85 86 87 88 89 90 91 92 93 94 95 96 |
# File 'lib/playwright_api/frame_locator.rb', line 84 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(), 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. 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.
100 101 102 |
# File 'lib/playwright_api/frame_locator.rb', line 100 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. 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)) “‘
See also [‘method: Locator.filter`] that allows to match by another criteria, like an accessible role, and then filter by the text content.
> NOTE: 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. > NOTE: 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”>`.
137 138 139 |
# File 'lib/playwright_api/frame_locator.rb', line 137 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. For example, this method will find the button by its title “Place the order”:
“‘html <button title=’Place the order’>Order Now</button> “‘
146 147 148 |
# File 'lib/playwright_api/frame_locator.rb', line 146 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.
151 152 153 |
# File 'lib/playwright_api/frame_locator.rb', line 151 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).
159 160 161 |
# File 'lib/playwright_api/frame_locator.rb', line 159 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.
164 165 166 |
# File 'lib/playwright_api/frame_locator.rb', line 164 def nth(index) wrap_impl(@impl.nth(unwrap_impl(index))) end |