🔒 EXCLUSIVE: Docs/api/class locator - Collection

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="/">Home</a></li>
  <li><a href="/about">About</a></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 <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.

click​

Added in: v1.14 locator.click

Click an element.

Usage

Click a button:

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

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

await page.locator('canvas').click({
  button: 'right',
  modifiers: ['Shift'],
  position: { x: 23, y: 32 },
});

Arguments

  • options Object (optional)

    • button "left" | "right" | "middle" (optional)#

      Defaults to left.

    • clickCount number (optional)#

      defaults to 1. See UIEvent.detail.

    • delay number (optional)#

      Time to wait between mousedown and mouseup in milliseconds. Defaults to 0.

    • force boolean (optional)#

      Whether to bypass the actionability checks. Defaults to false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (optional)#

      Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to "Control" on Windows and Linux and to "Meta" on macOS.

    • noWaitAfter boolean (optional)#

      Deprecated

      This option will default to true in the future.

      Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to inaccessible pages. Defaults to false.

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

    • steps number (optional) Added in: v1.57#

      Defaults to 1. Sends n interpolated mousemove events to represent travel between Playwright's current cursor position and the provided destination. When set to 1, emits a single mousemove event at the destination location.

    • 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. Note that keyboard modifiers will be pressed regardless of trial to allow testing elements which are only visible when those keys are pressed.

Returns

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.

contentFrame​

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

const locator = page.locator('iframe[name="embedded"]');
// ...
const frameLocator = locator.contentFrame();
await frameLocator.getByRole('button').click();

Returns

count​

Added in: v1.14 locator.count

Returns the number of elements matching the locator.

Asserting count

If you need to assert the number of elements on the page, prefer expect(locator).toHaveCount() to avoid flakiness. See assertions guide for more details.

Usage

const count = await page.getByRole('listitem').count();

Returns

dblclick​

Added in: v1.14 locator.dblclick

Double-click an element.

Usage

await locator.dblclick();
await locator.dblclick(options);

Arguments

  • options Object (optional)

    • button "left" | "right" | "middle" (optional)#

      Defaults to left.

    • delay number (optional)#

      Time to wait between mousedown and mouseup in milliseconds. Defaults to 0.

    • force boolean (optional)#

      Whether to bypass the actionability checks. Defaults to false.

    • modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (optional)#

      Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used. "ControlOrMeta" resolves to "Control" on Windows and Linux and to "Meta" on macOS.

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

    • steps number (optional) Added in: v1.57#

      Defaults to 1. Sends n interpolated mousemove events to represent travel between Playwright's current cursor position and the provided destination. When set to 1, emits a single mousemove event at the destination location.

    • 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. Note that keyboard modifiers will be pressed regardless of trial to allow testing elements which are only visible when those keys are pressed.

Returns