Package com.microsoft.playwright

Interface Locator

  • public interface Locator
    Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way to find element(s) on the page at any moment. A locator can be created with the Page.locator() method.

    Learn more about locators.

    • Method Detail

      • all

        List<Locator> all()
        When the locator points to a list of elements, this returns an array of locators, pointing to their respective elements.

        NOTE: Locator.all() does not wait for elements to match the locator, and instead immediately returns whatever is present in the page. When the list of elements changes dynamically, Locator.all() will produce unpredictable and flaky results. When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before calling Locator.all().

        Usage 

        
 for (Locator li : page.getByRole('listitem').all())
   li.click();
        Since:
        v1.29

      • allInnerTexts

        List<String> allInnerTexts()
        Returns an array of node.innerText values for all matching nodes.

        NOTE: If you need to assert text on the page, prefer LocatorAssertions.hasText() with useInnerText option to avoid flakiness. See assertions guide for more details.

        Usage 

        
 String[] texts = page.getByRole(AriaRole.LINK).allInnerTexts();
        Since:
        v1.14

      • allTextContents

        List<String> allTextContents()
        Returns an array of node.textContent values for all matching nodes.

        NOTE: If you need to assert text on the page, prefer LocatorAssertions.hasText() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 String[] texts = page.getByRole(AriaRole.LINK).allTextContents();
        Since:
        v1.14

      • and

        Locator and​(Locator locator)
        Creates a locator that matches both this locator and the argument locator.

        Usage

        The following example finds a button with a specific title. 

        
 Locator button = page.getByRole(AriaRole.BUTTON).and(page.getByTitle("Subscribe"));
        Parameters:
        locator - Additional locator to match.
        Since:
        v1.34

      • blur

        default void blur()
        Calls blur on the element.
        Since:
        v1.28

      • boundingBox

        default BoundingBox boundingBox()
        This method returns the bounding box of the element matching the locator, or null if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window.

        Details

        Scrolling affects the returned bounding box, similarly to Element.getBoundingClientRect. That means x and/or y may be negative.

        Elements from child frames return the bounding box relative to the main frame, unlike the Element.getBoundingClientRect.

        Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element.

        Usage 

        
 BoundingBox box = page.getByRole(AriaRole.BUTTON).boundingBox();
 page.mouse().click(box.x + box.width / 2, box.y + box.height / 2);
        Since:
        v1.14

      • boundingBox

        BoundingBox boundingBox​(Locator.BoundingBoxOptions options)
        This method returns the bounding box of the element matching the locator, or null if the element is not visible. The bounding box is calculated relative to the main frame viewport - which is usually the same as the browser window.

        Details

        Scrolling affects the returned bounding box, similarly to Element.getBoundingClientRect. That means x and/or y may be negative.

        Elements from child frames return the bounding box relative to the main frame, unlike the Element.getBoundingClientRect.

        Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element.

        Usage 

        
 BoundingBox box = page.getByRole(AriaRole.BUTTON).boundingBox();
 page.mouse().click(box.x + box.width / 2, box.y + box.height / 2);
        Since:
        v1.14

      • check

        default void check()
        Ensure that checkbox or radio element is checked.

        Details

        Performs the following steps:

        1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
        2. Wait for actionability checks on the element, unless force option is set.
        3. Scroll the element into view if needed.
        4. Use Page.mouse() to click in the center of the element.
        5. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
        6. Ensure that the element is now checked. If not, this method throws.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Usage 

        
 page.getByRole(AriaRole.CHECKBOX).check();
        Since:
        v1.14

      • check

        void check​(Locator.CheckOptions options)
        Ensure that checkbox or radio element is checked.

        Details

        Performs the following steps:

        1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
        2. Wait for actionability checks on the element, unless force option is set.
        3. Scroll the element into view if needed.
        4. Use Page.mouse() to click in the center of the element.
        5. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
        6. Ensure that the element is now checked. If not, this method throws.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Usage 

        
 page.getByRole(AriaRole.CHECKBOX).check();
        Since:
        v1.14

      • clear

        default void clear()
        Clear the input field.

        Details

        This method waits for actionability checks, focuses the element, clears it and triggers an input event after clearing.

        If the target element is not an <input>, <textarea> or [contenteditable] element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be cleared instead.

        Usage 

        
 page.getByRole(AriaRole.TEXTBOX).clear();
        Since:
        v1.28

      • clear

        void clear​(Locator.ClearOptions options)
        Clear the input field.

        Details

        This method waits for actionability checks, focuses the element, clears it and triggers an input event after clearing.

        If the target element is not an <input>, <textarea> or [contenteditable] element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be cleared instead.

        Usage 

        
 page.getByRole(AriaRole.TEXTBOX).clear();
        Since:
        v1.28

      • click

        default void click()
        Click an element.

        Details

        This method clicks the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.mouse() to click in the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Usage

        Click a button: 

        
 page.getByRole(AriaRole.BUTTON).click();

        Shift-right-click at a specific position on a canvas: 

        
 page.locator("canvas").click(new Locator.ClickOptions()
   .setButton(MouseButton.RIGHT)
   .setModifiers(Arrays.asList(KeyboardModifier.SHIFT))
   .setPosition(23, 32));
        Since:
        v1.14

      • click

        void click​(Locator.ClickOptions options)
        Click an element.

        Details

        This method clicks the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.mouse() to click in the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Usage

        Click a button: 

        
 page.getByRole(AriaRole.BUTTON).click();

        Shift-right-click at a specific position on a canvas: 

        
 page.locator("canvas").click(new Locator.ClickOptions()
   .setButton(MouseButton.RIGHT)
   .setModifiers(Arrays.asList(KeyboardModifier.SHIFT))
   .setPosition(23, 32));
        Since:
        v1.14

      • count

        int count()
        Returns the number of elements matching the locator.

        NOTE: If you need to assert the number of elements on the page, prefer LocatorAssertions.hasCount() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 int count = page.getByRole(AriaRole.LISTITEM).count();
        Since:
        v1.14

      • dblclick

        default void dblclick()
        Double-click an element.

        Details

        This method double clicks the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.mouse() to double click in the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set. Note that if the first click of the dblclick() triggers a navigation event, this method will throw.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        NOTE: element.dblclick() dispatches two click events and a single dblclick event.

        Since:
        v1.14

      • dblclick

        void dblclick​(Locator.DblclickOptions options)
        Double-click an element.

        Details

        This method double clicks the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.mouse() to double click in the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set. Note that if the first click of the dblclick() triggers a navigation event, this method will throw.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        NOTE: element.dblclick() dispatches two click events and a single dblclick event.

        Since:
        v1.14

      • dispatchEvent

        default void dispatchEvent​(String type,
                           Object eventInit)
        Programmatically dispatch an event on the matching element.

        Usage 

        
 locator.dispatchEvent("click");

        Details

        The snippet above dispatches the click event on the element. Regardless of the visibility state of the element, click is dispatched. This is equivalent to calling element.click().

        Under the hood, it creates an instance of an event based on the given type, initializes it with eventInit properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

        Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:

        You can also specify JSHandle as the property value if you want live objects to be passed into the event: 

        
 // Note you can only create DataTransfer in Chromium and Firefox
 JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
 Map<String, Object> arg = new HashMap<>();
 arg.put("dataTransfer", dataTransfer);
 locator.dispatchEvent("dragstart", arg);
        Parameters:
        type - DOM event type: "click", "dragstart", etc.
        eventInit - Optional event-specific initialization properties.
        Since:
        v1.14

      • dispatchEvent

        default void dispatchEvent​(String type)
        Programmatically dispatch an event on the matching element.

        Usage 

        
 locator.dispatchEvent("click");

        Details

        The snippet above dispatches the click event on the element. Regardless of the visibility state of the element, click is dispatched. This is equivalent to calling element.click().

        Under the hood, it creates an instance of an event based on the given type, initializes it with eventInit properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

        Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:

        You can also specify JSHandle as the property value if you want live objects to be passed into the event: 

        
 // Note you can only create DataTransfer in Chromium and Firefox
 JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
 Map<String, Object> arg = new HashMap<>();
 arg.put("dataTransfer", dataTransfer);
 locator.dispatchEvent("dragstart", arg);
        Parameters:
        type - DOM event type: "click", "dragstart", etc.
        Since:
        v1.14

      • dispatchEvent

        void dispatchEvent​(String type,
                   Object eventInit,
                   Locator.DispatchEventOptions options)
        Programmatically dispatch an event on the matching element.

        Usage 

        
 locator.dispatchEvent("click");

        Details

        The snippet above dispatches the click event on the element. Regardless of the visibility state of the element, click is dispatched. This is equivalent to calling element.click().

        Under the hood, it creates an instance of an event based on the given type, initializes it with eventInit properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

        Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:

        You can also specify JSHandle as the property value if you want live objects to be passed into the event: 

        
 // Note you can only create DataTransfer in Chromium and Firefox
 JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
 Map<String, Object> arg = new HashMap<>();
 arg.put("dataTransfer", dataTransfer);
 locator.dispatchEvent("dragstart", arg);
        Parameters:
        type - DOM event type: "click", "dragstart", etc.
        eventInit - Optional event-specific initialization properties.
        Since:
        v1.14

      • dragTo

        default void dragTo​(Locator target)
        Drag the source element towards the target element and drop it.

        Details

        This method drags the locator to another target locator or target position. It will first move to the source element, perform a mousedown, then move to the target element or position and perform a mouseup.

        Usage 

        
 Locator source = page.locator("#source");
 Locator target = page.locator("#target");

 source.dragTo(target);
 // or specify exact positions relative to the top-left corners of the elements:
 source.dragTo(target, new Locator.DragToOptions()
   .setSourcePosition(34, 7).setTargetPosition(10, 20));
        Parameters:
        target - Locator of the element to drag to.
        Since:
        v1.18

      • dragTo

        void dragTo​(Locator target,
            Locator.DragToOptions options)
        Drag the source element towards the target element and drop it.

        Details

        This method drags the locator to another target locator or target position. It will first move to the source element, perform a mousedown, then move to the target element or position and perform a mouseup.

        Usage 

        
 Locator source = page.locator("#source");
 Locator target = page.locator("#target");

 source.dragTo(target);
 // or specify exact positions relative to the top-left corners of the elements:
 source.dragTo(target, new Locator.DragToOptions()
   .setSourcePosition(34, 7).setTargetPosition(10, 20));
        Parameters:
        target - Locator of the element to drag to.
        Since:
        v1.18

      • elementHandle

        default ElementHandle elementHandle()
        Resolves given locator to the first matching DOM element. If there are no matching elements, waits for one. If multiple elements match the locator, throws.
        Since:
        v1.14

      • elementHandle

        ElementHandle elementHandle​(Locator.ElementHandleOptions options)
        Resolves given locator to the first matching DOM element. If there are no matching elements, waits for one. If multiple elements match the locator, throws.
        Since:
        v1.14

      • elementHandles

        List<ElementHandle> elementHandles()
        Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.
        Since:
        v1.14

      • contentFrame

        FrameLocator contentFrame()
        Returns a FrameLocator object pointing to the same iframe as this locator.

        Useful when you have a Locator object obtained somewhere, and later on would like to interact with the content inside the frame.

        For a reverse operation, use FrameLocator.owner().

        Usage 

        
 Locator locator = page.locator("iframe[name=\"embedded\"]");
 // ...
 FrameLocator frameLocator = locator.contentFrame();
 frameLocator.getByRole(AriaRole.BUTTON).click();
        Since:
        v1.43

      • evaluate

        default Object evaluate​(String expression,
                        Object arg)
        Execute JavaScript code in the page, taking the matching element as an argument.

        Details

        Returns the return value of expression, called with the matching element as a first argument, and arg as a second argument.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        Usage 

        
 Locator tweets = page.locator(".tweet .retweets");
 assertEquals("10 retweets", tweets.evaluate("node => node.innerText"));
        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        arg - Optional argument to pass to expression.
        Since:
        v1.14

      • evaluate

        default Object evaluate​(String expression)
        Execute JavaScript code in the page, taking the matching element as an argument.

        Details

        Returns the return value of expression, called with the matching element as a first argument, and arg as a second argument.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        Usage 

        
 Locator tweets = page.locator(".tweet .retweets");
 assertEquals("10 retweets", tweets.evaluate("node => node.innerText"));
        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        Since:
        v1.14

      • evaluate

        Object evaluate​(String expression,
                Object arg,
                Locator.EvaluateOptions options)
        Execute JavaScript code in the page, taking the matching element as an argument.

        Details

        Returns the return value of expression, called with the matching element as a first argument, and arg as a second argument.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        Usage 

        
 Locator tweets = page.locator(".tweet .retweets");
 assertEquals("10 retweets", tweets.evaluate("node => node.innerText"));
        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        arg - Optional argument to pass to expression.
        Since:
        v1.14

      • evaluateAll

        default Object evaluateAll​(String expression)
        Execute JavaScript code in the page, taking all matching elements as an argument.

        Details

        Returns the return value of expression, called with an array of all matching elements as a first argument, and arg as a second argument.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        Usage 

        
 Locator locator = page.locator("div");
 boolean moreThanTen = (boolean) locator.evaluateAll("(divs, min) => divs.length > min", 10);
        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        Since:
        v1.14

      • evaluateAll

        Object evaluateAll​(String expression,
                   Object arg)
        Execute JavaScript code in the page, taking all matching elements as an argument.

        Details

        Returns the return value of expression, called with an array of all matching elements as a first argument, and arg as a second argument.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        Usage 

        
 Locator locator = page.locator("div");
 boolean moreThanTen = (boolean) locator.evaluateAll("(divs, min) => divs.length > min", 10);
        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        arg - Optional argument to pass to expression.
        Since:
        v1.14

      • evaluateHandle

        default JSHandle evaluateHandle​(String expression,
                                Object arg)
        Execute JavaScript code in the page, taking the matching element as an argument, and return a JSHandle with the result.

        Details

        Returns the return value of expression as aJSHandle, called with the matching element as a first argument, and arg as a second argument.

        The only difference between Locator.evaluate() and Locator.evaluateHandle() is that Locator.evaluateHandle() returns JSHandle.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        See Page.evaluateHandle() for more details.

        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        arg - Optional argument to pass to expression.
        Since:
        v1.14

      • evaluateHandle

        default JSHandle evaluateHandle​(String expression)
        Execute JavaScript code in the page, taking the matching element as an argument, and return a JSHandle with the result.

        Details

        Returns the return value of expression as aJSHandle, called with the matching element as a first argument, and arg as a second argument.

        The only difference between Locator.evaluate() and Locator.evaluateHandle() is that Locator.evaluateHandle() returns JSHandle.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        See Page.evaluateHandle() for more details.

        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        Since:
        v1.14

      • evaluateHandle

        JSHandle evaluateHandle​(String expression,
                        Object arg,
                        Locator.EvaluateHandleOptions options)
        Execute JavaScript code in the page, taking the matching element as an argument, and return a JSHandle with the result.

        Details

        Returns the return value of expression as aJSHandle, called with the matching element as a first argument, and arg as a second argument.

        The only difference between Locator.evaluate() and Locator.evaluateHandle() is that Locator.evaluateHandle() returns JSHandle.

        If expression returns a Promise, this method will wait for the promise to resolve and return its value.

        If expression throws or rejects, this method throws.

        See Page.evaluateHandle() for more details.

        Parameters:
        expression - JavaScript expression to be evaluated in the browser context. If the expression evaluates to a function, the function is automatically invoked.
        arg - Optional argument to pass to expression.
        Since:
        v1.14

      • fill

        default void fill​(String value)
        Set a value to the input field.

        Usage 

        
 page.getByRole(AriaRole.TEXTBOX).fill("example value");

        Details

        This method waits for actionability checks, focuses the element, fills it and triggers an input event after filling. Note that you can pass an empty string to clear the input field.

        If the target element is not an <input>, <textarea> or [contenteditable] element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be filled instead.

        To send fine-grained keyboard events, use Locator.pressSequentially().

        Parameters:
        value - Value to set for the <input>, <textarea> or [contenteditable] element.
        Since:
        v1.14

      • fill

        void fill​(String value,
          Locator.FillOptions options)
        Set a value to the input field.

        Usage 

        
 page.getByRole(AriaRole.TEXTBOX).fill("example value");

        Details

        This method waits for actionability checks, focuses the element, fills it and triggers an input event after filling. Note that you can pass an empty string to clear the input field.

        If the target element is not an <input>, <textarea> or [contenteditable] element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be filled instead.

        To send fine-grained keyboard events, use Locator.pressSequentially().

        Parameters:
        value - Value to set for the <input>, <textarea> or [contenteditable] element.
        Since:
        v1.14

      • filter

        default Locator filter()
        This method narrows existing locator according to the options, for example filters by text. It can be chained to filter multiple times.

        Usage 

        
 Locator rowLocator = page.locator("tr");
 // ...
 rowLocator
     .filter(new Locator.FilterOptions().setHasText("text in column 1"))
     .filter(new Locator.FilterOptions().setHas(
         page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("column 2 button"))
     ))
     .screenshot();
        Since:
        v1.22

      • filter

        Locator filter​(Locator.FilterOptions options)
        This method narrows existing locator according to the options, for example filters by text. It can be chained to filter multiple times.

        Usage 

        
 Locator rowLocator = page.locator("tr");
 // ...
 rowLocator
     .filter(new Locator.FilterOptions().setHasText("text in column 1"))
     .filter(new Locator.FilterOptions().setHas(
         page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("column 2 button"))
     ))
     .screenshot();
        Since:
        v1.22

      • first

        Locator first()
        Returns locator to the first matching element.
        Since:
        v1.14

      • focus

        default void focus()
        Calls focus on the matching element.
        Since:
        v1.14

      • frameLocator

        FrameLocator frameLocator​(String selector)
        When working with iframes, you can create a frame locator that will enter the iframe and allow locating elements in that iframe:

        Usage 

        
 Locator locator = page.frameLocator("iframe").getByText("Submit");
 locator.click();
        Parameters:
        selector - A selector to use when resolving DOM element.
        Since:
        v1.17

      • getAttribute

        default String getAttribute​(String name)
        Returns the matching element's attribute value.

        NOTE: If you need to assert an element's attribute, prefer LocatorAssertions.hasAttribute() to avoid flakiness. See assertions guide for more details.

        Parameters:
        name - Attribute name to get the value for.
        Since:
        v1.14

      • 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,
                     Locator.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,
                     Locator.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,
                   Locator.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,
                   Locator.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,
                         Locator.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,
                         Locator.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,
                  Locator.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,
                  Locator.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,
                  Locator.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,
                   Locator.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,
                   Locator.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

      • highlight

        void highlight()
        Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses Locator.highlight().
        Since:
        v1.20

      • hover

        default void hover()
        Hover over the matching element.

        Usage 

        
 page.getByRole(AriaRole.LINK).hover();

        Details

        This method hovers over the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.mouse() to hover over the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Since:
        v1.14

      • hover

        void hover​(Locator.HoverOptions options)
        Hover over the matching element.

        Usage 

        
 page.getByRole(AriaRole.LINK).hover();

        Details

        This method hovers over the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.mouse() to hover over the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Since:
        v1.14

      • inputValue

        default String inputValue()
        Returns the value for the matching <input> or <textarea> or <select> element.

        NOTE: If you need to assert input value, prefer LocatorAssertions.hasValue() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 String value = page.getByRole(AriaRole.TEXTBOX).inputValue();

        Details

        Throws elements that are not an input, textarea or a select. However, if the element is inside the <label> element that has an associated control, returns the value of the control.

        Since:
        v1.14

      • inputValue

        String inputValue​(Locator.InputValueOptions options)
        Returns the value for the matching <input> or <textarea> or <select> element.

        NOTE: If you need to assert input value, prefer LocatorAssertions.hasValue() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 String value = page.getByRole(AriaRole.TEXTBOX).inputValue();

        Details

        Throws elements that are not an input, textarea or a select. However, if the element is inside the <label> element that has an associated control, returns the value of the control.

        Since:
        v1.14

      • isChecked

        default boolean isChecked()
        Returns whether the element is checked. Throws if the element is not a checkbox or radio input.

        NOTE: If you need to assert that checkbox is checked, prefer LocatorAssertions.isChecked() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 boolean checked = page.getByRole(AriaRole.CHECKBOX).isChecked();
        Since:
        v1.14

      • isChecked

        boolean isChecked​(Locator.IsCheckedOptions options)
        Returns whether the element is checked. Throws if the element is not a checkbox or radio input.

        NOTE: If you need to assert that checkbox is checked, prefer LocatorAssertions.isChecked() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 boolean checked = page.getByRole(AriaRole.CHECKBOX).isChecked();
        Since:
        v1.14

      • isDisabled

        default boolean isDisabled()
        Returns whether the element is disabled, the opposite of enabled.

        NOTE: If you need to assert that an element is disabled, prefer LocatorAssertions.isDisabled() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 boolean disabled = page.getByRole(AriaRole.BUTTON).isDisabled();
        Since:
        v1.14

      • isEditable

        default boolean isEditable()
        Returns whether the element is editable.

        NOTE: If you need to assert that an element is editable, prefer LocatorAssertions.isEditable() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 boolean editable = page.getByRole(AriaRole.TEXTBOX).isEditable();
        Since:
        v1.14

      • isEnabled

        default boolean isEnabled()
        Returns whether the element is enabled.

        NOTE: If you need to assert that an element is enabled, prefer LocatorAssertions.isEnabled() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 boolean enabled = page.getByRole(AriaRole.BUTTON).isEnabled();
        Since:
        v1.14

      • isHidden

        default boolean isHidden()
        Returns whether the element is hidden, the opposite of visible.

        NOTE: If you need to assert that element is hidden, prefer LocatorAssertions.isHidden() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 boolean hidden = page.getByRole(AriaRole.BUTTON).isHidden();
        Since:
        v1.14

      • isVisible

        default boolean isVisible()
        Returns whether the element is visible.

        NOTE: If you need to assert that element is visible, prefer LocatorAssertions.isVisible() to avoid flakiness. See assertions guide for more details.

        Usage 

        
 boolean visible = page.getByRole(AriaRole.BUTTON).isVisible();
        Since:
        v1.14

      • last

        Locator last()
        Returns locator to the last matching element.

        Usage 

        
 Locator banana = page.getByRole(AriaRole.LISTITEM).last();
        Since:
        v1.14

      • 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.14

      • 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.14

      • nth

        Locator nth​(int index)
        Returns locator to the n-th matching element. It's zero based, nth(0) selects the first element.

        Usage 

        
 Locator banana = page.getByRole(AriaRole.LISTITEM).nth(2);
        Since:
        v1.14

      • or

        Locator or​(Locator locator)
        Creates a locator that matches either of the two locators.

        Usage

        Consider a scenario where you'd like to click on a "New email" button, but sometimes a security settings dialog shows up instead. In this case, you can wait for either a "New email" button, or a dialog and act accordingly. 

        
 Locator newEmail = page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("New"));
 Locator dialog = page.getByText("Confirm security settings");
 assertThat(newEmail.or(dialog)).isVisible();
 if (dialog.isVisible())
   page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Dismiss")).click();
 newEmail.click();
        Parameters:
        locator - Alternative locator to match.
        Since:
        v1.33

      • page

        Page page()
        A page this locator belongs to.
        Since:
        v1.19

      • press

        default void press​(String key)
        Focuses the matching element and presses a combination of the keys.

        Usage 

        
 page.getByRole(AriaRole.TEXTBOX).press("Backspace");

        Details

        Focuses the element, and then uses Keyboard.down() and Keyboard.up().

        key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found here. Examples of the keys are:

        F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

        Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. ControlOrMeta resolves to Control on Windows and Linux and to Meta on macOS.

        Holding down Shift will type the text that corresponds to the key in the upper case.

        If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

        Shortcuts such as key: "Control+o", key: "Control++ or key: "Control+Shift+T" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

        Parameters:
        key - Name of the key to press or a character to generate, such as ArrowLeft or a.
        Since:
        v1.14

      • press

        void press​(String key,
           Locator.PressOptions options)
        Focuses the matching element and presses a combination of the keys.

        Usage 

        
 page.getByRole(AriaRole.TEXTBOX).press("Backspace");

        Details

        Focuses the element, and then uses Keyboard.down() and Keyboard.up().

        key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found here. Examples of the keys are:

        F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

        Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft, ControlOrMeta. ControlOrMeta resolves to Control on Windows and Linux and to Meta on macOS.

        Holding down Shift will type the text that corresponds to the key in the upper case.

        If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

        Shortcuts such as key: "Control+o", key: "Control++ or key: "Control+Shift+T" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

        Parameters:
        key - Name of the key to press or a character to generate, such as ArrowLeft or a.
        Since:
        v1.14

      • pressSequentially

        default void pressSequentially​(String text)
        NOTE: In most cases, you should use Locator.fill() instead. You only need to press keys one by one if there is special keyboard handling on the page.

        Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.

        To press a special key, like Control or ArrowDown, use Locator.press().

        Usage 

        
 locator.pressSequentially("Hello"); // Types instantly
 locator.pressSequentially("World", new Locator.pressSequentiallyOptions().setDelay(100)); // Types slower, like a user

        An example of typing into a text field and then submitting the form: 

        
 Locator locator = page.getByLabel("Password");
 locator.pressSequentially("my password");
 locator.press("Enter");
        Parameters:
        text - String of characters to sequentially press into a focused element.
        Since:
        v1.38

      • pressSequentially

        void pressSequentially​(String text,
                       Locator.PressSequentiallyOptions options)
        NOTE: In most cases, you should use Locator.fill() instead. You only need to press keys one by one if there is special keyboard handling on the page.

        Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.

        To press a special key, like Control or ArrowDown, use Locator.press().

        Usage 

        
 locator.pressSequentially("Hello"); // Types instantly
 locator.pressSequentially("World", new Locator.pressSequentiallyOptions().setDelay(100)); // Types slower, like a user

        An example of typing into a text field and then submitting the form: 

        
 Locator locator = page.getByLabel("Password");
 locator.pressSequentially("my password");
 locator.press("Enter");
        Parameters:
        text - String of characters to sequentially press into a focused element.
        Since:
        v1.38

      • screenshot

        default byte[] screenshot()
        Take a screenshot of the element matching the locator.

        Usage 

        
 page.getByRole(AriaRole.LINK).screenshot();

        Disable animations and save screenshot to a file: 

        
 page.getByRole(AriaRole.LINK).screenshot(new Locator.ScreenshotOptions()
     .setAnimations(ScreenshotAnimations.DISABLED)
     .setPath(Paths.get("example.png")));

        Details

        This method captures a screenshot of the page, clipped to the size and position of a particular element matching the locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the screenshot.

        This method waits for the actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, the method throws an error.

        Returns the buffer with the captured screenshot.

        Since:
        v1.14

      • screenshot

        byte[] screenshot​(Locator.ScreenshotOptions options)
        Take a screenshot of the element matching the locator.

        Usage 

        
 page.getByRole(AriaRole.LINK).screenshot();

        Disable animations and save screenshot to a file: 

        
 page.getByRole(AriaRole.LINK).screenshot(new Locator.ScreenshotOptions()
     .setAnimations(ScreenshotAnimations.DISABLED)
     .setPath(Paths.get("example.png")));

        Details

        This method captures a screenshot of the page, clipped to the size and position of a particular element matching the locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the screenshot.

        This method waits for the actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, the method throws an error.

        Returns the buffer with the captured screenshot.

        Since:
        v1.14

      • scrollIntoViewIfNeeded

        default void scrollIntoViewIfNeeded()
        This method waits for actionability checks, then tries to scroll element into view, unless it is completely visible as defined by IntersectionObserver's ratio.
        Since:
        v1.14

      • selectOption

        default List<String> selectOption​(String values)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        List<String> selectOption​(String values,
                          Locator.SelectOptionOptions options)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        default List<String> selectOption​(ElementHandle values)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        List<String> selectOption​(ElementHandle values,
                          Locator.SelectOptionOptions options)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        default List<String> selectOption​(String[] values)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        List<String> selectOption​(String[] values,
                          Locator.SelectOptionOptions options)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        default List<String> selectOption​(SelectOption values)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        List<String> selectOption​(SelectOption values,
                          Locator.SelectOptionOptions options)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        default List<String> selectOption​(ElementHandle[] values)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        List<String> selectOption​(ElementHandle[] values,
                          Locator.SelectOptionOptions options)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        default List<String> selectOption​(SelectOption[] values)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectOption

        List<String> selectOption​(SelectOption[] values,
                          Locator.SelectOptionOptions options)
        Selects option or options in <select>.

        Details

        This method waits for actionability checks, waits until all specified options are present in the <select> element and selects these options.

        If the target element is not a <select> element, this method throws an error. However, if the element is inside the <label> element that has an associated control, the control will be used instead.

        Returns the array of option values that have been successfully selected.

        Triggers a change and input event once all the provided options have been selected.

        Usage 

        
 // single selection matching the value or label
 element.selectOption("blue");
 // single selection matching the label
 element.selectOption(new SelectOption().setLabel("Blue"));
 // multiple selection for blue, red and second option
 element.selectOption(new String[] {"red", "green", "blue"});
        Parameters:
        values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. String values are matching both values and labels. Option is considered matching if all specified properties match.
        Since:
        v1.14

      • selectText

        default void selectText()
        This method waits for actionability checks, then focuses the element and selects all its text content.

        If the element is inside the <label> element that has an associated control, focuses and selects text in the control instead.

        Since:
        v1.14

      • selectText

        void selectText​(Locator.SelectTextOptions options)
        This method waits for actionability checks, then focuses the element and selects all its text content.

        If the element is inside the <label> element that has an associated control, focuses and selects text in the control instead.

        Since:
        v1.14

      • setChecked

        default void setChecked​(boolean checked)
        Set the state of a checkbox or a radio element.

        Usage 

        
 page.getByRole(AriaRole.CHECKBOX).setChecked(true);

        Details

        This method checks or unchecks an element by performing the following steps:

        1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
        2. If the element already has the right checked state, this method returns immediately.
        3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
        4. Scroll the element into view if needed.
        5. Use Page.mouse() to click in the center of the element.
        6. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
        7. Ensure that the element is now checked or unchecked. If not, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Parameters:
        checked - Whether to check or uncheck the checkbox.
        Since:
        v1.15

      • setChecked

        void setChecked​(boolean checked,
                Locator.SetCheckedOptions options)
        Set the state of a checkbox or a radio element.

        Usage 

        
 page.getByRole(AriaRole.CHECKBOX).setChecked(true);

        Details

        This method checks or unchecks an element by performing the following steps:

        1. Ensure that matched element is a checkbox or a radio input. If not, this method throws.
        2. If the element already has the right checked state, this method returns immediately.
        3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
        4. Scroll the element into view if needed.
        5. Use Page.mouse() to click in the center of the element.
        6. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
        7. Ensure that the element is now checked or unchecked. If not, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Parameters:
        checked - Whether to check or uncheck the checkbox.
        Since:
        v1.15

      • setInputFiles

        default void setInputFiles​(Path files)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • setInputFiles

        void setInputFiles​(Path files,
                   Locator.SetInputFilesOptions options)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • setInputFiles

        default void setInputFiles​(Path[] files)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • setInputFiles

        void setInputFiles​(Path[] files,
                   Locator.SetInputFilesOptions options)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • setInputFiles

        default void setInputFiles​(FilePayload files)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • setInputFiles

        void setInputFiles​(FilePayload files,
                   Locator.SetInputFilesOptions options)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • setInputFiles

        default void setInputFiles​(FilePayload[] files)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • setInputFiles

        void setInputFiles​(FilePayload[] files,
                   Locator.SetInputFilesOptions options)
        Upload file or multiple files into <input type=file>.

        Usage 

        
 // Select one file
 page.getByLabel("Upload file").setInputFiles(Paths.get("myfile.pdf"));

 // Select multiple files
 page.getByLabel("Upload files").setInputFiles(new Path[] {Paths.get("file1.txt"), Paths.get("file2.txt")});

 // Remove all the selected files
 page.getByLabel("Upload file").setInputFiles(new Path[0]);

 // Upload buffer from memory
 page.getByLabel("Upload file").setInputFiles(new FilePayload(
   "file.txt", "text/plain", "this is test".getBytes(StandardCharsets.UTF_8)));

        Details

        Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they are resolved relative to the current working directory. For empty array, clears the selected files.

        This method expects Locator to point to an input element. However, if the element is inside the <label> element that has an associated control, targets the control instead.

        Since:
        v1.14

      • tap

        default void tap()
        Perform a tap gesture on the element matching the locator.

        Details

        This method taps the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.touchscreen() to tap the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        NOTE: element.tap() requires that the hasTouch option of the browser context be set to true.

        Since:
        v1.14

      • tap

        void tap​(Locator.TapOptions options)
        Perform a tap gesture on the element matching the locator.

        Details

        This method taps the element by performing the following steps:

        1. Wait for actionability checks on the element, unless force option is set.
        2. Scroll the element into view if needed.
        3. Use Page.touchscreen() to tap the center of the element, or the specified position.
        4. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        NOTE: element.tap() requires that the hasTouch option of the browser context be set to true.

        Since:
        v1.14

      • type

        default void type​(String text)
        Deprecated.
        In most cases, you should use Locator.fill() instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use Locator.pressSequentially().
        Parameters:
        text - A text to type into a focused element.
        Since:
        v1.14

      • type

        void type​(String text,
          Locator.TypeOptions options)
        Deprecated.
        In most cases, you should use Locator.fill() instead. You only need to press keys one by one if there is special keyboard handling on the page - in this case use Locator.pressSequentially().
        Parameters:
        text - A text to type into a focused element.
        Since:
        v1.14

      • uncheck

        default void uncheck()
        Ensure that checkbox or radio element is unchecked.

        Usage 

        
 page.getByRole(AriaRole.CHECKBOX).uncheck();

        Details

        This method unchecks the element by performing the following steps:

        1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already unchecked, this method returns immediately.
        2. Wait for actionability checks on the element, unless force option is set.
        3. Scroll the element into view if needed.
        4. Use Page.mouse() to click in the center of the element.
        5. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
        6. Ensure that the element is now unchecked. If not, this method throws.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Since:
        v1.14

      • uncheck

        void uncheck​(Locator.UncheckOptions options)
        Ensure that checkbox or radio element is unchecked.

        Usage 

        
 page.getByRole(AriaRole.CHECKBOX).uncheck();

        Details

        This method unchecks the element by performing the following steps:

        1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already unchecked, this method returns immediately.
        2. Wait for actionability checks on the element, unless force option is set.
        3. Scroll the element into view if needed.
        4. Use Page.mouse() to click in the center of the element.
        5. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
        6. Ensure that the element is now unchecked. If not, this method throws.

        If the element is detached from the DOM at any moment during the action, this method throws.

        When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

        Since:
        v1.14

      • waitFor

        default void waitFor()
        Returns when element specified by locator satisfies the state option.

        If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to timeout milliseconds until the condition is met.

        Usage 

        
 Locator orderSent = page.locator("#order-sent");
 orderSent.waitFor();
        Since:
        v1.16

      • waitFor

        void waitFor​(Locator.WaitForOptions options)
        Returns when element specified by locator satisfies the state option.

        If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to timeout milliseconds until the condition is met.

        Usage 

        
 Locator orderSent = page.locator("#order-sent");
 orderSent.waitFor();
        Since:
        v1.16