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() or Locator.FrameLocator() method.
var locator = page.FrameLocator("#my-frame").GetByText("Submit");
await locator.ClickAsync();
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(AriaRole.Button).ClickAsync();
// Works because we explicitly tell locator to pick the first frame:
await page.FrameLocator(".result-frame").First.getByRole(AriaRole.Button).ClickAsync();
Converting Locator to FrameLocator
If you have a Locator object pointing to an iframe
it can be converted to FrameLocator using :scope
CSS selector:
var frameLocator = locator.FrameLocator(":scope");
Methods
First
Added in: v1.17Returns locator to the first matching frame.
Usage
FrameLocator.First
Returns
FrameLocator
Added in: v1.17When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.
Usage
FrameLocator.FrameLocator(selector);
Arguments
Returns
GetByAltText
Added in: v1.27Allows locating elements by their alt text.
Usage
For example, this method will find the image by alt text "Playwright logo":
<img alt='Playwright logo'>
await page.GetByAltText("Playwright logo").ClickAsync();
Arguments
-
Text to locate the element for.
-
options
FrameLocatorGetByAltTextOptions?
(optional)
Returns
GetByLabel
Added in: v1.27Allows 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">
await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");
Arguments
-
Text to locate the element for.
-
options
FrameLocatorGetByLabelOptions?
(optional)
Returns
GetByPlaceholder
Added in: v1.27Allows 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:
await page
.GetByPlaceholder("name@example.com")
.FillAsync("playwright@microsoft.com");
Arguments
-
Text to locate the element for.
-
options
FrameLocatorGetByPlaceholderOptions?
(optional)
Returns
GetByRole
Added in: v1.27Allows 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 it's implicit role:
await Expect(Page
.GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
.ToBeVisibleAsync();
await page
.GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
.CheckAsync();
await page
.GetByRole(AriaRole.Button, new() {
NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
})
.ClickAsync();
Arguments
-
role
enum AriaRole { 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
FrameLocatorGetByRoleOptions?
(optional)-
An attribute that is usually set by
aria-checked
or native<input type=checkbox>
controls.Learn more about
aria-checked
. -
An attribute that is usually set by
aria-disabled
ordisabled
.noteUnlike most other attributes,
disabled
is inherited through the DOM hierarchy. Learn more aboutaria-disabled
. -
Exact
bool? (optional) Added in: v1.28#Whether
name
is matched exactly: case-sensitive and whole-string. Defaults to false. Ignored whenname
is a regular expression. Note that exact match still trims whitespace. -
An attribute that is usually set by
aria-expanded
.Learn more about
aria-expanded
. -
IncludeHidden
bool? (optional)#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
. -
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|NameRegex
string?|Regex? (optional)#Option to match the accessible name. By default, matching is case-insensitive and searches for a substring, use
exact
to control this behavior.Learn more about accessible name.
-
An attribute that is usually set by
aria-pressed
.Learn more about
aria-pressed
. -
An attribute that is usually set by
aria-selected
.Learn more about
aria-selected
.
-
Returns
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.
GetByTestId
Added in: v1.27Locate element by the test id.
Usage
Consider the following DOM structure.
<button data-testid="directions">Itinéraire</button>
You can locate the element by it's test id:
await page.GetByTestId("directions").ClickAsync();
Arguments
Returns
Details
By default, the data-testid
attribute is used as a test id. Use Selectors.SetTestIdAttribute() to configure a different test id attribute if necessary.