Interface IFrameLocator

Namespace

Microsoft.Playwright

Assembly

Microsoft.Playwright.dll

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 FrameLocator(string) or FrameLocator(string) 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 ILocator object pointing to an iframe it can be converted to IFrameLocator using ContentFrame.

**Converting FrameLocator to Locator**

If you have a IFrameLocator object it can be converted to ILocator pointing to the same iframe using Owner.

public interface IFrameLocator

Properties

First

Returns locator to the first matching frame.

IFrameLocator First { get; }

Property Value

IFrameLocator

Last

Returns locator to the last matching frame.

IFrameLocator Last { get; }

Property Value

IFrameLocator

Owner

Returns a ILocator object pointing to the same iframe as this frame locator.

Useful when you have a IFrameLocator object obtained somewhere, and later on would like to interact with the iframe element.

For a reverse operation, use ContentFrame.

**Usage**

var frameLocator = Page.FrameLocator("iframe[name=\"embedded\"]");
// ...
var locator = frameLocator.Owner;
await Expect(locator).ToBeVisibleAsync();

ILocator Owner { get; }

Property Value

ILocator

Methods

FrameLocator(string)

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

IFrameLocator FrameLocator(string selector)

Parameters

selector string

A selector to use when resolving DOM element.

Returns

IFrameLocator

GetByAltText(string, FrameLocatorGetByAltTextOptions?)

Allows locating elements by their alt text.

**Usage**

For example, this method will find the image by alt text "Playwright logo":

await page.GetByAltText("Playwright logo").ClickAsync();

ILocator GetByAltText(string text, FrameLocatorGetByAltTextOptions? options = null)

Parameters

text string

Text to locate the element for.

options FrameLocatorGetByAltTextOptions

Call options

Returns

ILocator

GetByAltText(Regex, FrameLocatorGetByAltTextOptions?)

Allows locating elements by their alt text.

**Usage**

For example, this method will find the image by alt text "Playwright logo":

await page.GetByAltText("Playwright logo").ClickAsync();

ILocator GetByAltText(Regex text, FrameLocatorGetByAltTextOptions? options = null)

Parameters

text Regex

Text to locate the element for.

options FrameLocatorGetByAltTextOptions

Call options

Returns

ILocator

GetByLabel(string, FrameLocatorGetByLabelOptions?)

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:

await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");

ILocator GetByLabel(string text, FrameLocatorGetByLabelOptions? options = null)

Parameters

text string

Text to locate the element for.

options FrameLocatorGetByLabelOptions

Call options

Returns

ILocator

GetByLabel(Regex, FrameLocatorGetByLabelOptions?)

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:

await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");

ILocator GetByLabel(Regex text, FrameLocatorGetByLabelOptions? options = null)

Parameters

text Regex

Text to locate the element for.

options FrameLocatorGetByLabelOptions

Call options

Returns

ILocator

GetByPlaceholder(string, FrameLocatorGetByPlaceholderOptions?)

Allows locating input elements by the placeholder text.

**Usage**

For example, consider the following DOM structure.

You can fill the input after locating it by the placeholder text:

await page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

ILocator GetByPlaceholder(string text, FrameLocatorGetByPlaceholderOptions? options = null)

Parameters

text string

Text to locate the element for.

options FrameLocatorGetByPlaceholderOptions

Call options

Returns

ILocator

GetByPlaceholder(Regex, FrameLocatorGetByPlaceholderOptions?)

Allows locating input elements by the placeholder text.

**Usage**

For example, consider the following DOM structure.

You can fill the input after locating it by the placeholder text:

await page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

ILocator GetByPlaceholder(Regex text, FrameLocatorGetByPlaceholderOptions? options = null)

Parameters

text Regex

Text to locate the element for.

options FrameLocatorGetByPlaceholderOptions

Call options

Returns

ILocator

GetByRole(AriaRole, FrameLocatorGetByRoleOptions?)

Allows locating elements by their ARIA role, ARIA attributes and accessible name.

**Usage**

Consider the following DOM structure.

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();

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

