Locator

locator.click

Signature: locator.click(options?)

• options? <object>
  • delay? <number> Time to wait between mousedown and mouseup in milliseconds.
  • button? <'left' | 'right' | 'middle'> Defaults to 'left'.
  • force? <boolean> Whether to bypass the actionability checks. Defaults to false.
  • clickCount? <number> Count of button clicks, defaults to 1.
  • position? <object> Offset for the clickable point relative to the top-left corder of the border box.
    • x <number> x-offset for the clickable point relative to the top-left corder of the border box.
    • y <number> y-offset for the clickable point relative to the top-left corder of the border box.
  • timeout? <number> Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultNavigationTimeout() or Page.setDefaultTimeout() methods.

Returns <Promise<void>> This method scrolls element into view if needed, and then uses Page.mouse to click in the center of the element. If the element is detached from DOM, the method throws an error.

locator.dblclick

Signature: locator.dblclick(options?)

• options? <object>
  • delay? <number> Time to wait between mousedown and mouseup in milliseconds.
  • button? <'left' | 'right' | 'middle'> Defaults to 'left'.
  • force? <boolean> Whether to bypass the actionability checks. Defaults to false.
  • position? <object> Offset for the clickable point relative to the top-left corder of the border box.
    • x <number> x-offset for the clickable point relative to the top-left corder of the border box.
    • y <number> y-offset for the clickable point relative to the top-left corder of the border box.
  • timeout? <number> Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultNavigationTimeout() or Page.setDefaultTimeout() methods.

Returns <Promise<void>> This method scrolls element into view if needed, and then uses Page.mouse to double click in the center of the element. If the element is detached from DOM, the method throws an error.

locator.fill

Signature: locator.fill(value, options?)

• value <string> Value to set for the <input>, <textarea> or contenteditable element.
• options? <object>
  • timeout? <number>

This method waits for actionability checks, focuses the element, fills it and triggers an input event after filling. Note that you can pass an empty string to clear the input field.

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 filled instead.

locator.check

Signature: locator.check(options?)

• options? <object>
  • position? <object> Offset for the clickable point relative to the top-left corder of the border box.
  • x <number> x-offset for the clickable point relative to the top-left corder of the border box.
  • y <number> y-offset for the clickable point relative to the top-left corder of the border box.
  • timeout? <number> Maximum navigation time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the Page.setDefaultNavigationTimeout() or Page.setDefaultTimeout() methods.

This method checks the element by performing 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. Wait for initiated navigations to either succeed or fail.
6. Ensure that the element is now checked. If not, this method throws.

locator.uncheck

Signature: locator.uncheck(options?)

• options? <object>
  • force? <boolean> Whether to bypass the actionability checks. Defaults to false.
  • position? <object> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element. x <number> y <number>
  • timeout? <number> Maximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.
  • trial? <boolean> 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.

This method checks the element by performing the following steps:

1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already unchecked, 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. Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
6. Ensure that the element is now unchecked. 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.

locator.focus

Signature: locator.focus(options?)

• options? <object>
  • timeout? <number> Maximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.

Returns <Promise<void>>

Calls focus on the element.

locator.hover

Signature: locator.hover(options?)

• options? <object>
  • force? <boolean> Whether to bypass the actionability checks. Defaults to false.
  • modifiers? <Array<"Alt"|"Control"|"Meta"|"Shift">> 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.
    • position? <object> A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
      • x <number>
      • y <number>
  • timeout? <number> Maximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.
  • trial? <boolean> 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 <Promise<void>>

locator.isVisible

Signature: locator.isVisible(options?)

• options? <object>
  • timeout? <number> DEPRECATED This option is ignored. locator.isVisible(options?) does not wait for the element to become visible and returns immediately.

Returns <Promise<boolean>>

Returns whether the element is visible.

locator.isCheck

Signature: locator.isCheck(options?)

• options? <object>
  • timeout? <number> Maximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods.

Returns <Promise<boolean>>

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

locator.isHidden

Signature: locator.isHidden(options?)

locator.isDisabled

Signature: locator.isDisabled(options?)

• options? <object>
  • timeout? <number> Maximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed by using the browserContext.setDefaultTimeout(timeout) or page.setDefaultTimeout(timeout) methods. Returns <Promise<boolean>>

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

locator.count

Signature: locator.count()

Returns <Promise<number>>>

Returns the number of elements matching given selector.

locator.get

Signature: locator.get(selector)

• selector <string> A selector to use when resolving DOM element

Returns <Locator>

The method finds an element matching the specified selector in the locator's subtree.

locator.getByText

Signature: locator.getByText(text)

• text <string> The label text.
• Returns <Locator>

locator.getByTestId

Signature: locator.getByTestId(testId)

• testId <string>
• Returns <Locator>

locator.getByClass

• text <string>
• Returns <ElementHandle>

locator.queryElementByText

Signature: locator.queryElementByText(text)

• text <string>
• Returns <ElementHandle>

locator.queryElementByTestId

Signature: locator.queryElementByTestId(testId)

• testId <string>
• Returns <ElementHandle>

locator.queryElementByClass

Signature: locator.queryElementByClass(className)

• className <string>
• Returns <ElementHandle>