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 (const li of await page.getByRole('listitem').all())
  await li.click();

Returns

allInnerTexts​

Added in: v1.14 locator.allInnerTexts

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).toHaveText() with useInnerText option to avoid flakiness. See assertions guide for more details.

Usage

const texts = await page.getByRole('link').allInnerTexts();

Returns

allTextContents​

Added in: v1.14 locator.allTextContents

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).toHaveText() to avoid flakiness. See assertions guide for more details.

Usage

const texts = await page.getByRole('link').allTextContents();

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.

const button = page.getByRole('button').and(page.getByTitle('Subscribe'));

Arguments

  • locator Locator#

    Additional locator to match.

Returns

ariaSnapshot​

Added in: v1.49 locator.ariaSnapshot

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

Usage

await page.getByRole('link').ariaSnapshot();

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

await locator.blur();
await locator.blur(options);

Arguments

Returns

boundingBox​

Added in: v1.14 locator.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.

Usage

const box = await page.getByRole('button').boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);

Arguments

Returns

  • Promise<null | Object>#

    • x number

      the x coordinate of the element in pixels.

    • y number

      the y coordinate of the element in pixels.

    • width number

      the width of the element in pixels.

    • height number

      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

await page.getByRole('checkbox').check();

Arguments

  • options Object (optional)

    • force boolean (optional)#

      Whether to bypass the actionability checks. Defaults to false.

    • noWaitAfter boolean (optional)#

      Deprecated

      This option has no effect.

      This option has no effect.

    • position Object (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 number (optional)#

      Maximum time in milliseconds. Defaults to 0 - no timeout. The default value can be changed via actionTimeout option in the config, or by using the browserContext.setDefaultTimeout() or page.setDefaultTimeout() methods.

    • trial boolean (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

await page.getByRole('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 ,