@serenity-js/web/src/screenplay/models/RootLocator.ts

Serenity/JS Screenplay Pattern library offering a flexible, web driver-agnostic approach for interacting with web-based user interfaces and components, suitable for various testing contexts

import util from 'node:util';

import type { Optional } from '@serenity-js/core';
import { inspectedObject } from '@serenity-js/core/lib/io';

/**
 * [`RootLocator`](https://serenity-js.org/api/web/class/RootLocator/) represents the context in which [`Locator`](https://serenity-js.org/api/web/class/Locator/) looks for [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) or [`PageElement`](https://serenity-js.org/api/web/class/PageElements/).
 * This context is either a parent element, or some representation of the top-level browsing context.
 *
 * ## Learn more
 * - [`Locator`](https://serenity-js.org/api/web/class/Locator/)
 * - [`Page.locate`](https://serenity-js.org/api/web/class/Page/#locate)
 * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
 * - [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
 *
 * @group Models
 */
export abstract class RootLocator<Native_Element_Type> implements Optional {
    public abstract switchToFrame(element: Native_Element_Type): Promise<void>;
    public abstract switchToParentFrame(): Promise<void>;
    public abstract switchToMainFrame(): Promise<void>;
    public abstract isPresent(): Promise<boolean>;

    public abstract nativeElement(): Promise<Partial<Native_Element_Type>>;

    toString(): string {
        return 'root locator';
    }

    [util.inspect.custom] = inspectedObject(this, [ ])
}