Interface Locator<S>

Description

Libra Locator

Locator

interface Locator<S> {
    click: ((options?: {
        button?: "left" | "right" | "middle";
        clickCount?: number;
        delay?: number;
        force?: boolean;
        modifiers?: (
            | "Alt"
            | "Control"
            | "Meta"
            | "Shift")[];
        noWaitAfter?: boolean;
        position?: {
            x: number;
            y: number;
        };
        timeout?: number;
        trial?: boolean;
    }) => Promise<void>);
    filter: ((options: LibraLocatorOptions) => Locator<string>);
    getByLabel: getByLabel;
    getByTestId: getByTestId;
    getByText: getByText;
    isDisabled: (() => Promise<boolean>);
    isEnabled: (() => Promise<boolean>);
    isHidden: (() => Promise<boolean>);
    isVisible: (() => Promise<boolean>);
    nth: ((index: number) => Locator<string>);
    press: ((key: string, options?: {
        timeout?: number;
    }) => Promise<void>);
    waitFor: ((options?: {
        state?:
            | "attached"
            | "detached"
            | "visible"
            | "hidden";
        timeout?: number;
    }) => Promise<void>);
    allInnerTexts(): Promise<string[]>;
    boundingBox(options?: {
        timeout?: number;
    }): Promise<null | {
        height: number;
        width: number;
        x: number;
        y: number;
    }>;
    captureImage(options: captureImageOptions): Promise<Buffer>;
    check(options?: {
        timeout?: number;
    }): Promise<void>;
    count(): Promise<number>;
    dispatchEvent(type: string, eventInit?: object, options?: {
        timeout?: number;
    }): Promise<void>;
    dragTo(target: Locator<string>, options?: {
        sourcePosition?: {
            x: number;
            y: number;
        };
        targetPosition?: {
            x: number;
            y: number;
        };
        timeout?: number;
    }): Promise<void>;
    focus(options?: {
        timeout?: number;
    }): Promise<void>;
    getByRole(role: ByRole, options?: ByRoleOptions): Locator<string>;
    inputValue(options?: {
        timeout?: number;
    }): Promise<string>;
    isChecked(options?: {
        timeout?: number;
    }): Promise<boolean>;
    isEditable(options?: {
        timeout?: number;
    }): Promise<boolean>;
    or(locator: Locator<string>): Locator<string>;
    screenshot(options?: {
        mask?: Locator<string>[];
        maskColor?: string;
        omitBackground?: boolean;
        path?: string;
        quality?: number;
        timeout?: number;
        type?: "png" | "jpeg";
    }): Promise<Buffer>;
    uncheck(options?: {
        timeout?: number;
    }): Promise<void>;
}

Type Parameters

  • S = string

Properties

click filter getByLabel getByTestId getByText isDisabled isEnabled isHidden isVisible nth press waitFor

Methods

allInnerTexts boundingBox captureImage check count dispatchEvent dragTo focus getByRole inputValue isChecked isEditable or screenshot uncheck

Properties

click

click: ((options?: {
    button?: "left" | "right" | "middle";
    clickCount?: number;
    delay?: number;
    force?: boolean;
    modifiers?: (
        | "Alt"
        | "Control"
        | "Meta"
        | "Shift")[];
    noWaitAfter?: boolean;
    position?: {
        x: number;
        y: number;
    };
    timeout?: number;
    trial?: boolean;
}) => Promise<void>)

Click an element.

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.

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 },
});

filter

filter: ((options: LibraLocatorOptions) => Locator<string>)

This method narrows existing locator according to the options, for example filters by text. It can be chained to filter multiple times.

Usage

const rowLocator = page.locator('tr');
// ...
await rowLocator
    .filter({ hasText: 'text in column 1' })
    .filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
    .screenshot();

getByLabel

getByLabel: getByLabel

See

getByLabel

getByTestId

getByTestId: getByTestId

See

getByLabel

getByText

getByText: getByText

See

getByText

isDisabled

isDisabled: (() => Promise<boolean>)

Returns whether the element is disabled, the opposite of enabled.

NOTE If you need to assert that an element is disabled, prefer expect(locator).toBeDisabled([options]) to avoid flakiness. See assertions guide for more details.

Usage

const disabled = await page.getByRole('button').isDisabled();

isEnabled

isEnabled: (() => Promise<boolean>)

Returns whether the element is enabled.

NOTE If you need to assert that an element is enabled, prefer expect(locator).toBeEnabled([options]) to avoid flakiness. See assertions guide for more details.

Usage

const enabled = await page.getByRole('button').isEnabled();

isHidden

isHidden: (() => Promise<boolean>)

Returns whether the element is hidden, the opposite of visible.

NOTE If you need to assert that element is hidden, prefer expect(locator).toBeHidden([options]) to avoid flakiness. See assertions guide for more details.

Usage

const hidden = await page.getByRole('button').isHidden();

isVisible

isVisible: (() => Promise<boolean>)

