Package com.microsoft.playwright

Interface FrameLocator

  • 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 Locator.contentFrame().

    Converting FrameLocator to Locator

    If you have a FrameLocator object it can be converted to Locator pointing to the same iframe using FrameLocator.owner().

    • Method Detail

      • 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

        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

      • 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

      • owner

        Locator owner()
        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 

        
 FrameLocator frameLocator = page.frameLocator("iframe[name=\"embedded\"]");
 // ...
 Locator locator = frameLocator.owner();
 assertThat(locator).isVisible();
        Since:
        v1.43