Class Locator

Describes how to find an element and acts on it once it is ready: attached, visible, enabled and stable (unless turned off). Each action waits and retries until the locator's timeout. Created by Page.locator, Frame.locator, ElementHandle.asLocator and Locator.race.

A locator is an immutable description: the set…, map, filter and clone members return a new locator, and nothing runs in the page until an action (click, fill, hover, scroll, wait, waitHandle) is called.

pjsc differences:

At most 64 chain options per locator, Locator.race nested at most 4 deep, and at most 64 locators in one race tree.
An action's signal option is ignored: every action ends with the render.
Main-frame click, fill, hover and scroll wait until pjsc's own navigation to the request url has finished.

await page.locator("#name").fill("pjsc");
await page.locator("button[type=submit]").setTimeout(5000).click();
const total = await page.locator(".total").map((el) => el.textContent).wait();

Methods

click

click(options?: ClickOptions & { offset?: Point }): Promise<void>
Clicks the element.
Parameters
- Optionaloptions: ClickOptions & { offset?: Point }
  click options (button, clickCount, delay, offset)
Returns Promise<void>

clone

clone(): Locator

A copy of this locator.

Returns Locator

emit

emit(event: string, data?: unknown): boolean
Calls the handlers of event with data; true when there were any.
Parameters
- event: string
- Optionaldata: unknown
Returns boolean

fill

fill(value: string, options?: Record<string, unknown>): Promise<void>
Fills an input, textarea, select or contenteditable element with value.
Parameters
- value: string
- Optionaloptions: Record<string, unknown>
Returns Promise<void>

filter

filter(predicate: PageFunction): Locator
A copy that only accepts values for which predicate(value), run in the page, is true.
Parameters
- predicate: PageFunction
Returns Locator

hover

hover(options?: Record<string, unknown>): Promise<void>
Moves the mouse over the element.
Parameters
- Optionaloptions: Record<string, unknown>
Returns Promise<void>

listenerCount

listenerCount(event: string): number
The number of handlers for event.
Parameters
- event: string
Returns number

map

map(mapper: PageFunction): Locator
A copy whose found value is mapper(value), run in the page.
Parameters
- mapper: PageFunction
Returns Locator

off

off(event: string, handler?: (...args: any[]) => void): this
Removes handler (or every handler, without handler) for event.
Parameters
- event: string
- Optionalhandler: (...args: any[]) => void
Returns this

on

on(event: string, handler: (...args: any[]) => void): this
Adds handler for event. The locator emits LocatorEvent.Action right before click, fill, hover and scroll; a handler that throws makes the action fail.
Parameters
- event: string
- handler: (...args: any[]) => void
Returns this

once

once(event: string, handler: (...args: any[]) => void): this
Adds handler for the next event only.
Parameters
- event: string
- handler: (...args: any[]) => void
Returns this

removeAllListeners

removeAllListeners(event?: string): this
Removes every handler of event, or of every event.
Parameters
- Optionalevent: string
Returns this

scroll

scroll(options?: { scrollLeft?: number; scrollTop?: number }): Promise<void>
Scrolls the element to scrollTop / scrollLeft.
Parameters
- Optionaloptions: { scrollLeft?: number; scrollTop?: number }
Returns Promise<void>

setEnsureElementIsInTheViewport

setEnsureElementIsInTheViewport(value: boolean): Locator
A copy that scrolls (true) or does not scroll (false) the element into the viewport before acting.
Parameters
- value: boolean
Returns Locator

setTimeout

setTimeout(timeout: number): Locator
A copy of this locator whose actions time out after timeout milliseconds (0 = no timeout).
Parameters
- timeout: number
Returns Locator

setVisibility

setVisibility(visibility: "visible" | "hidden"): Locator
A copy that waits for the element to be "visible", "hidden", or neither (null).
Parameters
- visibility: "visible" | "hidden"
Returns Locator

setWaitForEnabled

setWaitForEnabled(value: boolean): Locator
A copy that waits (true) or does not wait (false) for the element to be enabled.
Parameters
- value: boolean
Returns Locator

setWaitForStableBoundingBox

setWaitForStableBoundingBox(value: boolean): Locator
A copy that waits (true) or does not wait (false) for the element's bounding box to be stable.
Parameters
- value: boolean
Returns Locator

wait

wait(options?: Record<string, unknown>): Promise<any>
Waits for the element (or the mapped value) and returns it as JSON.
Parameters
- Optionaloptions: Record<string, unknown>
Returns Promise<any>

waitHandle

waitHandle(options?: Record<string, unknown>): Promise<JSHandle>
Waits for the element (or the mapped value) and returns it as a :class.
Parameters
- Optionaloptions: Record<string, unknown>
Returns Promise<JSHandle>

`Static`race

race(locators: Locator[]): Locator
A locator that acts on whichever of locators finds its element first.
```
await Locator.race([page.locator("#accept"), page.locator("#agree")]).click();
```
Parameters
- locators: Locator[]
Returns Locator

Class Locator

Index

Methods

Methods

click

Parameters

Returns Promise<void>

clone

Returns Locator

emit

Parameters

Returns boolean

fill

Parameters

Returns Promise<void>

filter

Parameters

Returns Locator

hover

Parameters

Returns Promise<void>

listenerCount

Parameters

Returns number

map

Parameters

Returns Locator

off

Parameters

Returns this

on

Parameters

Returns this

once

Parameters

Returns this

removeAllListeners

Parameters

Returns this

scroll

Parameters

Returns Promise<void>

setEnsureElementIsInTheViewport

Parameters

Returns Locator

setTimeout

Parameters

Returns Locator

setVisibility

Parameters

Returns Locator

setWaitForEnabled

Parameters

Returns Locator

setWaitForStableBoundingBox

Parameters

Returns Locator

wait

Parameters

Returns Promise<any>

waitHandle

Parameters

Returns Promise<JSHandle>

Staticrace

Parameters

Returns Locator

Settings

On This Page

`Static`race