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

const locator = page.frameLocator('#my-frame').getByText('Submit');
await 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:
await page.frameLocator('.result-frame').getByRole('button').click();

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

const frameLocator = locator.frameLocator(':scope');

frameLocator.first()​

Added in: v1.17

Returns locator to the first matching frame.

frameLocator.frameLocator(selector)​

Added in: v1.17

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

frameLocator.getByAltText(text[, options])​

Added in: v1.27
  • text <string|RegExp> Text to locate the element for.#
  • options? <Object>
    • exact? <boolean> Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.#
  • returns: <Locator>#

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

<img alt='Castle'>

frameLocator.getByLabel(text[, options])​

Added in: v1.27
  • text <string|RegExp> Text to locate the element for.#
  • options? <Object>
    • exact? <boolean> Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.#
  • returns: <Locator>#

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

frameLocator.getByPlaceholder(text[, options])​

Added in: v1.27
  • text <string|RegExp> Text to locate the element for.#
  • options? <Object>
    • exact? <boolean> Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.#
  • returns: <Locator>#

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

<input placeholder="Country">

frameLocator.getByRole(role[, options])​

Added in: v1.27

  • role <"alert"|"alertdialog"|"application"|"article"|"banner"|"blockquote"|"button"|"caption"|"cell"|"checkbox"|"code"|"columnheader"|"combobox"|"complementary"|"contentinfo"|"definition"|"deletion"|"dialog"|"directory"|"document"|"emphasis"|"feed"|"figure"|"form"|"generic"|"grid"|"gridcell"|"group"|"heading"|"img"|"insertion"|"link"|"list"|"listbox"|"listitem"|"log"|"main"|"marquee"|"math"|"meter"|"menu"|"menubar"|"menuitem"|"menuitemcheckbox"|"menuitemradio"|"navigation"|"none"|"note"|"option"|"paragraph"|"presentation"|"progressbar"|"radio"|"radiogroup"|"region"|"row"|"rowgroup"|"rowheader"|"scrollbar"|"search"|"searchbox"|"separator"|"slider"|"spinbutton"|"status"|"strong"|"subscript"|"superscript"|"switch"|"tab"|"table"|"tablist"|"tabpanel"|"term"|"textbox"|"time"|"timer"|"toolbar"|"tooltip"|"tree"|"treegrid"|"treeitem"> Required aria role.#

  • options? <Object>

    • checked? <boolean> An attribute that is usually set by aria-checked or native <input type=checkbox> controls. Available values for checked are true, false and "mixed".#

      Learn more about aria-checked.

    • disabled? <boolean> A boolean attribute that is usually set by aria-disabled or disabled.#

      note

      Unlike most other attributes, disabled is inherited through the DOM hierarchy. Learn more about aria-disabled.

    • expanded? <boolean> A boolean attribute that is usually set by aria-expanded.#

      Learn more about aria-expanded.

    • includeHidden? <boolean> A boolean attribute that controls whether hidden elements are matched. By default, only non-hidden elements, as defined by ARIA, are matched by role selector.#

      Learn more about aria-hidden.

    • level? <number> A number attribute that is usually present for roles heading, listitem, row, treeitem, with default values for <h1>-<h6> elements.#

      Learn more about aria-level.

    • name? <string|RegExp> A string attribute that matches accessible name.#

      Learn more about accessible name.

    • pressed? <boolean> An attribute that is usually set by aria-pressed. Available values for pressed are true, false and "mixed".#

      Learn more about aria-pressed.

    • selected? <boolean> A boolean attribute that is usually set by aria-selected.#

      Learn more about aria-selected.

  • returns: <Locator>#

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.

frameLocator.getByTestId(testId)​

Added in: v1.27

Locate element by the test id. By default, the data-testid attribute is used as a test id. Use selectors.setTestIdAttribute(attributeName) to configure a different test id attribute if necessary.

frameLocator.getByText(text[, options])​

Added in: v1.27
  • text <string|RegExp> Text to locate the element for.#
  • options? <Object>
    • exact? <boolean> Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.#
  • returns: <Locator>#

Allows locating elements that contain given text. Consider the following DOM structure:

<div>Hello <span>world</span></div>
<div>Hello</div>

You can locate by text substring, exact string, or a regular expression:

// Matches <span>
page.getByText('world')

// Matches first <div>
page.getByText('Hello world')

// Matches second <div>
page.getByText('Hello', { exact: true })

// Matches both <div>s
page.getByText(/Hello/)

// Matches second <div>
page.getByText(/^hello$/i)

See also locator.filter([options]) that allows to match by another criteria, like an accessible role, and then filter by the text content.

note

Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.

note

Input elements of the type button and submit are matched by their value instead of the text content. For example, locating by text "Log in" matches <input type=button value="Log in">.

frameLocator.getByTitle(text[, options])​

Added in: v1.27
  • text <string|RegExp> Text to locate the element for.#
  • options? <Object>
    • exact? <boolean> Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.#
  • returns: <Locator>#

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>

frameLocator.last()​

Added in: v1.17

Returns locator to the last matching frame.

frameLocator.locator(selector[, options])​

Added in: v1.17

  • selector <string> A selector to use when resolving DOM element. See working with selectors for more details.#

  • options? <Object>

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

    • hasText? <string|RegExp> 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 locator's subtree. It also accepts filter options, similar to locator.filter([options]) method.

Learn more about locators.

frameLocator.nth(index)​

Added in: v1.17

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