@serenity-js/web 3.41.1 → 3.42.0

package/esm/screenplay/models/Locator.d.ts

@@ -0,0 +1,48 @@
+import util from 'node:util';
+import type { PageElement } from './PageElement.js';
+import { RootLocator } from './RootLocator.js';
+import { ByCss, type Selector } from './selectors/index.js';
+/**
+ * [`Locator`](https://serenity-js.org/api/web/class/Locator/) uses a [`Selector`](https://serenity-js.org/api/web/class/Selector/) to locate a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) or [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ * within the [`Page`](https://serenity-js.org/api/web/class/Page/).
+ *
+ * ## Learn more
+ * - [`RootLocator`](https://serenity-js.org/api/web/class/RootLocator/)
+ * - [`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 declare abstract class Locator<Native_Element_Type, Native_Selector_Type = any> extends RootLocator<Native_Element_Type> {
+    protected readonly parent: RootLocator<Native_Element_Type>;
+    readonly selector: Selector;
+    protected constructor(parent: RootLocator<Native_Element_Type>, selector: Selector);
+    abstract nativeElement(): Promise<Native_Element_Type>;
+    abstract allNativeElements(): Promise<Array<Native_Element_Type>>;
+    switchToFrame(element: Native_Element_Type): Promise<void>;
+    switchToParentFrame(): Promise<void>;
+    switchToMainFrame(): Promise<void>;
+    protected abstract nativeSelector(): Native_Selector_Type;
+    abstract of(parent: RootLocator<Native_Element_Type>): Locator<Native_Element_Type>;
+    abstract closestTo(child: Locator<Native_Element_Type>): Locator<Native_Element_Type>;
+    abstract locate(child: Locator<Native_Element_Type>): Locator<Native_Element_Type>;
+    /**
+     * Expresses [`ByCss`](https://serenity-js.org/api/web/class/ByCss/), [`ById`](https://serenity-js.org/api/web/class/ById/), or [`ByTagName`](https://serenity-js.org/api/web/class/ByTagName/) as a [`ByCss`](https://serenity-js.org/api/web/class/ByCss/) selector.
+     *
+     * @throws LogicError
+     *  if the `selector` can't be expressed as [`ByCss`](https://serenity-js.org/api/web/class/ByCss/)
+     *
+     * @param selector
+     * @protected
+     */
+    protected asCssSelector(selector: Selector): ByCss;
+    abstract element(): PageElement<Native_Element_Type>;
+    abstract allElements(): Promise<Array<PageElement<Native_Element_Type>>>;
+    toString(): string;
+    /**
+     * Custom [Node.js inspection method](https://nodejs.org/api/util.html#utilinspectcustom).
+     */
+    [util.inspect.custom]: (depth: number, options: util.InspectOptionsStylized, inspect: typeof util.inspect) => string;
+}
+//# sourceMappingURL=Locator.d.ts.map

package/esm/screenplay/models/Locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Locator.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/Locator.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAK7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAmB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,8BAAsB,OAAO,CAAC,mBAAmB,EAAE,oBAAoB,GAAG,GAAG,CACzE,SAAQ,WAAW,CAAC,mBAAmB,CAAC;IAGpC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,mBAAmB,CAAC;aAC3C,QAAQ,EAAE,QAAQ;IAFtC,SAAS,aACc,MAAM,EAAE,WAAW,CAAC,mBAAmB,CAAC,EAC3C,QAAQ,EAAE,QAAQ;aAKtB,aAAa,IAAI,OAAO,CAAC,mBAAmB,CAAC;aAC7C,iBAAiB,IAAI,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC;IAElE,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1D,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxC,SAAS,CAAC,QAAQ,CAAC,cAAc,IAAI,oBAAoB;IAEzD,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IACnF,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IACrF,QAAQ,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAElF;;;;;;;;OAQG;IACH,SAAS,CAAC,aAAa,CAAC,QAAQ,EAAE,QAAQ,GAAG,KAAK;IAgBlD,QAAQ,CAAC,OAAO,IAAI,WAAW,CAAC,mBAAmB,CAAC;IAEpD,QAAQ,CAAC,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAExE,QAAQ,IAAI,MAAM;IAIlB;;OAEG;IACH,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,gGAAiE;CACzF"}

