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

Locators

Locators is a new experimental API that combines waitForSelector and element actions in a single unit. In combination with additional precondition checks this allows locators to retry failed actions automatically leading to less flaky automation scripts.

:::note

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

:::

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.

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.

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.