Package com.microsoft.playwright

Interface FrameLocator

All Known Implementing Classes:
FrameLocatorImpl
public interface 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. 

 Locator locator = page.frameLocator("#my-frame").getByText("Submit");
 locator.click();

**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:
 page.frame_locator(".result-frame").getByRole(AriaRole.BUTTON).click();

 // Works because we explicitly tell locator to pick the first frame:
 page.frame_locator(".result-frame").first().getByRole(AriaRole.BUTTON).click();

**Converting Locator to FrameLocator**

If you have a Locator object pointing to an iframe it can be converted to FrameLocator using :scope CSS selector: 


 Locator frameLocator = locator.frameLocator(':scope');

  • Method Details

    • first

      FrameLocator first()
      Returns locator to the first matching frame.
      Since:
      v1.17

    • frameLocator

      FrameLocator frameLocator(String selector)
      When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.
      Parameters:
      selector - A selector to use when resolving DOM element.
      Since:
      v1.17

    • getByAltText

      default Locator getByAltText(String text)
      Allows locating elements by their alt text.

      **Usage**

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

      
 page.getByAltText("Playwright logo").click();
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByAltText

      Locator getByAltText(String text, FrameLocator.GetByAltTextOptions options)
      Allows locating elements by their alt text.

      **Usage**

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

      
 page.getByAltText("Playwright logo").click();
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByAltText

      default Locator getByAltText(Pattern text)
      Allows locating elements by their alt text.

      **Usage**

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

      
 page.getByAltText("Playwright logo").click();
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByAltText

      Locator getByAltText(Pattern text, FrameLocator.GetByAltTextOptions options)
      Allows locating elements by their alt text.

      **Usage**

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

      
 page.getByAltText("Playwright logo").click();
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByLabel

      default Locator getByLabel(String text)
      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: 

      
 page.getByLabel("Username").fill("john");
 page.getByLabel("Password").fill("secret");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByLabel

      Locator getByLabel(String text, FrameLocator.GetByLabelOptions options)
      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: 

      
 page.getByLabel("Username").fill("john");
 page.getByLabel("Password").fill("secret");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByLabel

      default Locator getByLabel(Pattern text)
      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: 

      
 page.getByLabel("Username").fill("john");
 page.getByLabel("Password").fill("secret");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByLabel

      Locator getByLabel(Pattern text, FrameLocator.GetByLabelOptions options)
      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: 

      
 page.getByLabel("Username").fill("john");
 page.getByLabel("Password").fill("secret");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByPlaceholder

      default Locator getByPlaceholder(String text)
      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: 

      
 page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByPlaceholder

      Locator getByPlaceholder(String text, FrameLocator.GetByPlaceholderOptions options)
      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: 

      
 page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByPlaceholder

      default Locator getByPlaceholder(Pattern text)
      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: 

      
 page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByPlaceholder

      Locator getByPlaceholder(Pattern text, FrameLocator.GetByPlaceholderOptions options)
      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: 

      
 page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByRole

      default Locator getByRole(AriaRole role)
      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: 

      
 assertThat(page
     .getByRole(AriaRole.HEADING,
                new Page.GetByRoleOptions().setName("Sign up")))
     .isVisible();

 page.getByRole(AriaRole.CHECKBOX,
                new Page.GetByRoleOptions().setName("Subscribe"))
     .check();

 page.getByRole(AriaRole.BUTTON,
                new Page.GetByRoleOptions().setName(
                    Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
     .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.

      Parameters:
      role - Required aria role.
      Since:
      v1.27

    • getByRole

      Locator getByRole(AriaRole role, FrameLocator.GetByRoleOptions options)
      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: 

      
 assertThat(page
     .getByRole(AriaRole.HEADING,
                new Page.GetByRoleOptions().setName("Sign up")))
     .isVisible();

 page.getByRole(AriaRole.CHECKBOX,
                new Page.GetByRoleOptions().setName("Subscribe"))
     .check();

 page.getByRole(AriaRole.BUTTON,
                new Page.GetByRoleOptions().setName(
                    Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
     .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.

      Parameters:
      role - Required aria role.
      Since:
      v1.27

    • getByTestId

      Locator getByTestId(String testId)
      Locate element by the test id.

      **Usage**

      Consider the following DOM structure.

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

      
 page.getByTestId("directions").click();

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

      Parameters:
      testId - Id to locate the element by.
      Since:
      v1.27

    • getByTestId

      Locator getByTestId(Pattern testId)
      Locate element by the test id.

      **Usage**

      Consider the following DOM structure.

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

      
 page.getByTestId("directions").click();

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

      Parameters:
      testId - Id to locate the element by.
      Since:
      v1.27

    • getByText

      default Locator getByText(String text)
      Allows locating elements that contain given text.

      See also Locator.filter() 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 Page.GetByTextOptions().setExact(true))

 // Matches both <div>s
 page.getByText(Pattern.compile("Hello"))

 // Matches second <div>
 page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE))

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

      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByText

      Locator getByText(String text, FrameLocator.GetByTextOptions options)
      Allows locating elements that contain given text.

      See also Locator.filter() 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 Page.GetByTextOptions().setExact(true))

 // Matches both <div>s
 page.getByText(Pattern.compile("Hello"))

 // Matches second <div>
 page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE))

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

      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByText

      default Locator getByText(Pattern text)
      Allows locating elements that contain given text.

      See also Locator.filter() 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 Page.GetByTextOptions().setExact(true))

 // Matches both <div>s
 page.getByText(Pattern.compile("Hello"))

 // Matches second <div>
 page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE))

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

      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByText

      Locator getByText(Pattern text, FrameLocator.GetByTextOptions options)
      Allows locating elements that contain given text.

      See also Locator.filter() 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 Page.GetByTextOptions().setExact(true))

 // Matches both <div>s
 page.getByText(Pattern.compile("Hello"))

 // Matches second <div>
 page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE))

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

      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByTitle

      default Locator getByTitle(String text)
      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: 

      
 assertThat(page.getByTitle("Issues count")).hasText("25 issues");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByTitle

      Locator getByTitle(String text, FrameLocator.GetByTitleOptions options)
      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: 

      
 assertThat(page.getByTitle("Issues count")).hasText("25 issues");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByTitle

      default Locator getByTitle(Pattern text)
      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: 

      
 assertThat(page.getByTitle("Issues count")).hasText("25 issues");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • getByTitle

      Locator getByTitle(Pattern text, FrameLocator.GetByTitleOptions options)
      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: 

      
 assertThat(page.getByTitle("Issues count")).hasText("25 issues");
      Parameters:
      text - Text to locate the element for.
      Since:
      v1.27

    • last

      FrameLocator last()
      Returns locator to the last matching frame.
      Since:
      v1.17

    • locator

      default Locator locator(String selectorOrLocator)
      The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to Locator.filter() method.

      Learn more about locators.

      Parameters:
      selectorOrLocator - A selector or locator to use when resolving DOM element.
      Since:
      v1.17

    • locator

      Locator locator(String selectorOrLocator, FrameLocator.LocatorOptions options)
      The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to Locator.filter() method.

      Learn more about locators.

      Parameters:
      selectorOrLocator - A selector or locator to use when resolving DOM element.
      Since:
      v1.17

    • locator

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

      Learn more about locators.

      Parameters:
      selectorOrLocator - A selector or locator to use when resolving DOM element.
      Since:
      v1.17

    • locator

      Locator locator(Locator selectorOrLocator, FrameLocator.LocatorOptions options)
      The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to Locator.filter() method.

      Learn more about locators.

      Parameters:
      selectorOrLocator - A selector or locator to use when resolving DOM element.
      Since:
      v1.17

    • nth

      FrameLocator nth(int index)
      Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.
      Since:
      v1.17