/** * @license * Copyright 2023 Google Inc. * SPDX-License-Identifier: Apache-2.0 */ import type { Observable, OperatorFunction } from '../../../third_party/rxjs/rxjs.js'; import type { EventType } from '../../common/EventEmitter.js'; import { EventEmitter } from '../../common/EventEmitter.js'; import type { Awaitable, HandleFor, NodeFor } from '../../common/types.js'; import type { ClickOptions, ElementHandle } from '../ElementHandle.js'; import type { Frame } from '../Frame.js'; import type { Page } from '../Page.js'; /** * Whether to wait for the element to be * {@link ElementHandle.isVisible | visible} or * {@link ElementHandle.isHidden | hidden}. * `null` to disable visibility checks. * * @public */ export type VisibilityOption = 'hidden' | 'visible' | null; /** * @public */ export interface ActionOptions { /** * A signal to abort the locator action. */ signal?: AbortSignal; } /** * @public */ export type LocatorClickOptions = ClickOptions & ActionOptions; /** * @public */ export interface LocatorFillOptions extends ActionOptions { /** * The number of characters to type before switching to a faster fill-out * method. * * @defaultValue `100` */ typingThreshold?: number; } /** * @public */ export interface LocatorScrollOptions extends ActionOptions { scrollTop?: number; scrollLeft?: number; } /** * All the events that a locator instance may emit. * * @public */ export declare enum LocatorEvent { /** * Emitted every time before the locator performs an action on the located element(s). */ Action = "action" } /** * @public */ export interface LocatorEvents extends Record { [LocatorEvent.Action]: undefined; } /** * Locators describe a strategy of locating objects and performing an action on * them. If the action fails because the object is not ready for the action, the * whole operation is retried. Various preconditions for a successful action are * checked automatically. * * See {@link https://pptr.dev/guides/page-interactions#locators} for details. * * @public */ export declare abstract class Locator extends EventEmitter { #private; /** * Creates a race between multiple locators trying to locate elements in * parallel but ensures that only a single element receives the action. * * @public */ static race(locators: Locators): Locator>; /** * Used for nominally typing {@link Locator}. */ _?: T; /** * @internal */ protected visibility: VisibilityOption; /** * @internal */ protected _timeout: number; /** * @internal */ protected operators: { conditions: (conditions: Array>, signal?: AbortSignal) => OperatorFunction, HandleFor>; retryAndRaceWithSignalAndTimer: (signal?: AbortSignal, cause?: Error) => OperatorFunction; }; get timeout(): number; /** * Creates a new locator instance by cloning the current locator and setting * the total timeout for the locator actions. * * Pass `0` to disable timeout. * * @defaultValue `Page.getDefaultTimeout()` */ setTimeout(timeout: number): Locator; /** * Creates a new locator instance by cloning the current locator with the * visibility property changed to the specified value. */ setVisibility(this: Locator, visibility: VisibilityOption): Locator; /** * Creates a new locator instance by cloning the current locator and * specifying whether to wait for input elements to become enabled before the * action. Applicable to `click` and `fill` actions. * * @defaultValue `true` */ setWaitForEnabled(this: Locator, value: boolean): Locator; /** * Creates a new locator instance by cloning the current locator and * specifying whether the locator should scroll the element into viewport if * it is not in the viewport already. * * @defaultValue `true` */ setEnsureElementIsInTheViewport(this: Locator, value: boolean): Locator; /** * Creates a new locator instance by cloning the current locator and * specifying whether the locator has to wait for the element's bounding box * to be same between two consecutive animation frames. * * @defaultValue `true` */ setWaitForStableBoundingBox(this: Locator, value: boolean): Locator; /** * @internal */ copyOptions(locator: Locator): this; /** * @internal */ abstract _clone(): Locator; /** * @internal */ abstract _wait(options?: Readonly): Observable>; /** * Clones the locator. */ clone(): Locator; /** * Waits for the locator to get a handle from the page. * * @public */ waitHandle(options?: Readonly): Promise>; /** * Waits for the locator to get the serialized value from the page. * * Note this requires the value to be JSON-serializable. * * @public */ wait(options?: Readonly): Promise; /** * Maps the locator using the provided mapper. * * @public */ map(mapper: Mapper): Locator; /** * Creates an expectation that is evaluated against located values. * * If the expectations do not match, then the locator will retry. * * @public */ filter(predicate: Predicate): Locator; /** * Creates an expectation that is evaluated against located handles. * * If the expectations do not match, then the locator will retry. * * @internal */ filterHandle(predicate: Predicate, HandleFor>): Locator; /** * Maps the locator using the provided mapper. * * @internal */ mapHandle(mapper: HandleMapper): Locator; /** * Clicks the located element. */ click(this: Locator, options?: Readonly): Promise; /** * Fills out the input identified by the locator using the provided value. The * type of the input is determined at runtime and the appropriate fill-out * method is chosen based on the type. `contenteditable`, select, textarea and * input elements are supported. */ fill(this: Locator, value: string, options?: Readonly): Promise; /** * Hovers over the located element. */ hover(this: Locator, options?: Readonly): Promise; /** * Scrolls the located element. */ scroll(this: Locator, options?: Readonly): Promise; } /** * @internal */ export declare class FunctionLocator extends Locator { #private; static create(pageOrFrame: Page | Frame, func: () => Awaitable): Locator; private constructor(); _clone(): FunctionLocator; _wait(options?: Readonly): Observable>; } /** * @public */ export type Predicate = ((value: From) => value is To) | ((value: From) => Awaitable); /** * @internal */ export type HandlePredicate = ((value: HandleFor, signal?: AbortSignal) => value is HandleFor) | ((value: HandleFor, signal?: AbortSignal) => Awaitable); /** * @internal */ export declare abstract class DelegatedLocator extends Locator { #private; constructor(delegate: Locator); protected get delegate(): Locator; setTimeout(timeout: number): DelegatedLocator; setVisibility(this: DelegatedLocator, visibility: VisibilityOption): DelegatedLocator; setWaitForEnabled(this: DelegatedLocator, value: boolean): DelegatedLocator; setEnsureElementIsInTheViewport(this: DelegatedLocator, value: boolean): DelegatedLocator; setWaitForStableBoundingBox(this: DelegatedLocator, value: boolean): DelegatedLocator; abstract _clone(): DelegatedLocator; abstract _wait(): Observable>; } /** * @internal */ export declare class FilteredLocator extends DelegatedLocator { #private; constructor(base: Locator, predicate: HandlePredicate); _clone(): FilteredLocator; _wait(options?: Readonly): Observable>; } /** * @public */ export type Mapper = (value: From) => Awaitable; /** * @internal */ export type HandleMapper = (value: HandleFor, signal?: AbortSignal) => Awaitable>; /** * @internal */ export declare class MappedLocator extends DelegatedLocator { #private; constructor(base: Locator, mapper: HandleMapper); _clone(): MappedLocator; _wait(options?: Readonly): Observable>; } /** * @internal */ export type Action = (element: HandleFor, signal?: AbortSignal) => Observable; /** * @internal */ export declare class NodeLocator extends Locator { #private; static create(pageOrFrame: Page | Frame, selector: Selector): Locator>; static createFromHandle(pageOrFrame: Page | Frame, handle: ElementHandle): Locator; private constructor(); private constructor(); _clone(): NodeLocator; _wait(options?: Readonly): Observable>; } /** * @public */ export type AwaitedLocator = T extends Locator ? S : never; /** * @internal */ export declare class RaceLocator extends Locator { #private; static create(locators: T): Locator>; constructor(locators: ReadonlyArray>); _clone(): RaceLocator; _wait(options?: Readonly): Observable>; } /** * For observables coming from promises, a delay is needed, otherwise RxJS will * never yield in a permanent failure for a promise. * * We also don't want RxJS to do promise operations to often, so we bump the * delay up to 100ms. * * @internal */ export declare const RETRY_DELAY = 100; //# sourceMappingURL=locators.d.ts.map