@serenity-js/web 3.41.1 → 3.42.0

package/esm/screenplay/interactions/Press.js

@@ -0,0 +1,166 @@
+import { Interaction, Question, the } from '@serenity-js/core';
+import { asyncMap } from '@serenity-js/core/io';
+import { BrowseTheWeb } from '../abilities/index.js';
+import { Key } from '../models/index.js';
+import { PageElementInteraction } from './PageElementInteraction.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to send a key press or a sequence of keys to a Web element.
+ *
+ * **Note:** On macOS, some keyboard shortcuts might not work
+ * with the [`devtools` protocol](https://webdriver.io/docs/automationProtocols/#devtools-protocol).
+ *
+ *  For example:
+ *  - to *copy*, instead of [`Key.Meta`](https://serenity-js.org/api/web/class/Key/#Meta)+`C`, use [`Key.Control`](https://serenity-js.org/api/web/class/Key/#Control)+[`Key.Insert`](https://serenity-js.org/api/web/class/Key/#Insert)
+ *  - to *cut*, instead of [`Key.Meta`](https://serenity-js.org/api/web/class/Key/#Meta)+`X`, use [`Key.Control`](https://serenity-js.org/api/web/class/Key/#Control)+[`Key.Delete`](https://serenity-js.org/api/web/class/Key/#Delete)
+ *  - to *paste*, instead of [`Key.Meta`](https://serenity-js.org/api/web/class/Key/#Meta)+`V`, use [`Key.Shift`](https://serenity-js.org/api/web/class/Key/#Shift)+[`Key.Insert`](https://serenity-js.org/api/web/class/Key/#Insert)
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <form>
+ *   <input type="text" name="example" id="example" />
+ * </form>
+ * ```
+ *
+ * ## Lean Page Object describing the widget
+ *
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
+ * }
+ * ```
+ *
+ * ## Pressing keys
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Key, Press, Value } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Priyanka')
+ *   .attemptsTo(
+ *     Press.the('H', 'i', '!', Key.ENTER).in(Form.exampleInput()),
+ *     Ensure.that(Value.of(Form.exampleInput), equals('Hi!')),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`Key`](https://serenity-js.org/api/web/class/Key/)
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * @group Activities
+ */
+export class Press extends PageElementInteraction {
+    keys;
+    /**
+     * Instantiates an [interaction](https://serenity-js.org/api/core/class/Interaction/)
+     * that instructs the [actor](https://serenity-js.org/api/core/class/Actor/)
+     * to press a sequence of [keys](https://serenity-js.org/api/web/class/Key/),
+     *
+     * When no `field` is specified, the key sequence will be sent to the currently focused element,
+     * and if no element is focused - to the `document.body` to handle.
+     *
+     * @param keys
+     *  A sequence of one or more keys to press
+     */
+    static the(...keys) {
+        return new Press(KeySequence.of(keys));
+    }
+    /**
+     * Send the key sequence to a specific element.
+     *
+     * @param field
+     */
+    in(field) {
+        return new PressKeyInField(this.keys, field);
+    }
+    /**
+     * @param keys
+     *  A sequence of one or more keys to press
+     */
+    constructor(keys) {
+        super(the `#actor presses ${keys}`);
+        this.keys = keys;
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const keys = await actor.answer(this.keys);
+        const page = await BrowseTheWeb.as(actor).currentPage();
+        return page.sendKeys(keys);
+    }
+}
+class PressKeyInField extends PageElementInteraction {
+    keys;
+    field;
+    /**
+     * @param {Answerable<Array<Key | string>>} keys
+     *  A sequence of one or more keys to press
+     *
+     * @param {Answerable<PageElement>} field
+     *  Web element to send the keys to
+     */
+    constructor(keys, field /* todo | Question<AlertPromise> | AlertPromise */) {
+        super(the `#actor presses ${keys} in ${field}`, Interaction.callerLocation(3));
+        this.keys = keys;
+        this.field = field;
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const field = await this.resolve(actor, this.field);
+        const keys = await actor.answer(this.keys);
+        const page = await BrowseTheWeb.as(actor).currentPage();
+        // fix for protractor
+        await page.executeScript(
+        /* c8 ignore next */
+        function focus(element) {
+            element.focus();
+        }, await field);
+        return page.sendKeys(keys);
+    }
+}
+/**
+ * @package
+ */
+class KeySequence extends Question {
+    keys;
+    static of(keys) {
+        return new KeySequence(keys);
+    }
+    constructor(keys) {
+        super(KeySequence.describe(keys));
+        this.keys = keys;
+    }
+    async answeredBy(actor) {
+        const keys = await asyncMap(this.keys, key => actor.answer(key));
+        return keys
+            .flat()
+            .filter(key => !!key);
+    }
+    static describe(keys) {
+        const prefix = keys.length === 1 ? 'key' : 'keys';
+        const description = keys.reduce((acc, key, index) => {
+            const separator = Key.isKey(key) && key.isModifier
+                ? '-'
+                : acc.separator;
+            return {
+                description: index === 0
+                    ? `${key}`
+                    : `${acc.description}${acc.separator}${key}`,
+                separator,
+            };
+        }, { description: '', separator: ', ' }).description;
+        return `${prefix} ${description}`;
+    }
+}
+//# sourceMappingURL=Press.js.map

package/esm/screenplay/interactions/Press.js.map

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

package/esm/screenplay/interactions/RightClick.d.ts

@@ -0,0 +1,83 @@
+import type { Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
+import type { PageElement } from '../models/index.js';
+import { PageElementInteraction } from './PageElementInteraction.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to perform a right click on a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+ *
+ * This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
+ * on a given Web element, since it's not possible to interact with the standard context menu offered by your browser.
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <form>
+ *   <input type="text" id="field"
+ *     oncontextmenu="showMenu(); return false;" />
+ *
+ *   <div id="context-menu" style="display:none">
+ *     Custom context menu
+ *   </div>
+ * </form>
+ *
+ * <script>
+ *   function showMenu() {
+ *     document.getElementById("context-menu").style.display = 'block';
+ *   }
+ * </script>
+ * ```
+ *
+ * ## Lean Page Object describing the widget
+ *
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
+ *
+ *   static exampleContextMenu = () =>
+ *     PageElement.located(By.id('context-menu'))
+ *       .describedAs('example context menu')
+ * }
+ * ```
+ *
+ * ## Right-click on an element
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { RightClick, isVisible } from '@serenity-js/web'
+ * import { Ensure } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Chloé')
+ *   .whoCan(BrowseTheWeb.using(browser))
+ *   .attemptsTo(
+ *     RightClick.on(Form.exampleInput()),
+ *     Ensure.that(Form.exampleContextMenu(), isVisible()),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * @group Activities
+ */
+export declare class RightClick extends PageElementInteraction {
+    private readonly pageElement;
+    /**
+     * Instantiates this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
+     *
+     * @param pageElement
+     *  The element to be right-clicked on
+     */
+    static on(pageElement: Answerable<PageElement>): Interaction;
+    protected constructor(pageElement: Answerable<PageElement>);
+    /**
+     * @inheritDoc
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+}
+//# sourceMappingURL=RightClick.d.ts.map

package/esm/screenplay/interactions/RightClick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RightClick.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/RightClick.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,qBAAa,UAAW,SAAQ,sBAAsB;IAW5B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAVlD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,WAAW;IAI5D,SAAS,aAA8B,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC;IAI3E;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAK1E"}

package/esm/screenplay/interactions/RightClick.js

@@ -0,0 +1,91 @@
+import { the } from '@serenity-js/core';
+import { PageElementInteraction } from './PageElementInteraction.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to perform a right click on a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+ *
+ * This is typically used to open a [custom context menu](https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event)
+ * on a given Web element, since it's not possible to interact with the standard context menu offered by your browser.
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <form>
+ *   <input type="text" id="field"
+ *     oncontextmenu="showMenu(); return false;" />
+ *
+ *   <div id="context-menu" style="display:none">
+ *     Custom context menu
+ *   </div>
+ * </form>
+ *
+ * <script>
+ *   function showMenu() {
+ *     document.getElementById("context-menu").style.display = 'block';
+ *   }
+ * </script>
+ * ```
+ *
+ * ## Lean Page Object describing the widget
+ *
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Form {
+ *   static exampleInput = () =>
+ *     PageElement.located(By.id('example'))
+ *       .describedAs('example input')
+ *
+ *   static exampleContextMenu = () =>
+ *     PageElement.located(By.id('context-menu'))
+ *       .describedAs('example context menu')
+ * }
+ * ```
+ *
+ * ## Right-click on an element
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { RightClick, isVisible } from '@serenity-js/web'
+ * import { Ensure } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Chloé')
+ *   .whoCan(BrowseTheWeb.using(browser))
+ *   .attemptsTo(
+ *     RightClick.on(Form.exampleInput()),
+ *     Ensure.that(Form.exampleContextMenu(), isVisible()),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * @group Activities
+ */
+export class RightClick extends PageElementInteraction {
+    pageElement;
+    /**
+     * Instantiates this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
+     *
+     * @param pageElement
+     *  The element to be right-clicked on
+     */
+    static on(pageElement) {
+        return new RightClick(pageElement);
+    }
+    constructor(pageElement) {
+        super(the `#actor right-clicks on ${pageElement}`);
+        this.pageElement = pageElement;
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const element = await this.resolve(actor, this.pageElement);
+        await element.scrollIntoView();
+        await element.rightClick();
+    }
+}
+//# sourceMappingURL=RightClick.js.map

package/esm/screenplay/interactions/RightClick.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RightClick.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/RightClick.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAGxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,MAAM,OAAO,UAAW,SAAQ,sBAAsB;IAWX;IAVvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,WAAoC;QAC1C,OAAO,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAED,YAAuC,WAAoC;QACvE,KAAK,CAAC,GAAG,CAAC,0BAA2B,WAAY,EAAE,CAAC,CAAC;QADlB,gBAAW,GAAX,WAAW,CAAyB;IAE3E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5D,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;QAC/B,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;IAC/B,CAAC;CACJ"}

package/esm/screenplay/interactions/Scroll.d.ts

@@ -0,0 +1,66 @@
+import type { Answerable, AnswersQuestions, UsesAbilities } from '@serenity-js/core';
+import { Interaction } from '@serenity-js/core';
+import type { PageElement } from '../models/index.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to scroll until a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) comes into view.
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <!--
+ *   an element somewhere at the bottom of the page,
+ *   outside of the visible area
+ * -->
+ * <input type="submit" id="submit" />
+ * ```
+ *
+ * ## Lean Page Object describing the widget
+ *
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Form {
+ *   static submitButton = () => {
+ *     PageElement.located(By.id('submit'))
+ *       .describedAs('submit button')
+ * }
+ * ```
+ *
+ * ## Scrolling to element
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure } from '@serenity-js/assertions'
+ * import { Scroll, isVisible } from '@serenity-js/web'
+ *
+ * await actorCalled('Sara')
+ *   .attemptsTo(
+ *     Scroll.to(Form.submitButton()),
+ *     Ensure.that(Form.submitButton(), isVisible()),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * @group Activities
+ */
+export declare class Scroll extends Interaction {
+    private readonly element;
+    /**
+     * Instantiates this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
+     *
+     * @param pageElement
+     *  The element to scroll to
+     */
+    static to(pageElement: Answerable<PageElement>): Scroll;
+    protected constructor(element: Answerable<PageElement>);
+    /**
+     * @inheritDoc
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+}
+//# sourceMappingURL=Scroll.d.ts.map

package/esm/screenplay/interactions/Scroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scroll.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Scroll.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACrF,OAAO,EAAE,WAAW,EAAO,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,MAAO,SAAQ,WAAW;IAYb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV9C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,MAAM;IAIvD,SAAS,aAA8B,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC;IAIvE;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAI1E"}

package/esm/screenplay/interactions/Scroll.js

@@ -0,0 +1,72 @@
+import { Interaction, the } from '@serenity-js/core';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to scroll until a given [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) comes into view.
+ *
+ * ## Example widget
+ *
+ * ```html
+ * <!--
+ *   an element somewhere at the bottom of the page,
+ *   outside of the visible area
+ * -->
+ * <input type="submit" id="submit" />
+ * ```
+ *
+ * ## Lean Page Object describing the widget
+ *
+ * ```ts
+ * import { By, PageElement } from '@serenity-js/web'
+ *
+ * class Form {
+ *   static submitButton = () => {
+ *     PageElement.located(By.id('submit'))
+ *       .describedAs('submit button')
+ * }
+ * ```
+ *
+ * ## Scrolling to element
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Ensure } from '@serenity-js/assertions'
+ * import { Scroll, isVisible } from '@serenity-js/web'
+ *
+ * await actorCalled('Sara')
+ *   .attemptsTo(
+ *     Scroll.to(Form.submitButton()),
+ *     Ensure.that(Form.submitButton(), isVisible()),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`PageElement`](https://serenity-js.org/api/web/class/PageElement/)
+ *
+ * @group Activities
+ */
+export class Scroll extends Interaction {
+    element;
+    /**
+     * Instantiates this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
+     *
+     * @param pageElement
+     *  The element to scroll to
+     */
+    static to(pageElement) {
+        return new Scroll(pageElement);
+    }
+    constructor(element) {
+        super(the `#actor scrolls to ${element}`);
+        this.element = element;
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const pageElement = await actor.answer(this.element);
+        await pageElement.scrollIntoView();
+    }
+}
+//# sourceMappingURL=Scroll.js.map

package/esm/screenplay/interactions/Scroll.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Scroll.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Scroll.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAIrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,OAAO,MAAO,SAAQ,WAAW;IAYI;IAVvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,WAAoC;QAC1C,OAAO,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC;IACnC,CAAC;IAED,YAAuC,OAAgC;QACnE,KAAK,CAAC,GAAG,CAAA,qBAAsB,OAAQ,EAAE,CAAC,CAAC;QADR,YAAO,GAAP,OAAO,CAAyB;IAEvE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,WAAW,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrD,MAAM,WAAW,CAAC,cAAc,EAAE,CAAC;IACvC,CAAC;CACJ"}