Returns whether the element is visible.

NOTE If you need to assert that element is visible, prefer expect(locator).toBeVisible([options]) to avoid flakiness. See assertions guide for more details.

Usage

const visible = await page.getByRole('button').isVisible();

nth

nth: ((index: number) => Locator<string>)

Returns locator to the n-th matching element. It's zero based, nth(0) selects the first element.

Usage

const banana = await page.getByRole('listitem').nth(2);

press

press: ((key: string, options?: {
    timeout?: number;
}) => Promise<void>)

Focuses the matching element and presses a combination of the keys. Not support Control + currently, we can implement it later Usage

await page.getByRole('textbox').press('Backspace');

Details

Focuses the element, and then uses keyboard.down(key) and keyboard.up(key).

key can specify the intended keyboardEvent.key value or a single character to generate the text for. A superset of the key values can be found here. Examples of the keys are:

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.

Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft.

Holding down Shift will type the text that corresponds to the key in the upper case.

If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

Shortcuts such as key: "Control+o" or key: "Control+Shift+T" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

Type declaration

    • (key, options?): Promise<void>

    • Parameters

      • key: string

        Name of the key to press or a character to generate, such as ArrowLeft or a.

      • Optionaloptions: {
            timeout?: number;
        }
        • Optionaltimeout?: number

      Returns Promise<void>

waitFor

waitFor: ((options?: {
    state?:
        | "attached"
        | "detached"
        | "visible"
        | "hidden";
    timeout?: number;
}) => Promise<void>)

Returns when element specified by locator satisfies the state option.

If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to timeout milliseconds until the condition is met.

Usage

const orderSent = page.locator('#order-sent');
await orderSent.waitFor();

Methods

allInnerTexts

  • allInnerTexts(): Promise<string[]>

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

    NOTE If you need to assert text on the page, prefer expect(locator).toHaveText(expected[, options]) with useInnerText option to avoid flakiness. See assertions guide for more details.

    Usage

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

    Returns Promise<string[]>

boundingBox

  • boundingBox(options?): Promise<null | {
        height: number;
        width: number;
        x: number;
        y: number;
    }>

  • This method returns the bounding box of the element, 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.

    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.

    Usage

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

    Parameters

    • Optionaloptions: {
          timeout?: number;
      }
      • Optionaltimeout?: number

    Returns Promise<null | {
        height: number;
        width: number;
        x: number;
        y: number;
    }>

