puppeteer/website/versioned_docs/version-21.0.2/guides/locators.md

Locators

Locators is a new, experimental API that combines the functionalities of waiting and actions. With additional precondition checks, it enables automatic retries for failed actions, resulting in more reliable and less flaky automation scripts.

:::note

Locators API is experimental and we will not follow semver for breaking changes in the Locators API.

:::

Use cases

Waiting for an element

await page.locator('button').wait();

The following preconditions are automatically checked:

• Waits for the element to become visible or hidden.

Waiting for a function

await page
  .locator(() => {
    let resolve!: (node: HTMLCanvasElement) => void;
    const promise = new Promise(res => {
      return (resolve = res);
    });
    const observer = new MutationObserver(records => {
      for (const record of records) {
        if (record.target instanceof HTMLCanvasElement) {
          resolve(record.target);
        }
      }
    });
    observer.observe(document);
    return promise;
  })
  .wait();

Clicking an element

await page.locator('button').click();

The following preconditions are automatically checked:

• Ensures the element is in the viewport.
• Waits for the element to become visible or hidden.
• Waits for the element to become enabled.
• Waits for the element to have a stable bounding box over two consecutive animation frames.

Clicking an element matching a criteria

await page
  .locator('button')
  .filter(button => !button.disabled)
  .click();

The following preconditions are automatically checked:

• Ensures the element is in the viewport.
• Waits for the element to become visible or hidden.
• Waits for the element to become enabled.
• Waits for the element to have a stable bounding box over two consecutive animation frames.

Filling out an input

await page.locator('input').fill('value');

Automatically detects the input type and choose an approritate way to fill it out with the provided value.

The following preconditions are automatically checked:

• Ensures the element is in the viewport.
• Waits for the element to become visible or hidden.
• Waits for the element to become enabled.
• Waits for the element to have a stable bounding box over two consecutive animation frames.

Retrieving an element property

const enabled = await page
  .locator('button')
  .map(button => !button.disabled)
  .wait();

Hover over an element

await page.locator('div').hover();

The following preconditions are automatically checked:

• Ensures the element is in the viewport.
• Waits for the element to become visible or hidden.
• Waits for the element to have a stable bounding box over two consecutive animation frames.

Scroll an element

await page.locator('div').scroll({
  scrollLeft: 10,
  scrollTop: 20,
});

The following preconditions are automatically checked:

• Ensures the element is in the viewport.
• Waits for the element to become visible or hidden.
• Waits for the element to have a stable bounding box over two consecutive animation frames.

Configuring locators

Locators can be configured to tune configure the preconditions and other other options:

await page
  .locator('button')
  .setEnsureElementIsInTheViewport(false)
  .setTimeout(0)
  .setVisibility(null)
  .setWaitForEnabled(false)
  .setWaitForStableBoundingBox(false)
  .click();

Getting locator events

Currently, locators support a single event that notifies you when the locator is about to perform the action:

let willClick = false;
await page
  .locator('button')
  .on(LocatorEmittedEvents.Action, () => {
    willClick = true;
  })
  .click();

This event can be used for logging/debugging or other purposes. The event might fire multiple times if the locator retries the action.