ILocator GetByRole(AriaRole role, FrameLocatorGetByRoleOptions? options = null)

Parameters

role AriaRole

Required aria role.

options FrameLocatorGetByRoleOptions

Call options

Returns

ILocator

GetByTestId(string)

Locate element by the test id.

**Usage**

Consider the following DOM structure.

You can locate the element by it's test id:

await page.GetByTestId("directions").ClickAsync();

**Details**

By default, the data-testid attribute is used as a test id. Use SetTestIdAttribute(string) to configure a different test id attribute if necessary.

ILocator GetByTestId(string testId)

Parameters

testId string

Id to locate the element by.

Returns

ILocator

GetByTestId(Regex)

Locate element by the test id.

**Usage**

Consider the following DOM structure.

You can locate the element by it's test id:

await page.GetByTestId("directions").ClickAsync();

**Details**

By default, the data-testid attribute is used as a test id. Use SetTestIdAttribute(string) to configure a different test id attribute if necessary.

ILocator GetByTestId(Regex testId)

Parameters

testId Regex

Id to locate the element by.

Returns

ILocator

GetByText(string, FrameLocatorGetByTextOptions?)

Allows locating elements that contain given text.

See also Filter(LocatorFilterOptions?) that allows to match by another criteria, like an accessible role, and then filter by the text content.

**Usage**

Consider the following DOM structure:

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", new() { Exact = true });
// Matches both <div>s
page.GetByText(new Regex("Hello"));
// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

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

ILocator GetByText(string text, FrameLocatorGetByTextOptions? options = null)

Parameters

text string

Text to locate the element for.

options FrameLocatorGetByTextOptions

Call options

Returns

ILocator

GetByText(Regex, FrameLocatorGetByTextOptions?)

Allows locating elements that contain given text.

See also Filter(LocatorFilterOptions?) that allows to match by another criteria, like an accessible role, and then filter by the text content.

**Usage**

Consider the following DOM structure:

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", new() { Exact = true });
// Matches both <div>s
page.GetByText(new Regex("Hello"));
// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

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

ILocator GetByText(Regex text, FrameLocatorGetByTextOptions? options = null)

Parameters

text Regex

Text to locate the element for.

options FrameLocatorGetByTextOptions

Call options

Returns

ILocator

GetByTitle(string, FrameLocatorGetByTitleOptions?)

Allows locating elements by their title attribute.

**Usage**

Consider the following DOM structure.

You can check the issues count after locating it by the title text:

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

ILocator GetByTitle(string text, FrameLocatorGetByTitleOptions? options = null)

Parameters

text string

Text to locate the element for.

options FrameLocatorGetByTitleOptions

Call options

Returns

ILocator

GetByTitle(Regex, FrameLocatorGetByTitleOptions?)

Allows locating elements by their title attribute.

**Usage**

Consider the following DOM structure.

You can check the issues count after locating it by the title text:

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

ILocator GetByTitle(Regex text, FrameLocatorGetByTitleOptions? options = null)

Parameters

text Regex

Text to locate the element for.

options FrameLocatorGetByTitleOptions

Call options

Returns

ILocator

Locator(ILocator, FrameLocatorLocatorOptions?)

The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to Filter(LocatorFilterOptions?) method.

Learn more about locators.

ILocator Locator(ILocator selectorOrLocator, FrameLocatorLocatorOptions? options = null)

Parameters

selectorOrLocator ILocator

A selector or locator to use when resolving DOM element.

options FrameLocatorLocatorOptions

Call options

Returns

ILocator

Locator(string, FrameLocatorLocatorOptions?)

The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to Filter(LocatorFilterOptions?) method.

Learn more about locators.

ILocator Locator(string selectorOrLocator, FrameLocatorLocatorOptions? options = null)

Parameters

selectorOrLocator string

A selector or locator to use when resolving DOM element.

options FrameLocatorLocatorOptions

Call options

Returns

ILocator

Nth(int)

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

IFrameLocator Nth(int index)

Parameters

index int

Returns

IFrameLocator