Skip to main content
Version: 1.23

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 <Locator> Matches elements containing an element that matches an inner locator. Inner locator is queried against the outer one. For example, article that has text=Playwright matches <article><div>Playwright</div></article>.#

    Note that outer and inner locators must belong to the same frame. Inner locator must not contain FrameLocators.

  • has_text <str|Pattern> Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When passed a [string], matching is case-insensitive and searches for a substring. 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. It's zero based, nth(0) selects the first frame.