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.
A selector to use when resolving DOM element.
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'>
await page.getByAltText('Playwright logo').click();
Text to locate the element for.
Optional options: { Optional
Optional exact?: booleanWhether 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.
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">
await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');
Text to locate the element for.
Optional options: { Optional
Optional exact?: booleanWhether 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.
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:
await page
.getByPlaceholder('name@example.com')
.fill('playwright@microsoft.com');
Text to locate the element for.
Optional options: { Optional
Optional exact?: booleanWhether 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.
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 it's implicit role:
await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();
await page.getByRole('checkbox', { name: 'Subscribe' }).check();
await page.getByRole('button', { name: /submit/i }).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.
Required aria role.
Optional options: { Optional
Optional checked?: booleanAn attribute that is usually set by aria-checked or native <input type=checkbox> controls.
Learn more about aria-checked.
Optional disabled?: booleanAn 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.
Optional exact?: booleanWhether name is matched exactly: case-sensitive and whole-string. Defaults to false. Ignored when name is a
regular expression. Note that exact match still trims whitespace.
Optional expanded?: booleanAn attribute that is usually set by aria-expanded.
Learn more about aria-expanded.
Optional includeOption 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.
Optional level?: numberA number attribute that is usually present for roles heading, listitem, row, treeitem, with default values
for <h1>-<h6> elements.
Learn more about aria-level.
Optional name?: string | RegExpOption 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.
Optional pressed?: booleanAn attribute that is usually set by aria-pressed.
Learn more about aria-pressed.
Optional selected?: booleanAn attribute that is usually set by aria-selected.
Learn more about aria-selected.
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 it's test id:
await page.getByTestId('directions').click();
Details
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.
// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
testIdAttribute: 'data-pw'
},
});
Id to locate the element by.
Allows locating elements that contain given text.
See also locator.filter([options]) 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.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);
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">.
Text to locate the element for.
Optional options: { Optional
Optional exact?: booleanWhether 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.
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:
await expect(page.getByTitle('Issues count')).toHaveText('25 issues');
Text to locate the element for.
Optional options: { Optional
Optional exact?: booleanWhether 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.
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.
A selector or locator to use when resolving DOM element.
Optional options: { Optional
Optional has?: LocatorNarrows down the results of the method to those which contain elements matching this relative locator. For example,
article that has text=Playwright matches <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 content that has div in
<article><content><div>Playwright</div></content></article>. However, looking for content that has article div will fail, because the inner locator must be relative and should not use any elements outside the content.
Note that outer and inner locators must belong to the same frame. Inner locator must not contain FrameLocators.
Optional hasMatches elements that do not contain an element that matches an inner locator. Inner locator is queried against the
outer one. For example, article that does not have div matches <article><span>Playwright</span></article>.
Note that outer and inner locators must belong to the same frame. Inner locator must not contain FrameLocators.
Optional hasMatches elements that do not contain 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.
Optional hasMatches 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 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.
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 locator.contentFrame().
Usage
const frameLocator = page.frameLocator('iframe[name="embedded"]');
// ...
const locator = frameLocator.owner();
await expect(locator).toBeVisible();
Generated using TypeDoc
FrameLocator represents a view to the
iframeon the page. It captures the logic sufficient to retrieve theiframeand locate elements in that iframe. FrameLocator can be created with either page.frameLocator(selector) or locator.frameLocator(selector) method.Strictness
Frame locators are strict. This means that all operations on frame locators will throw if more than one element matches a given selector.
Converting Locator to FrameLocator
If you have a Locator object pointing to an
iframeit can be converted to FrameLocator using locator.contentFrame().Converting FrameLocator to Locator
If you have a FrameLocator object it can be converted to Locator pointing to the same
iframeusing frameLocator.owner().