Skip to main content
Version: 1.18

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(selector) or locator.frame_locator(selector) method.

locator = page.frame_locator("my-frame").locator("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 given selector.

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

# Works because we explicitly tell locator to pick the first frame:
page.frame_locator('.result-frame').first.locator('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:

frameLocator = locator.frame_locator(":scope");

frame_locator.first

Returns locator to the first matching frame.

frame_locator.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.

frame_locator.last

Returns locator to the last matching frame.

frame_locator.locator(selector, **kwargs)

  • selector <str> A selector to use when resolving DOM element. See working with selectors for more details.#
  • has_text <str|Pattern> Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. For example, "Playwright" matches <article><div>Playwright</div></article>.#
  • returns: <Locator>#

The method finds an element matching the specified selector in the FrameLocator's subtree.

frame_locator.nth(index)

Returns locator to the n-th matching frame.