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 Playwright.Locator.content_frame/1, Playwright.Page.frame_locator/2 or Playwright.Locator.frame_locator/2 method.
locator = Page.locator(page, "#my-frame") |> Locator.content_frame() |> FrameLocator.get_by_text("Submit")
Locator.click!(locator)Strictness
Frame locators are strict. This means that all operations on frame locators will fail if more than one element matches a given selector.
# Throws if there are several frames in DOM:
Page.locator(page, ".result-frame")
|> Locator.content_frame()
|> FrameLocator.get_by_role(:button)
|> Locator.click!()
# Works because we explicitly tell locator to pick the first frame:
Page.locator(page, ".result-frame")
|> Locator.content_frame()
|> FrameLocator.first()
|> FrameLocator.get_by_role(:button)
|> Locator.click!()Any frame
Calling Playwright.Page.frame_locator/2 or Playwright.Frame.frame_locator/2 without a selector creates a frame locator that
starts the search in any frame of the subtree - so that you don't
need to locate the iframe first.
# Finds the button in any frame on the page:
Page.frame_locator(page) |> FrameLocator.get_by_role(:button) |> Locator.click!()
# Finds the iframe with id "my-frame" anywhere on the page, and clicks the button inside it:
Page.frame_locator(page)
|> FrameLocator.locator("#my-frame")
|> Locator.content_frame()
|> FrameLocator.get_by_role(:button)
|> Locator.click!()Only the start of the search is affected - the rest of the locator is resolved inside a single frame, just like any other locator. Following the strictness rules above, the call fails when elements are matched in multiple frames.
Such a frame locator does not point to a particular iframe, so Playwright.FrameLocator.owner/1,
Playwright.FrameLocator.first/1, Playwright.FrameLocator.last/1 and Playwright.FrameLocator.nth/2 are not supported on it.
Converting Locator to FrameLocator
If you have a Locator object pointing to an iframe it can be converted to FrameLocator using Playwright.Locator.content_frame/1.
Converting FrameLocator to Locator
If you have a FrameLocator object it can be converted to Locator pointing to the same iframe using Playwright.FrameLocator.owner/1.
Since Playwright 1.17.
The examples alias the modules they use (alias Playwright.{Locator, Page}).
Summary
Types
Options of get_by_alt_text/3, see its docs.
Options of get_by_label/3, see its docs.
Options of get_by_placeholder/3, see its docs.
Options of get_by_role/3, see its docs.
Options of get_by_text/3, see its docs.
Options of get_by_title/3, see its docs.
Options of locator/3, see its docs.
A FrameLocator handle. Compare handles with ==, their fields are internal.
Functions
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.
Allows locating elements by their alt text.
Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute.
Allows locating input elements by the placeholder text.
Allows locating elements by their ARIA role, ARIA attributes and accessible name.
Locate element by the test id.
Allows locating elements that contain given text.
Allows locating elements by their title attribute.
Returns locator to the last matching frame.
The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to Playwright.Locator.filter/2 method.
Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.
Returns a Locator object pointing to the same iframe as this frame locator.
Types
Options of get_by_alt_text/3, see its docs.
Options of get_by_label/3, see its docs.
Options of get_by_placeholder/3, see its docs.
@type get_by_role_options() :: [ checked: boolean(), description: String.t() | Regex.t() | Playwright.RegExp.t(), disabled: boolean(), exact: boolean(), expanded: boolean(), include_hidden: boolean(), level: integer(), name: String.t() | Regex.t() | Playwright.RegExp.t(), pressed: boolean(), selected: boolean() ] | %{ optional(:checked) => boolean(), optional(:description) => String.t() | Regex.t() | Playwright.RegExp.t(), optional(:disabled) => boolean(), optional(:exact) => boolean(), optional(:expanded) => boolean(), optional(:include_hidden) => boolean(), optional(:level) => integer(), optional(:name) => String.t() | Regex.t() | Playwright.RegExp.t(), optional(:pressed) => boolean(), optional(:selected) => boolean() }
Options of get_by_role/3, see its docs.
Options of get_by_text/3, see its docs.
Options of get_by_title/3, see its docs.
@type locator_options() :: [ has: Playwright.Locator.t(), has_not: Playwright.Locator.t(), has_not_text: String.t() | Regex.t() | Playwright.RegExp.t(), has_text: String.t() | Regex.t() | Playwright.RegExp.t() ] | %{ optional(:has) => Playwright.Locator.t(), optional(:has_not) => Playwright.Locator.t(), optional(:has_not_text) => String.t() | Regex.t() | Playwright.RegExp.t(), optional(:has_text) => String.t() | Regex.t() | Playwright.RegExp.t() }
Options of locator/3, see its docs.
A FrameLocator handle. Compare handles with ==, their fields are internal.
Functions
Returns locator to the first matching frame.
Since Playwright 1.17.
When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.
Since Playwright 1.17.
Arguments
selector- A selector to use when resolving DOM element.
@spec get_by_alt_text( t(), String.t() | Regex.t() | Playwright.RegExp.t(), get_by_alt_text_options() ) :: Playwright.Locator.t()
Allows locating elements by their alt text.
Usage
For example, this method will find the image by alt text "Playwright logo":
<img alt='Playwright logo'>Page.get_by_alt_text(page, "Playwright logo") |> Locator.click!()Since Playwright 1.27.
Arguments
text- Text to locate the element for.
Options
:exact(boolean/0) - 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.
@spec get_by_label( t(), String.t() | Regex.t() | Playwright.RegExp.t(), get_by_label_options() ) :: Playwright.Locator.t()
Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute.
Usage
For example, this method will find inputs by label "Username" and "Password" in the following DOM:
<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">Page.get_by_label(page, "Username") |> Locator.fill!("john")
Page.get_by_label(page, "Password") |> Locator.fill!("secret")Since Playwright 1.27.
Arguments
text- Text to locate the element for.
Options
:exact(boolean/0) - 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.
@spec get_by_placeholder( t(), String.t() | Regex.t() | Playwright.RegExp.t(), get_by_placeholder_options() ) :: Playwright.Locator.t()
Allows locating input elements by the placeholder text.
Usage
For example, consider the following DOM structure.
<input type="email" placeholder="name@example.com" />You can fill the input after locating it by the placeholder text:
Page.get_by_placeholder(page, "name@example.com") |> Locator.fill!("playwright@microsoft.com")Since Playwright 1.27.
Arguments
text- Text to locate the element for.
Options
:exact(boolean/0) - 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.
@spec get_by_role( t(), :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 | String.t(), get_by_role_options() ) :: Playwright.Locator.t()
Allows locating elements by their ARIA role, ARIA attributes and accessible name.
Usage
Consider the following DOM structure.
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>You can locate each element by its implicit role:
Page.get_by_role(page, :heading, name: "Sign up") |> Expect.to_be_visible!()
Page.get_by_role(page, :checkbox, name: "Subscribe") |> Locator.check!()
Page.get_by_role(page, :button, name: ~r/submit/i) |> Locator.click!()Details
Role selector does not replace accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
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.
Since Playwright 1.27.
Arguments
role- Required aria role.In Elixir, a role is an atom of the typespec (
:button) or a string, also one the typespec lacks ("mark"): the JS client takes any string.
Options
:checked(boolean/0) - An attribute that is usually set byaria-checkedor native<input type=checkbox>controls.Learn more about
aria-checked.:description(String.t/0|Regex.t/0|Playwright.RegExp.t/0) - Since Playwright 1.60. Option to match the accessible description. By default, matching is case-insensitive and searches for a substring, use:exactto control this behavior.Learn more about accessible description.
:disabled(boolean/0) - An attribute that is usually set byaria-disabledordisabled.Note
Unlike most other attributes,
disabledis inherited through the DOM hierarchy. Learn more aboutaria-disabled.:exact(boolean/0) - Since Playwright 1.28. Whether:nameand:descriptionare matched exactly: case-sensitive and whole-string. Defaults to false. Ignored when the value is a regular expression. Note that exact match still trims whitespace.:expanded(boolean/0) - An attribute that is usually set byaria-expanded.Learn more about
aria-expanded.:include_hidden(boolean/0) - Option 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(integer/0) - A number attribute that is usually present for rolesheading,listitem,row,treeitem, with default values for<h1>-<h6>elements.Learn more about
aria-level.:name(String.t/0|Regex.t/0|Playwright.RegExp.t/0) - Option to match the accessible name. By default, matching is case-insensitive and searches for a substring, use:exactto control this behavior.Learn more about accessible name.
:pressed(boolean/0) - An attribute that is usually set byaria-pressed.Learn more about
aria-pressed.:selected(boolean/0) - An attribute that is usually set byaria-selected.Learn more about
aria-selected.
@spec get_by_test_id(t(), String.t() | Regex.t() | Playwright.RegExp.t()) :: Playwright.Locator.t()
Locate element by the test id.
Usage
Consider the following DOM structure.
<button data-testid="directions">Itinéraire</button>You can locate the element by its test id:
Page.get_by_test_id(page, "directions") |> Locator.click!()Details
By default, the data-testid attribute is used as a test id. Use Playwright.Selectors.set_test_id_attribute/2 to configure a different test id attribute if necessary.
# Set a custom test id attribute:
Playwright.selectors(playwright) |> Selectors.set_test_id_attribute("data-pw")Since Playwright 1.27.
Arguments
test_id- Id to locate the element by.
@spec get_by_text( t(), String.t() | Regex.t() | Playwright.RegExp.t(), get_by_text_options() ) :: Playwright.Locator.t()
Allows locating elements that contain given text.
See also Playwright.Locator.filter/2 that allows to match by another criteria, like an accessible role, and then filter by the text content.
Usage
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.get_by_text(page, "world")
# Matches first <div>
Page.get_by_text(page, "Hello world")
# Matches second <div>
Page.get_by_text(page, "Hello", exact: true)
# Matches both <div>s
Page.get_by_text(page, ~r/Hello/)
# Matches second <div>
Page.get_by_text(page, ~r/^hello$/i)Details
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.
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">.
Since Playwright 1.27.
Arguments
text- Text to locate the element for.
Options
:exact(boolean/0) - 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.
@spec get_by_title( t(), String.t() | Regex.t() | Playwright.RegExp.t(), get_by_title_options() ) :: Playwright.Locator.t()
Allows locating elements by their title attribute.
Usage
Consider the following DOM structure.
<span title='Issues count'>25 issues</span>You can check the issues count after locating it by the title text:
Page.get_by_title(page, "Issues count") |> Expect.to_have_text!("25 issues")Since Playwright 1.27.
Arguments
text- Text to locate the element for.
Options
:exact(boolean/0) - 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 to the last matching frame.
Since Playwright 1.17.
@spec locator(t(), String.t() | Playwright.Locator.t(), locator_options()) :: Playwright.Locator.t()
The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to Playwright.Locator.filter/2 method.
Since Playwright 1.17.
Arguments
selector_or_locator- A selector or locator to use when resolving DOM element.
Options
:has(Playwright.Locator.t/0) - Narrows down the results of the method to those which contain elements matching this relative locator. For example,articlethat hastext=Playwrightmatches<article><div>Playwright</div></article>.Inner locator must be relative to the outer locator and is queried starting with the outer locator match, not the document root. For example, you can find
contentthat hasdivin<article><content><div>Playwright</div></content></article>. However, looking forcontentthat hasarticle divwill fail, because the inner locator must be relative and should not use any elements outside thecontent.Note that outer and inner locators must belong to the same frame. Inner locator must not contain
FrameLocators.:has_not(Playwright.Locator.t/0) - Since Playwright 1.33. Matches elements that do not contain an element that matches an inner locator. Inner locator is queried against the outer one. For example,articlethat does not havedivmatches<article><span>Playwright</span></article>.Note that outer and inner locators must belong to the same frame. Inner locator must not contain
FrameLocators.:has_not_text(String.t/0|Regex.t/0|Playwright.RegExp.t/0) - Since Playwright 1.33. Matches elements that do not contain specified text somewhere inside, possibly in a child or a descendant element. When passed astring, matching is case-insensitive and searches for a substring.:has_text(String.t/0|Regex.t/0|Playwright.RegExp.t/0) - Matches elements containing specified text somewhere inside, possibly in a child or a descendant element. When passed astring, matching is case-insensitive and searches for a substring. For example,"Playwright"matches<article><div>Playwright</div></article>.
Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.
Since Playwright 1.17.
@spec owner(t()) :: Playwright.Locator.t()
Returns a Locator object pointing to the same iframe as this frame locator.
Useful when you have a FrameLocator object obtained somewhere, and later on would like to interact with the iframe element.
For a reverse operation, use Playwright.Locator.content_frame/1.
Usage
frame_locator = Page.locator(page, ~s(iframe[name="embedded"])) |> Locator.content_frame()
# ...
locator = FrameLocator.owner(frame_locator)
Expect.to_be_visible!(locator)Since Playwright 1.43.