Skip to main content

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.

Methods​

all​

Added in: v1.29 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 li in page.get_by_role('listitem').all():
  li.click();

Returns

all_inner_texts​

Added in: v1.14 locator.all_inner_texts

Returns an array of node.innerText values for all matching nodes.

Asserting text

If you need to assert text on the page, prefer expect(locator).to_have_text() with use_inner_text option to avoid flakiness. See assertions guide for more details.

Usage

texts = page.get_by_role("link").all_inner_texts()

Returns

all_text_contents​

Added in: v1.14 locator.all_text_contents

Returns an array of node.textContent values for all matching nodes.

Asserting text

If you need to assert text on the page, prefer expect(locator).to_have_text() to avoid flakiness. See assertions guide for more details.

Usage

texts = page.get_by_role("link").all_text_contents()

Returns

and_​

Added in: v1.34 locator.and_

Creates a locator that matches both this locator and the argument locator.

Usage

The following example finds a button with a specific title.

button = page.get_by_role("button").and_(page.getByTitle("Subscribe"))

Arguments

  • locator Locator#

    Additional locator to match.

Returns

aria_snapshot​

Added in: v1.49 locator.aria_snapshot

Captures the aria snapshot of the given element. Read more about aria snapshots and expect(locator).to_match_aria_snapshot() for the corresponding assertion.

Usage

page.get_by_role("link").aria_snapshot()

Arguments

Returns

Details

This method captures the aria snapshot of the given element. The snapshot is a string that represents the state of the element and its children. The snapshot can be used to assert the state of the element in the test, or to compare it to state in the future.

The ARIA snapshot is represented using YAML markup language:

  • The keys of the objects are the roles and optional accessible names of the elements.
  • The values are either text content or an array of child elements.
  • Generic static text can be represented with the text key.

Below is the HTML markup and the respective ARIA snapshot:

<ul aria-label="Links">
  <li><a href="/">Homea>li>
  <li><a href="/about">Abouta>li>
<ul>
- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

blur​

Added in: v1.28 locator.blur

Calls blur on the element.

Usage

locator.blur()
locator.blur(**kwargs)

Arguments

Returns

bounding_box​

Added in: v1.14 locator.bounding_box

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.

Usage

box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

Arguments

Returns

  • NoneType | Dict#

    • x float

      the x coordinate of the element in pixels.

    • y float

      the y coordinate of the element in pixels.

    • width float

      the width of the element in pixels.

    • height float

      the height of the element in pixels.

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.

check​

Added in: v1.14 locator.check

Ensure that checkbox or radio element is checked.

Usage

page.get_by_role("checkbox").check()

Arguments

  • force bool (optional)#

    Whether to bypass the actionability checks. Defaults to false.

  • no_wait_after bool (optional)#

    Deprecated

    This option has no effect.

    This option has no effect.

  • position Dict (optional)#

    A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.

  • timeout float (optional)#

    Maximum time in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout. The default value can be changed by using the browser_context.set_default_timeout() or page.set_default_timeout() methods.

  • trial bool (optional)#

    When set, this method only performs the actionability checks and skips the action. Defaults to false. Useful to wait until the element is ready for the action without performing it.

Returns

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

clear​

Added in: v1.28 locator.clear

Clear the input field.

Usage

page.get_by_role("textbox").clear()

Arguments

Returns

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 ,