package/esm/screenplay/models/Locator.js

@@ -0,0 +1,64 @@
+import util from 'node:util';
+import { LogicError } from '@serenity-js/core';
+import { inspectedObject } from '@serenity-js/core/io';
+import { RootLocator } from './RootLocator.js';
+import { ByCss, ById, ByTagName } from './selectors/index.js';
+/**
+ * [`Locator`](https://serenity-js.org/api/web/class/Locator/) uses a [`Selector`](https://serenity-js.org/api/web/class/Selector/) to locate a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) or [`PageElement`](https://serenity-js.org/api/web/class/PageElements/)
+ * within the [`Page`](https://serenity-js.org/api/web/class/Page/).
+ *
+ * ## Learn more
+ * - [`RootLocator`](https://serenity-js.org/api/web/class/RootLocator/)
+ * - [`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 class Locator extends RootLocator {
+    parent;
+    selector;
+    constructor(parent, selector) {
+        super();
+        this.parent = parent;
+        this.selector = selector;
+    }
+    async switchToFrame(element) {
+        await this.parent.switchToFrame(element);
+    }
+    async switchToParentFrame() {
+        await this.parent.switchToParentFrame();
+    }
+    async switchToMainFrame() {
+        await this.parent.switchToMainFrame();
+    }
+    /**
+     * Expresses [`ByCss`](https://serenity-js.org/api/web/class/ByCss/), [`ById`](https://serenity-js.org/api/web/class/ById/), or [`ByTagName`](https://serenity-js.org/api/web/class/ByTagName/) as a [`ByCss`](https://serenity-js.org/api/web/class/ByCss/) selector.
+     *
+     * @throws LogicError
+     *  if the `selector` can't be expressed as [`ByCss`](https://serenity-js.org/api/web/class/ByCss/)
+     *
+     * @param selector
+     * @protected
+     */
+    asCssSelector(selector) {
+        if (selector instanceof ByCss) {
+            return selector;
+        }
+        if (selector instanceof ById) {
+            return new ByCss(`#${selector.value}`);
+        }
+        if (selector instanceof ByTagName) {
+            return new ByCss(`${selector.value}`);
+        }
+        throw new LogicError(`${selector} can't be expressed as a CSS selector`);
+    }
+    toString() {
+        return this.selector.toString();
+    }
+    /**
+     * Custom [Node.js inspection method](https://nodejs.org/api/util.html#utilinspectcustom).
+     */
+    [util.inspect.custom] = inspectedObject(this, ['parent', 'selector']);
+}
+//# sourceMappingURL=Locator.js.map

package/esm/screenplay/models/Locator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Locator.js","sourceRoot":"","sources":["../../../src/screenplay/models/Locator.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAiB,MAAM,sBAAsB,CAAC;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,OAClB,SAAQ,WAAgC;IAGjB;IACH;IAFpB,YACuB,MAAwC,EAC3C,QAAkB;QAElC,KAAK,EAAE,CAAC;QAHW,WAAM,GAAN,MAAM,CAAkC;QAC3C,aAAQ,GAAR,QAAQ,CAAU;IAGtC,CAAC;IAKD,KAAK,CAAC,aAAa,CAAC,OAA4B;QAC5C,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,mBAAmB;QACrB,MAAM,IAAI,CAAC,MAAM,CAAC,mBAAmB,EAAE,CAAC;IAC5C,CAAC;IAED,KAAK,CAAC,iBAAiB;QACnB,MAAM,IAAI,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;IAC1C,CAAC;IAQD;;;;;;;;OAQG;IACO,aAAa,CAAC,QAAkB;QACtC,IAAI,QAAQ,YAAY,KAAK,EAAE,CAAC;YAC5B,OAAO,QAAQ,CAAC;QACpB,CAAC;QAED,IAAI,QAAQ,YAAY,IAAI,EAAE,CAAC;YAC3B,OAAO,IAAI,KAAK,CAAC,IAAK,QAAQ,CAAC,KAAM,EAAE,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,QAAQ,YAAY,SAAS,EAAE,CAAC;YAChC,OAAO,IAAI,KAAK,CAAC,GAAI,QAAQ,CAAC,KAAM,EAAE,CAAC,CAAC;QAC5C,CAAC;QAED,MAAM,IAAI,UAAU,CAAC,GAAI,QAAS,uCAAuC,CAAC,CAAA;IAC9E,CAAC;IAMD,QAAQ;QACJ,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IACpC,CAAC;IAED;;OAEG;IACH,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,EAAE,CAAE,QAAsB,EAAE,UAAU,CAAE,CAAC,CAAC;CACzF"}

