Skip to main content
Version: 1.18


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


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:

# Works because we explicitly tell locator to pick the first frame:

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


Returns locator to the first matching frame.


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


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.


Returns locator to the n-th matching frame.