Skip to main content
Frame queries methods for the Playwright driver.

​
locator

The method returns a Locator for the given selector.
The locator is a building block for accessing and interacting with elements on the page. Locators are strict by default - they will throw if more than one element matches the selector.
Upstream docs
​
selector
string
required
​
options
{ has?: RemotePlaywrightLocator; hasNot?: RemotePlaywrightLocator; hasText?: string | RegExp; hasNotText?: string | RegExp }
​
result
RemotePlaywrightLocator
Return value
await frame.locator('...');

​
frameLocator

Returns a FrameLocator for the given selector.
Use this when the <iframe> is lazy loaded. Use has and hasText options to locate elements inside a frame based on their content.
Upstream docs
​
selector
string
required
​
result
RemotePlaywrightFrameLocator
Return value
await frame.frameLocator('...');

​
getByRole

Allows locating elements by their ARIA role, ARIA attributes and accessible name. Upstream docs
​
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
​
options
PlaywrightGetByRoleOptions
​
result
RemotePlaywrightLocator
Return value
await frame.getByRole(/* "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" */);

​
getByText

Allows locating elements that contain given text.
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.
Upstream docs
​
text
string | RegExp
required
​
options
PlaywrightGetByTextOptions
​
result
RemotePlaywrightLocator
Return value
await frame.getByText(/* string | RegExp */);

​
getByLabel

Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute. Upstream docs
​
text
string | RegExp
required
​
options
PlaywrightGetByLabelOptions
​
result
RemotePlaywrightLocator
Return value
await frame.getByLabel(/* string | RegExp */);

​
getByPlaceholder

Allows locating input elements by the placeholder text. Upstream docs
​
text
string | RegExp
required
​
options
PlaywrightGetByPlaceholderOptions
​
result
RemotePlaywrightLocator
Return value
await frame.getByPlaceholder(/* string | RegExp */);

​
getByAltText

Allows locating elements by their alt text.
This method allows locating elements by their alt text. It works with <img> and <area> elements.
Upstream docs
​
text
string | RegExp
required
​
options
PlaywrightGetByAltTextOptions
​
result
RemotePlaywrightLocator
Return value
await frame.getByAltText(/* string | RegExp */);

​
getByTitle

Allows locating elements by their title attribute. Upstream docs
​
text
string | RegExp
required
​
options
PlaywrightGetByTitleOptions
​
result
RemotePlaywrightLocator
Return value
await frame.getByTitle(/* string | RegExp */);

​
getByTestId

Locate element by the test id.
By default, the data-testid attribute is used as a test id. Use selectors.setTestIdAttribute() to configure a different test id attribute if necessary.
Upstream docs
​
testId
string | RegExp
required
​
result
RemotePlaywrightLocator
Return value
await frame.getByTestId(/* string | RegExp */);

​
$

Returns the ElementHandle pointing to the frame element.
This method queries the frame for the given selector. If no element matches the selector, returns null. Discouraged: use locator-based frame.locator() instead.
Upstream docs
​
selector
string
required
​
result
SerializedHandle | null
Return value
await frame.$('...');

​
$$

Returns the ElementHandles pointing to the frame elements.
This method queries the frame for all elements matching the given selector. Returns empty array if no elements match. Discouraged: use locator-based frame.locator() instead.
Upstream docs
​
selector
string
required
​
result
SerializedHandle[]
Return value
await frame.$$('...');