Playwright · API reference · all subjects

framelocator

19 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

FrameLocator class overview

FrameLocator represents a view to an iframe on the page. It captures the logic sufficient to retrieve the iframe and locate elements within that iframe. FrameLocator can be created with Locator.contentFrame, Page.frameLocator, or Locator.frameLocator methods. FrameLocator was introduced in v1.17.

FrameLocator strictness behavior

Frame locators are strict. All operations on frame locators will throw if more than one element matches a given selector. To work with multiple frames, explicitly specify which frame to target using methods like first() or nth().

Convert FrameLocator to Locator

A FrameLocator object can be converted to a Locator pointing to the same iframe using the FrameLocator.owner method.

FrameLocator.first() method

FrameLocator.first() returns a FrameLocator object pointing to the first matching frame. This method is deprecated as of v1.17; use Locator.first followed by Locator.contentFrame instead.

FrameLocator.last() method

FrameLocator.last() returns a FrameLocator object pointing to the last matching frame. This method is deprecated as of v1.17; use Locator.last followed by Locator.contentFrame instead.

FrameLocator.nth() method

FrameLocator.nth(index) returns a FrameLocator object pointing to the n-th matching frame. It is zero-based, so nth(0) selects the first frame. The method accepts an integer parameter 'index'. This method is deprecated as of v1.17; use Locator.nth followed by Locator.contentFrame instead.

FrameLocator.frameLocator() method

FrameLocator.frameLocator(selector) returns a FrameLocator object. When working with nested iframes, this method creates a frame locator that will enter the iframe and allow selecting elements in that iframe. Introduced in v1.17.

FrameLocator.locator() method

FrameLocator.locator(selectorOrLocator) returns a Locator object. It accepts a selector string or Locator object, and supports options including hasNot (v1.33+) and hasNotText (v1.33+). Introduced in v1.17.

FrameLocator accessibility locator methods

FrameLocator provides the following semantic/accessibility attribute targeting methods, all returning Locator objects: getByRole (v1.27+), getByLabel (v1.27+), getByPlaceholder (v1.27+), getByAltText (v1.27+), getByTitle (v1.27+), getByText (v1.27+), and getByTestId (v1.27+).

FrameLocator.getByRole() method signature

FrameLocator.getByRole(role, options) returns a Locator object. It accepts a required role parameter and optional parameters including exact, description, and others defined in the v1.27+ option list. Introduced in v1.27.

FrameLocator.getByLabel() method signature

FrameLocator.getByLabel(text, options) returns a Locator object. It accepts a required text parameter and an optional exact option. Introduced in v1.27.

FrameLocator.getByTitle() method signature

FrameLocator.getByTitle(text, options) returns a Locator object. It accepts a required text parameter and an optional exact option. Introduced in v1.27.

FrameLocator.getByText() method signature

FrameLocator.getByText(text, options) returns a Locator object. It accepts a required text parameter and an optional exact option. Introduced in v1.27.

FrameLocator.getByTestId() method signature

FrameLocator.getByTestId(testId) returns a Locator object. It accepts a required testId parameter. Introduced in v1.27.

FrameLocator.get() method

FrameLocator.get(by) returns a Locator object. It accepts a By parameter that is a page-free locator built with Playwright.by. Available in JavaScript only. Introduced in v1.63.

FrameLocator.owner() method

FrameLocator.owner() returns a Locator object pointing to the same iframe as the frame locator. This is useful when you have a FrameLocator object and later need to interact with the iframe element itself. For the reverse operation, use Locator.contentFrame. Introduced in v1.43.

FrameLocator usage example with contentFrame

Example: const locator = page.locator('#my-frame').contentFrame().getByText('Submit'); await locator.click();. This demonstrates locating an iframe by CSS selector, entering the frame, finding an element by text within that frame, and clicking it.

FrameLocator strictness example

Example: await page.locator('.result-frame').contentFrame().getByRole('button').click(); throws if multiple frames match '.result-frame'. To fix, use: await page.locator('.result-frame').first().contentFrame().getByRole('button').click(); to explicitly select the first frame.

FrameLocator.owner() usage example

Example: const frameLocator = page.locator('iframe[name="embedded"]').contentFrame(); const locator = frameLocator.owner(); await expect(locator).toBeVisible();. This demonstrates obtaining a FrameLocator, then converting it back to a Locator pointing to the iframe element, and making an assertion on it.

Give your agent this brain