captureImage

  • captureImage(options): Promise<Buffer>

  • Captures a screenshot of the element and saves it to a file.

    NOTE if path not specific, it will not save to disk.

    NOTE it run javascript to capture the image.

    canvas | video is required if canvas is specific(canvas locator to ), it will capture the canvas with the locator region, if video(

    Parameters

    • options: captureImageOptions

    Returns Promise<Buffer>

check

  • check(options?): Promise<void>

  • NOTE Use locator-based locator.check([options]) instead. Read more about locators. make sure the target is a checkbox or radio

    This method checks an element matching selector by performing the following steps:

    1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
    2. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
    3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
    4. Scroll the element into view if needed.
    5. Use page.mouse to click in the center of the element.
    6. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
    7. Ensure that the element is now checked. If not, this method throws.

    When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

    Parameters

    • Optionaloptions: {
          timeout?: number;
      }
      • Optionaltimeout?: number

    Returns Promise<void>

count

  • count(): Promise<number>

  • Returns the number of elements matching the locator.

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

    Usage

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

    Returns Promise<number>

dispatchEvent

  • dispatchEvent(type, eventInit?, options?): Promise<void>

  • Programmatically dispatch an event on the matching element.

    Usage

    await locator.dispatchEvent('click');

    Details

    The snippet above dispatches the click event on the element. Regardless of the visibility state of the element, click is dispatched. This is equivalent to calling element.click().

    Under the hood, it creates an instance of an event based on the given type, initializes it with eventInit properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

    Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:

    You can also specify JSHandle as the property value if you want live objects to be passed into the event:

    // Note you can only create DataTransfer in Chromium and Firefox
    const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
    await locator.dispatchEvent('dragstart', { dataTransfer });

    Parameters

    • type: string

      DOM event type: "click", "dragstart", etc.

    • OptionaleventInit: object

      Optional event-specific initialization properties.

    • Optionaloptions: {
          timeout?: number;
      }

    Returns Promise<void>

dragTo

  • dragTo(target, options?): Promise<void>

  • Drag the source element towards the target element and drop it.

    Details

    This method drags the locator to another target locator or target position. It will first move to the source element, perform a mousedown, then move to the target element or position and perform a mouseup.

    Usage

    const source = page.locator('#source');
    const target = page.locator('#target');

    await source.dragTo(target);
    // or specify exact positions relative to the top-left corners of the elements:
    await source.dragTo(target, {
      sourcePosition: { x: 34, y: 7 },
      targetPosition: { x: 10, y: 20 },
    });

    Parameters

    • target: Locator<string>

      Locator of the element to drag to.

    • Optionaloptions: {
          sourcePosition?: {
              x: number;
              y: number;
          };
          targetPosition?: {
              x: number;
              y: number;
          };
          timeout?: number;
      }
      • OptionalsourcePosition?: {
            x: number;
            y: number;
        }

        Clicks on the source element at this point relative to the top-left corner of the element's padding box. If not specified, some visible point of the element is used.

        • x: number
        • y: number
      • OptionaltargetPosition?: {
            x: number;
            y: number;
        }

        Drops on the target element at this point relative to the top-left corner of the element's padding box. If not specified, some visible point of the element is used.

        • x: number
        • y: number
      • Optionaltimeout?: number

        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(timeout) or page.setDefaultTimeout(timeout) methods.

    Returns Promise<void>

focus

  • focus(options?): Promise<void>

  • NOTE Use locator-based locator.focus([options]) instead. Read more about locators.

    This method fetches an element with selector and focuses it. If there's no element matching selector, the method waits until a matching element appears in the DOM.

    Parameters

    • Optionaloptions: {
          timeout?: number;
      }
      • Optionaltimeout?: number

    Returns Promise<void>

getByRole

inputValue

  • inputValue(options?): Promise<string>

  • Returns the value for the matching <input> or <textarea> or <select> element.

    NOTE If you need to assert input value, prefer expect(locator).toHaveValue(value[, options]) to avoid flakiness. See assertions guide for more details.

    Usage

    const value = await page.getByRole('textbox').inputValue();

    Details

    Throws elements that are not an input, textarea or a select. However, if the element is inside the <label> element that has an associated control, returns the value of the control.

    Parameters

    • Optionaloptions: {
          timeout?: number;
      }
      • Optionaltimeout?: number

    Returns Promise<string>

isChecked

  • isChecked(options?): Promise<boolean>

  • Returns whether the element is checked. Throws if the element is not a checkbox or radio input.

    NOTE If you need to assert that checkbox is checked, prefer expect(locator).toBeChecked([options]) to avoid flakiness. See assertions guide for more details.

    Usage

    const checked = await page.getByRole('checkbox').isChecked();

    Parameters

    Returns Promise<boolean>

isEditable

or

  • or(locator): Locator<string>

  • Creates a locator that matches either of the two locators.

    Usage

    Consider a scenario where you'd like to click on a "New email" button, but sometimes a security settings dialog shows up instead. In this case, you can wait for either a "New email" button, or a dialog and act accordingly.

    const newEmail = page.getByRole('button', { name: 'New' });
    const dialog = page.getByText('Confirm security settings');
    await expect(newEmail.or(dialog)).toBeVisible();
    if (await dialog.isVisible())
      await page.getByRole('button', { name: 'Dismiss' }).click();
    await newEmail.click();

    Parameters

    • locator: Locator<string>

      Alternative locator to match.

    Returns Locator<string>

screenshot

  • screenshot(options?): Promise<Buffer>

  • This method captures a screenshot of the page, clipped to the size and position of this particular element. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the screenshot.

    This method waits for the actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, the method throws an error.

    Returns the buffer with the captured screenshot.

    Parameters

    • Optionaloptions: {
          mask?: Locator<string>[];
          maskColor?: string;
          omitBackground?: boolean;
          path?: string;
          quality?: number;
          timeout?: number;
          type?: "png" | "jpeg";
      }
      • Optionalmask?: Locator<string>[]

        Specify locators that should be masked when the screenshot is taken. Masked elements will be overlaid with a pink box #FF00FF (customized by maskColor) that completely covers its bounding box.

      • OptionalmaskColor?: string

        Specify the color of the overlay box for masked elements, in CSS color format. Default color is pink #FF00FF.

      • OptionalomitBackground?: boolean

        Hides default white background and allows capturing screenshots with transparency. Not applicable to jpeg images. Defaults to false.

      • Optionalpath?: string

        The file path to save the image to. The screenshot type will be inferred from file extension. If path is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk.

      • Optionalquality?: number

        The quality of the image, between 0-100. Not applicable to png images.

      • Optionaltimeout?: number

        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(timeout) or page.setDefaultTimeout(timeout) methods.

      • Optionaltype?: "png" | "jpeg"

        Specify screenshot type, defaults to png.

    Returns Promise<Buffer>

uncheck

  • uncheck(options?): Promise<void>

  • NOTE Use locator-based locator.uncheck([options]) instead. Read more about locators. make sure the target is a checkbox or radio

    This method unchecks an element matching selector by performing the following steps:

    1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
    2. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already unchecked, this method returns immediately.
    3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
    4. Scroll the element into view if needed.
    5. Use page.mouse to click in the center of the element.
    6. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
    7. Ensure that the element is now unchecked. If not, this method throws.

    When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

    Parameters

    • Optionaloptions: {
          timeout?: number;
      }
      • Optionaltimeout?: number

    Returns Promise<void>

On This Page

Properties
Methods