package/esm/screenplay/models/Page.d.ts

@@ -0,0 +1,453 @@
+import type { URL } from 'node:url';
+import type { Expectation, Optional, QuestionAdapter } from '@serenity-js/core';
+import type { CorrelationId } from '@serenity-js/core/model';
+import type { BrowsingSession } from './BrowsingSession.js';
+import type { Cookie } from './Cookie.js';
+import type { CookieData } from './CookieData.js';
+import type { ModalDialogHandler } from './dialogs/index.js';
+import type { Key } from './Key.js';
+import type { PageElement } from './PageElement.js';
+import type { PageElements } from './PageElements.js';
+import type { RootLocator } from './RootLocator.js';
+import type { Selector } from './selectors/index.js';
+import type { Switchable } from './Switchable.js';
+import type { SwitchableOrigin } from './SwitchableOrigin.js';
+/**
+ * Serenity/JS Screenplay Pattern-style model that enables interactions with a Web page
+ * rendered in a Web browser tab.
+ *
+ * ## Referring to the current page
+ *
+ * ```ts
+ * import { Ensure, endsWith } from '@serenity-js/assertions'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Page } from '@serenity-js/web'
+ *
+ * await actorCalled('Serena').attemptsTo(
+ *   Navigate.to('https://serenity-js.org'),
+ *   Ensure.that(Page.current().title(), endsWith('Serenity/JS')),
+ * )
+ * ```
+ *
+ * ## Switching to another open page
+ *
+ * ```ts
+ * import { Ensure, equals, includes, startsWith } from '@serenity-js/assertions'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Page, Switch, Text } from '@serenity-js/web'
+ *
+ * const Navigation = {
+ *   linkTo = (name: Answerable<string>) =>
+ *     PageElements.located(By.css('nav a'))
+ *       .where(Text, includes(name))
+ *       .first()
+ * }
+ *
+ * await actorCalled('Serena').attemptsTo(
+ *   Navigate.to('https://serenity-js.org'),
+ *   Click.on(Navigation.linkTo('GitHub')),
+ *
+ *   Switch.to(Page.whichUrl(startsWith('https://github.com')))
+ *
+ *   Ensure.that(
+ *     Page.current().url().href,
+ *     equals('https://github.com/serenity-js/serenity-js')
+ *   ),
+ * )
+ * ```
+ *
+ * ## Retrieving information about another open page
+ *
+ * You can retrieve information about another open page without having to explicitly switch to it:
+ *
+ * ```ts
+ * import { Ensure, equals, includes, startsWith } from '@serenity-js/assertions'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Page, Text } from '@serenity-js/web'
+ *
+ * const Navigation = {
+ *   linkTo = (name: Answerable<string>) =>
+ *     PageElements.located(By.css('nav a'))
+ *       .where(Text, includes(name))
+ *       .first()
+ * }
+ *
+ * await actorCalled('Serena').attemptsTo(
+ *   Navigate.to('https://serenity-js.org'),
+ *   Click.on(Navigation.linkTo('GitHub')),
+ *   Ensure.that(
+ *     Page.whichUrl(startsWith('https://github.com')).url().href,
+ *     equals('https://github.com/serenity-js/serenity-js')
+ *   ),
+ * )
+ * ```
+ *
+ * ## Performing activities in the context of another page
+ *
+ * ```ts
+ * import { Ensure, equals, includes, startsWith } from '@serenity-js/assertions'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Page, Text } from '@serenity-js/web'
+ *
+ * const Navigation = {
+ *   linkTo = (name: Answerable<string>) =>
+ *     PageElements.located(By.css('nav a'))
+ *       .where(Text, includes(name))
+ *       .first()
+ * }
+ *
+ * await actorCalled('Serena').attemptsTo(
+ *
+ *   // Serenity/JS GitHub repository opens in a new browser tab
+ *   Navigate.to('https://serenity-js.org'),
+ *   Click.on(Navigation.linkTo('GitHub')),
+ *
+ *   // Switch to the newly opened page and perform an assertion
+ *   Switch.to(Page.whichUrl(startsWith('https://github.com')))
+ *     .and(
+ *       Ensure.that(
+ *         Page.current().url().href,
+ *         equals('https://github.com/serenity-js/serenity-js')
+ *       )
+ *     ),
+ *   // Automatically switch back to the original page
+ *
+ *   Ensure.that(Page.current().url().href, equals('https://serenity-js.org'),
+ * )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ * - [`Optional`](https://serenity-js.org/api/core/interface/Optional/)
+ * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
+ *
+ * @group Models
+ */
+export declare abstract class Page<Native_Element_Type = any> implements Optional, Switchable {
+    protected readonly session: BrowsingSession<Page<Native_Element_Type>>;
+    protected readonly rootLocator: RootLocator<Native_Element_Type>;
+    protected modalDialogHandler: ModalDialogHandler;
+    readonly id: CorrelationId;
+    /**
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) representing the currently active [`Page`](https://serenity-js.org/api/web/class/Page/).
+     */
+    static current(): QuestionAdapter<Page>;
+    /**
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a [`Page`](https://serenity-js.org/api/web/class/Page/) which [`Page.name`](https://serenity-js.org/api/web/class/Page/#name)
+     * meets the [expectation](https://serenity-js.org/api/core/class/Expectation/).
+     *
+     * #### Switching to a page with the desired name
+     *
+     * ```ts
+     * import { includes } from '@serenity-js/assertions'
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Switch } from '@serenity-js/web'
+     *
+     * actorCalled('Bernie').attemptsTo(
+     *   Switch.to(Page.whichName(includes(`photo-gallery`))),
+     * )
+     * ```
+     *
+     * @param expectation
+     */
+    static whichName(expectation: Expectation<string>): QuestionAdapter<Page>;
+    /**
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a [`Page`](https://serenity-js.org/api/web/class/Page/) which [`Page.title`](https://serenity-js.org/api/web/class/Page/#title)
+     * meets the [expectation](https://serenity-js.org/api/core/class/Expectation/).
+     *
+     * #### Switching to a page with the desired title
+     *
+     * ```ts
+     * import { includes } from '@serenity-js/assertions'
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Switch } from '@serenity-js/web'
+     *
+     * actorCalled('Bernie').attemptsTo(
+     *   Switch.to(Page.whichTitle(includes(`Summer collection`))),
+     * )
+     * ```
+     *
+     * @param expectation
+     */
+    static whichTitle(expectation: Expectation<string>): QuestionAdapter<Page>;
+    /**
+     * Creates a [`QuestionAdapter`](https://serenity-js.org/api/core/#QuestionAdapter) that resolves to a [`Page`](https://serenity-js.org/api/web/class/Page/) which [`Page.url`](https://serenity-js.org/api/web/class/Page/#url)
+     * meets the [expectation](https://serenity-js.org/api/core/class/Expectation/).
+     *
+     * #### Switching to a page with the desired URL
+     *
+     * ```ts
+     * import { endsWith } from '@serenity-js/assertions'
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Switch } from '@serenity-js/web'
+     *
+     * actorCalled('Bernie').attemptsTo(
+     *   Switch.to(Page.whichUrl(endsWith(`/gallery.html`))),
+     * )
+     * ```
+     *
+     * @param expectation
+     */
+    static whichUrl(expectation: Expectation<string>): QuestionAdapter<Page>;
+    private static findMatchingPage;
+    protected constructor(session: BrowsingSession<Page<Native_Element_Type>>, rootLocator: RootLocator<Native_Element_Type>, modalDialogHandler: ModalDialogHandler, id: CorrelationId);
+    /**
+     * Creates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) wrapping a native element.
+     *
+     * @param nativeElement
+     */
+    abstract createPageElement(nativeElement: Native_Element_Type): PageElement<Native_Element_Type>;
+    /**
+     * Creates a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/), retrieving an element located by [`Selector`](https://serenity-js.org/api/web/class/Selector/).
+     *
+     * @param selector
+     */
+    abstract locate(selector: Selector): PageElement<Native_Element_Type>;
+    /**
+     * Creates [`PageElement`](https://serenity-js.org/api/web/class/PageElements/), retrieving a collection of elements located by [`Selector`](https://serenity-js.org/api/web/class/Selector/).
+     *
+     * @param selector
+     */
+    abstract locateAll(selector: Selector): PageElements<Native_Element_Type>;
+    /**
+     * Navigate to a given destination, specified as an absolute URL
+     * or a path relative to any base URL configured in your web test integration tool.
+     *
+     * #### Learn more
+     *
+     * - [WebdriverIO: Configuration Options](https://webdriver.io/docs/options/#baseurl)
+     * - [Playwright: Browser](https://playwright.dev/docs/api/class-browser#browser-new-context)
+     * - [Playwright: Test Options](https://playwright.dev/docs/api/class-testoptions#test-options-base-url)
+     * - [Protractor: Configuration](https://github.com/angular/protractor/blob/master/lib/config.ts)
+     *
+     * @param destination
+     */
+    abstract navigateTo(destination: string): Promise<void>;
+    /**
+     * Causes the browser to traverse one step backward in the joint session history
+     * of the current [`Page`](https://serenity-js.org/api/web/class/Page/) (the current top-level browsing context).
+     *
+     * This is equivalent to pressing the back button in the browser UI,
+     * or calling [`window.history.back`](https://developer.mozilla.org/en-US/docs/Web/API/History/back).
+     */
+    abstract navigateBack(): Promise<void>;
+    /**
+     * Causes the browser to traverse one step forward in the joint session history
+     * of the current [`Page`](https://serenity-js.org/api/web/class/Page/) (the current top-level browsing context).
+     *
+     * This is equivalent to pressing the back button in the browser UI,
+     * or calling [`window.history.forward`](https://developer.mozilla.org/en-US/docs/Web/API/History/forward).
+     */
+    abstract navigateForward(): Promise<void>;
+    /**
+     * Causes the browser to reload the [`Page`](https://serenity-js.org/api/web/class/Page/) in the current top-level browsing context.
+     */
+    abstract reload(): Promise<void>;
+    /**
+     * Send a sequence of [`Key`](https://serenity-js.org/api/web/class/Key/) strokes to the active element.
+     *
+     * @param keys
+     *  Keys to enter
+     */
+    abstract sendKeys(keys: Array<Key | string>): Promise<void>;
+    /**
+     * Schedules a command to execute JavaScript in the context of the currently selected frame or window.
+     *
+     * The script fragment will be executed as the body of an anonymous function.
+     * If the script is provided as a function object, that function will be converted to a string for injection
+     * into the target window.
+     *
+     * Any arguments provided in addition to the script will be included as script arguments and may be referenced
+     * using the `arguments` object. Arguments may be a `boolean`, `number`, `string` or `WebElement`.
+     * Arrays and objects may also be used as script arguments as long as each item adheres
+     * to the types previously mentioned.
+     *
+     * The script may refer to any variables accessible from the current window.
+     * Furthermore, the script will execute in the window's context, thus `document` may be used to refer
+     * to the current document. Any local variables will not be available once the script has finished executing,
+     * though global variables will persist.
+     *
+     * If the script has a return value (i.e. if the script contains a `return` statement),
+     * then the following steps will be taken for resolving this functions return value:
+     *
+     * - For a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/), the value will resolve to a [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
+     * - `null` and `undefined` return values will resolve to `null`
+     * - `boolean`, `number`, and `string` values will resolve as is
+     * - Functions will resolve to their string representation
+     * - For arrays and objects, each member item will be converted according to the rules above
+     *
+     * #### Use injected JavaScript to retrieve information about a HTMLElement
+     *
+     * ```ts
+     * BrowseTheWeb.as(actor).executeAsyncScript(`
+     *   return arguments[0].tagName;
+     * `, PageElement.located(By.css('h1')).describedAs('header'))
+     *
+     * // returns a Promise that resolves to 'h1'
+     * ```
+     *
+     * #### Learn more
+     * - [Selenium WebDriver: JavaScript Executor](https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/JavascriptExecutor.html#executeAsyncScript-java.lang.String-java.lang.Object...-)
+     * - [`Page.lastScriptExecutionResult`](https://serenity-js.org/api/web/class/Page/#lastScriptExecutionResult)
+     *
+     * @param script
+     * @param args
+     */
+    abstract executeScript<Result, InnerArguments extends any[]>(script: string | ((...parameters: InnerArguments) => Result), ...args: InnerArguments): Promise<Result>;
+    /**
+     * Schedules a command to execute asynchronous JavaScript in the context of the currently selected frame or window.
+     *
+     * The script fragment will be executed as the body of an anonymous function.
+     * If the script is provided as a function object, that function will be converted to a string for injection
+     * into the target window.
+     *
+     * Any arguments provided in addition to the script will be included as script arguments and may be referenced
+     * using the `arguments` object. Arguments may be a `boolean`, `number`, `string` or `WebElement`
+     * Arrays and objects may also be used as script arguments as long as each item adheres
+     * to the types previously mentioned.
+     *
+     * Unlike executing synchronous JavaScript with [`Page.executeScript`](https://serenity-js.org/api/web/class/Page/#executeScript),
+     * scripts executed with this function must explicitly signal they are finished by invoking the provided callback.
+     *
+     * This callback will always be injected into the executed function as the last argument,
+     * and thus may be referenced with `arguments[arguments.length - 1]`.
+     *
+     * The following steps will be taken for resolving this functions return value against
+     * the first argument to the script's callback function:
+     *
+     * - For a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/), the value will resolve to a [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)
+     * - `null` and `undefined` return values will resolve to `null`
+     * - `boolean`, `number`, and `string` values will resolve as is
+     * - Functions will resolve to their string representation
+     * - For arrays and objects, each member item will be converted according to the rules above
+     *
+     * #### Perform a sleep in the browser under test>
+     *
+     * ```ts
+     * BrowseTheWeb.as(actor).executeAsyncScript(`
+     *   var delay    = arguments[0];
+     *   var callback = arguments[arguments.length - 1];
+     *
+     *   window.setTimeout(callback, delay);
+     * `, 500)
+     * ```
+     *
+     * #### Return a value asynchronously
+     *
+     * ```ts
+     * BrowseTheWeb.as(actor).executeAsyncScript(`
+     *   var callback = arguments[arguments.length - 1];
+     *
+     *   callback('some return value')
+     * `).then(value => doSomethingWithThe(value))
+     * ```
+     *
+     * #### Learn more
+     * - [Selenium WebDriver: JavaScript Executor](https://seleniumhq.github.io/selenium/docs/api/java/org/openqa/selenium/JavascriptExecutor.html#executeAsyncScript-java.lang.String-java.lang.Object...-)
+     * - [`Page.lastScriptExecutionResult`](https://serenity-js.org/api/web/class/Page/#lastScriptExecutionResult)
+     *
+     * @param script
+     * @param args
+     */
+    abstract executeAsyncScript<Result, Parameters extends any[]>(script: string | ((...args: [...parameters: Parameters, callback: (result: Result) => void]) => void), ...args: Parameters): Promise<Result>;
+    /**
+     * Returns the last result of calling [`Page.executeAsyncScript`](https://serenity-js.org/api/web/class/Page/#executeAsyncScript)
+     * or [`Page.executeScript`](https://serenity-js.org/api/web/class/Page/#executeScript)
+     */
+    abstract lastScriptExecutionResult<R = any>(): R;
+    /**
+     * Take a screenshot of the top-level browsing context's viewport.
+     *
+     * @throws [`BrowserWindowClosedError`](https://serenity-js.org/api/web/class/BrowserWindowClosedError/)
+     *  When the page you're trying to take the screenshot of has already been closed
+     *
+     * @return
+     *  A promise that will resolve to a base64-encoded screenshot PNG
+     */
+    abstract takeScreenshot(): Promise<string>;
+    /**
+     * Retrieves a cookie identified by `name` and visible to this [`Page`](https://serenity-js.org/api/web/class/Page/).
+     *
+     * @param name
+     */
+    abstract cookie(name: string): Promise<Cookie>;
+    /**
+     * Adds a single cookie with [`CookieData`](https://serenity-js.org/api/web/interface/CookieData/) to the cookie store associated
+     * with the active [`Page`](https://serenity-js.org/api/web/class/Page/)'s address.
+     *
+     * @param cookieData
+     */
+    abstract setCookie(cookieData: CookieData): Promise<void>;
+    /**
+     * Removes all the cookies.
+     */
+    abstract deleteAllCookies(): Promise<void>;
+    /**
+     * Retrieves the document title of the current top-level browsing context, equivalent to calling `document.title`.
+     *
+     * #### Learn more
+     * - [Mozilla Developer Network - Document title](https://developer.mozilla.org/en-US/docs/Web/API/Document/title)
+     */
+    abstract title(): Promise<string>;
+    /**
+     * Retrieves the [URL](https://nodejs.org/api/url.html) of the current top-level browsing context.
+     */
+    abstract url(): Promise<URL>;
+    /**
+     * Retrieves the name of the current top-level browsing context.
+     *
+     * #### Learn more
+     * - [Mozilla Developer Network - Window: name property](https://developer.mozilla.org/en-US/docs/Web/API/Window/name)
+     */
+    abstract name(): Promise<string>;
+    /**
+     * Checks if a given window / tab / page is open and can be switched to, e.g. it's not closed.
+     */
+    abstract isPresent(): Promise<boolean>;
+    /**
+     * Returns the actual viewport size available for the given page,
+     * excluding any scrollbars.
+     */
+    abstract viewportSize(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    /**
+     * Sets ths size of the visible viewport to desired dimensions.
+     *
+     * @param size
+     */
+    abstract setViewportSize(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Switches the current browsing context to the given page
+     * and returns an object that allows the caller to switch back
+     * to the previous context when needed.
+     *
+     * ## Learn more
+     * - [`Switch`](https://serenity-js.org/api/web/class/Switch/)
+     * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
+     */
+    switchTo(): Promise<SwitchableOrigin>;
+    /**
+     * Closes this page.
+     */
+    abstract close(): Promise<void>;
+    /**
+     * Closes any open pages, except for this one.
+     */
+    abstract closeOthers(): Promise<void>;
+    /**
+     * Returns the [`ModalDialogHandler`](https://serenity-js.org/api/web/class/ModalDialogHandler/) for the current [`Page`](https://serenity-js.org/api/web/class/Page/).
+     */
+    modalDialog(): ModalDialogHandler;
+    /**
+     * Returns a description of this Page and its ID.
+     */
+    toString(): string;
+}
+//# sourceMappingURL=Page.d.ts.map

package/esm/screenplay/models/Page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Page.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/Page.ts"],"names":[],"mappings":"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"}