Skip to main content

FrameLocator

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 Page#frame_locator or Locator#frame_locator method.

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.

# 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 CSS selector:

frame_locator = locator.frame_locator(':scope')

first​

def first

Returns locator to the first matching frame.

frame_locator​

def frame_locator(selector)

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​

def get_by_alt_text(text, exact: nil)

Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":

<img alt='Castle'>

get_by_label​

def get_by_label(text, exact: nil)

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:

<label for="password-input">Password:</label>
<input id="password-input">

get_by_placeholder​

def get_by_placeholder(text, exact: nil)

Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder "Country":

<input placeholder="Country">

get_by_role​

def get_by_role(
      role,
      checked: nil,
      disabled: nil,
      expanded: nil,
      includeHidden: nil,
      level: nil,
      name: nil,
      pressed: nil,
      selected: nil)

Allows locating elements by their ARIA role, ARIA attributes and 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 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.

get_by_test_id​

def get_by_test_id(testId)

Locate element by the test id. By default, the data-testid attribute is used as a test id. Use Selectors#set_test_id_attribute to configure a different test id attribute if necessary.

get_by_text​

def get_by_text(text, exact: nil)

Allows locating elements that contain given text.

get_by_title​

def get_by_title(text, exact: nil)

Allows locating elements by their title. For example, this method will find the button by its title "Submit":

<button title='Place the order'>Order Now</button>

last​

def last

Returns locator to the last matching frame.

locator​

def locator(selector, has: nil, hasText: nil)

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

Learn more about locators.

nth​

def nth(index)

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