@serenity-js/web 3.0.0-rc.0

package/lib/screenplay/interactions/Hover.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hover = void 0;
+const io_1 = require("@serenity-js/core/lib/io");
+const PageElementInteraction_1 = require("./PageElementInteraction");
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  hover the mouse pointer over a given Web element.
+ *
+ * @example <caption>Example widget</caption>
+ *  <a data-test="example-link"
+ *      class="off"
+ *      onmouseover="this.className='on';"
+ *      onmouseout="this.className='off';"
+ *      href="/">hover over me</a>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Example {
+ *      static link = Target.the('example link')
+ *          .located(by.css('[data-test="example-link"]'));
+ *  }
+ *
+ * @example <caption>Hovering over an element</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Hover, CssClasses } from '@serenity-js/webdriverio';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Hank')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Ensure.that(CssClasses.of(Example.link), equals([ 'off' ])),
+ *
+ *          Hover.over(Example.link),
+ *          Ensure.that(CssClasses.of(Example.link), equals([ 'on' ])),
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link CssClasses}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ *
+ * @extends {ElementInteraction}
+ */
+class Hover extends PageElementInteraction_1.PageElementInteraction {
+    /**
+     * @param {Answerable<PageElement>} target
+     *  The element to be hovered over
+     */
+    constructor(target) {
+        super((0, io_1.formatted) `#actor hovers the mouse over ${target}`);
+        this.target = target;
+    }
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {Answerable<PageElement>} target
+     *  The element to be hovered over
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static over(target) {
+        return new Hover(target);
+    }
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @returns {PromiseLike<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    async performAs(actor) {
+        const element = await this.resolve(actor, this.target);
+        return element.hoverOver();
+    }
+}
+exports.Hover = Hover;
+//# sourceMappingURL=Hover.js.map

package/lib/screenplay/interactions/Hover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hover.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Hover.ts"],"names":[],"mappings":";;;AACA,iDAAqD;AAGrD,qEAAkE;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAa,KAAM,SAAQ,+CAAsB;IAe7C;;;OAGG;IACH,YAA6B,MAA+B;QACxD,KAAK,CAAC,IAAA,cAAS,EAAC,gCAAiC,MAAO,EAAE,CAAC,CAAC;QADnC,WAAM,GAAN,MAAM,CAAyB;IAE5D,CAAC;IAnBD;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,CAAC,MAA+B;QACvC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAUD;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACvD,OAAO,OAAO,CAAC,SAAS,EAAE,CAAC;IAC/B,CAAC;CACJ;AAzCD,sBAyCC"}

package/lib/screenplay/interactions/Navigate.d.ts

@@ -0,0 +1,142 @@
+import { Answerable, Interaction } from '@serenity-js/core';
+/**
+ * @desc
+ *  Allows the {@link @serenity-js/core/lib/screenplay/actor~Actor} to navigate
+ *  to a specific destination, as well as back and forth in the browser history,
+ *  or reload the current page.
+ */
+export declare class Navigate {
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  to navigate to a given URL.
+     *
+     *  The URL can be:
+     *  - absolute, i.e. `https://example.org/search`
+     *  - relative, i.e. `/search`
+     *
+     *  If the URL is relative, WebdriverIO will append it to `baseUrl` specified in
+     *  the [configuration file](https://webdriver.io/docs/configurationfile/).
+     *
+     * @example <caption>wdio.conf.ts</caption>
+     *  export const config = {
+     *      baseUrl: 'https://example.org',
+     *      // ...
+     *  }
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/search'),
+     *      );
+     *
+     * @example <caption>Navigate to an absolute URL (overrides baseUrl)</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('https://mycompany.org/login'),
+     *      );
+     *
+     * @param {Answerable<string>} url
+     *  An absolute URL or path an {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  should navigate to
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link BrowseTheWeb}
+     */
+    static to(url: Answerable<string>): Interaction;
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+     *  navigate back one page in the joint session history of the current top-level browsing context.
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Ensure, endsWith } from '@serenity-js/assertions';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/first'),
+     *          Navigate.to('/second'),
+     *
+     *          Navigate.back(),
+     *
+     *          Ensure.that(Website.url(), endsWith('/first')),
+     *      );
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see https://webdriver.io/docs/api/webdriver/#back
+     * @see {@link BrowseTheWeb}
+     * @see {@link @serenity-js/assertions~Ensure}
+     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
+     */
+    static back(): Interaction;
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+     *  navigate forward one page in the session history.
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Ensure, endsWith } from '@serenity-js/assertions';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/first'),
+     *          Navigate.to('/second'),
+     *
+     *          Navigate.back(),
+     *          Navigate.forward(),
+     *
+     *          Ensure.that(Website.url(), endsWith('/second')),
+     *      );
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link BrowseTheWeb}
+     * @see {@link @serenity-js/assertions~Ensure}
+     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
+     * @see https://webdriver.io/docs/api/webdriver/#forward
+     */
+    static forward(): Interaction;
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+     *  reload the current page.
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Ensure, endsWith } from '@serenity-js/assertions';
+     *  import { Navigate, Cookie } from '@serenity-js/web';
+     *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/login'),
+     *          Cookie.called('session_id').delete(),
+     *          Navigate.reloadPage(),
+     *      );
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link BrowseTheWeb}
+     * @see {@link Cookie}
+     * @see {@link @serenity-js/assertions~Ensure}
+     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
+     */
+    static reloadPage(): Interaction;
+}

package/lib/screenplay/interactions/Navigate.js

@@ -0,0 +1,198 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Navigate = void 0;
+const core_1 = require("@serenity-js/core");
+const io_1 = require("@serenity-js/core/lib/io");
+const abilities_1 = require("../abilities");
+/**
+ * @desc
+ *  Allows the {@link @serenity-js/core/lib/screenplay/actor~Actor} to navigate
+ *  to a specific destination, as well as back and forth in the browser history,
+ *  or reload the current page.
+ */
+class Navigate {
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  to navigate to a given URL.
+     *
+     *  The URL can be:
+     *  - absolute, i.e. `https://example.org/search`
+     *  - relative, i.e. `/search`
+     *
+     *  If the URL is relative, WebdriverIO will append it to `baseUrl` specified in
+     *  the [configuration file](https://webdriver.io/docs/configurationfile/).
+     *
+     * @example <caption>wdio.conf.ts</caption>
+     *  export const config = {
+     *      baseUrl: 'https://example.org',
+     *      // ...
+     *  }
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/search'),
+     *      );
+     *
+     * @example <caption>Navigate to an absolute URL (overrides baseUrl)</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('https://mycompany.org/login'),
+     *      );
+     *
+     * @param {Answerable<string>} url
+     *  An absolute URL or path an {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  should navigate to
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link BrowseTheWeb}
+     */
+    static to(url) {
+        return new NavigateToUrl(url);
+    }
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+     *  navigate back one page in the joint session history of the current top-level browsing context.
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Ensure, endsWith } from '@serenity-js/assertions';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/first'),
+     *          Navigate.to('/second'),
+     *
+     *          Navigate.back(),
+     *
+     *          Ensure.that(Website.url(), endsWith('/first')),
+     *      );
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see https://webdriver.io/docs/api/webdriver/#back
+     * @see {@link BrowseTheWeb}
+     * @see {@link @serenity-js/assertions~Ensure}
+     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
+     */
+    static back() {
+        return core_1.Interaction.where(`#actor navigates back in the browser history`, actor => abilities_1.BrowseTheWeb.as(actor).navigateBack());
+    }
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+     *  navigate forward one page in the session history.
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Ensure, endsWith } from '@serenity-js/assertions';
+     *  import { BrowseTheWeb, Navigate } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWeb.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/first'),
+     *          Navigate.to('/second'),
+     *
+     *          Navigate.back(),
+     *          Navigate.forward(),
+     *
+     *          Ensure.that(Website.url(), endsWith('/second')),
+     *      );
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link BrowseTheWeb}
+     * @see {@link @serenity-js/assertions~Ensure}
+     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
+     * @see https://webdriver.io/docs/api/webdriver/#forward
+     */
+    static forward() {
+        return core_1.Interaction.where(`#actor navigates forward in the browser history`, actor => abilities_1.BrowseTheWeb.as(actor).navigateForward());
+    }
+    /**
+     * @desc
+     *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+     *  reload the current page.
+     *
+     * @example <caption>Navigate to path relative to baseUrl</caption>
+     *  import { actorCalled } from '@serenity-js/core';
+     *  import { Ensure, endsWith } from '@serenity-js/assertions';
+     *  import { Navigate, Cookie } from '@serenity-js/web';
+     *  import { BrowseTheWebWithWebdriverIO } from '@serenity-js/webdriverio';
+     *
+     *  actorCalled('Hannu')
+     *      .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+     *      .attemptsTo(
+     *          Navigate.to('/login'),
+     *          Cookie.called('session_id').delete(),
+     *          Navigate.reloadPage(),
+     *      );
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @see {@link BrowseTheWeb}
+     * @see {@link Cookie}
+     * @see {@link @serenity-js/assertions~Ensure}
+     * @see {@link @serenity-js/assertions/lib/expectations~endsWith}
+     */
+    static reloadPage() {
+        return core_1.Interaction.where(`#actor reloads the page`, actor => abilities_1.BrowseTheWeb.as(actor).reloadPage());
+    }
+}
+exports.Navigate = Navigate;
+/**
+ * @package
+ */
+class NavigateToUrl extends core_1.Interaction {
+    constructor(url) {
+        super();
+        this.url = url;
+    }
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @returns {PromiseLike<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    performAs(actor) {
+        return actor.answer(this.url)
+            .then(url => abilities_1.BrowseTheWeb.as(actor)
+            .navigateTo(url)
+            .catch(error => {
+            throw new core_1.TestCompromisedError(`Couldn't navigate to ${url}`, error);
+        }));
+    }
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString() {
+        return (0, io_1.formatted) `#actor navigates to ${this.url}`;
+    }
+}
+//# sourceMappingURL=Navigate.js.map

package/lib/screenplay/interactions/Navigate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Navigate.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Navigate.ts"],"names":[],"mappings":";;;AAAA,4CAAmH;AACnH,iDAAqD;AAErD,4CAA4C;AAE5C;;;;;GAKG;AACH,MAAa,QAAQ;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,MAAM,CAAC,EAAE,CAAC,GAAuB;QAC7B,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,IAAI;QACP,OAAO,kBAAW,CAAC,KAAK,CAAC,8CAA8C,EAAE,KAAK,CAAC,EAAE,CAC7E,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,YAAY,EAAE,CACxC,CAAC;IACN,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,MAAM,CAAC,OAAO;QACV,OAAO,kBAAW,CAAC,KAAK,CAAC,iDAAiD,EAAE,KAAK,CAAC,EAAE,CAChF,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,eAAe,EAAE,CAC3C,CAAC;IACN,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,UAAU;QACb,OAAO,kBAAW,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,CAAC,EAAE,CACxD,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,CACtC,CAAC;IACN,CAAC;CACJ;AAxJD,4BAwJC;AAED;;GAEG;AACH,MAAM,aAAc,SAAQ,kBAAW;IACnC,YAA6B,GAAuB;QAChD,KAAK,EAAE,CAAC;QADiB,QAAG,GAAH,GAAG,CAAoB;IAEpD,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,KAAuC;QAC7C,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;aACxB,IAAI,CAAC,GAAG,CAAC,EAAE,CACR,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC;aACjB,UAAU,CAAC,GAAG,CAAC;aACf,KAAK,CAAC,KAAK,CAAC,EAAE;YACX,MAAM,IAAI,2BAAoB,CAAC,wBAAyB,GAAI,EAAE,EAAE,KAAK,CAAC,CAAC;QAC3E,CAAC,CAAC,CACT,CAAA;IACT,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAA,cAAS,EAAC,uBAAwB,IAAI,CAAC,GAAI,EAAE,CAAC;IACzD,CAAC;CACJ"}

package/lib/screenplay/interactions/PageElementInteraction.d.ts

@@ -0,0 +1,39 @@
+import { Answerable, AnswersQuestions, Interaction } from '@serenity-js/core';
+import { PageElement } from '../models';
+/**
+ * @desc
+ *  A base class for interactions with {@link PageElement}s.
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+export declare abstract class PageElementInteraction extends Interaction {
+    private readonly description;
+    /**
+     * @param {string} description
+     *  A human-readable description to be used when reporting
+     *  this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @protected
+     */
+    protected constructor(description: string);
+    /**
+     * @desc
+     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
+     *  if the element is `undefined`.
+     *
+     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element<'async'>>} element
+     *
+     * @returns {Promise<PageElement>}
+     *
+     * @protected
+     */
+    protected resolve(actor: AnswersQuestions, element: Answerable<PageElement>): Promise<PageElement>;
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString(): string;
+}

package/lib/screenplay/interactions/PageElementInteraction.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PageElementInteraction = void 0;
+const core_1 = require("@serenity-js/core");
+const io_1 = require("@serenity-js/core/lib/io");
+/**
+ * @desc
+ *  A base class for interactions with {@link PageElement}s.
+ *
+ * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ */
+class PageElementInteraction extends core_1.Interaction {
+    /**
+     * @param {string} description
+     *  A human-readable description to be used when reporting
+     *  this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @protected
+     */
+    constructor(description) {
+        super();
+        this.description = description;
+    }
+    /**
+     * @desc
+     *  Returns the resolved {@link PageElement}, or throws a {@link @serenity-js/core/lib/errors~LogicError}
+     *  if the element is `undefined`.
+     *
+     * @param {@serenity-js/core/lib/screenplay/actor~AnswersQuestions} actor
+     * @param {@serenity-js/core/lib/screenplay~Answerable<Element<'async'>>} element
+     *
+     * @returns {Promise<PageElement>}
+     *
+     * @protected
+     */
+    async resolve(actor, element) {
+        const resolved = await actor.answer(element);
+        if (!resolved) {
+            throw new core_1.LogicError((0, io_1.formatted) `Couldn't find ${element}`);
+        }
+        return resolved;
+    }
+    /**
+     * @desc
+     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
+     *
+     * @returns {string}
+     */
+    toString() {
+        return this.description;
+    }
+}
+exports.PageElementInteraction = PageElementInteraction;
+//# sourceMappingURL=PageElementInteraction.js.map

package/lib/screenplay/interactions/PageElementInteraction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PageElementInteraction.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/PageElementInteraction.ts"],"names":[],"mappings":";;;AAAA,4CAA0F;AAC1F,iDAAqD;AAIrD;;;;;GAKG;AACH,MAAsB,sBAAuB,SAAQ,kBAAW;IAE5D;;;;;;OAMG;IACH,YAAuC,WAAmB;QACtD,KAAK,EAAE,CAAC;QAD2B,gBAAW,GAAX,WAAW,CAAQ;IAE1D,CAAC;IAED;;;;;;;;;;;OAWG;IACO,KAAK,CAAC,OAAO,CACnB,KAAuB,EACvB,OAAgC;QAEhC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAE7C,IAAI,CAAE,QAAQ,EAAE;YACZ,MAAM,IAAI,iBAAU,CAAC,IAAA,cAAS,EAAC,iBAAkB,OAAQ,EAAE,CAAC,CAAC;SAChE;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACJ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC5B,CAAC;CACJ;AA/CD,wDA+CC"}

package/lib/screenplay/interactions/Press.d.ts

@@ -0,0 +1,84 @@
+import { Activity, Answerable, AnswersQuestions, Interaction, UsesAbilities } from '@serenity-js/core';
+import { Key } from '../../input';
+import { PageElement } from '../models';
+import { PageElementInteraction } from './PageElementInteraction';
+import { PressBuilder } from './PressBuilder';
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  send a key press or a sequence of keys to a Web element.
+ *
+ *  *Please 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 `Meta+C`, use `Control+Insert`
+ *  - to *cut*, instead of `Meta+X`, use `Control+Delete`
+ *  - to *paste*, instead of `Meta+V`, use `Shift+Insert`
+ *
+ * @example <caption>Example widget</caption>
+ *  <form>
+ *    <input type="text" name="example" id="example" />
+ *  </form>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class Form {
+ *      static exampleInput = Target.the('example input')
+ *          .located(by.id('example'));
+ *  }
+ *
+ * @example <caption>Pressing keys</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Key, Press, Value } from '@serenity-js/webdriverio';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Priyanka')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Press.the('H', 'i', '!', Key.ENTER).in(Form.exampleInput),
+ *          Ensure.that(Value.of(Form.exampleInput), equals('Hi!')),
+ *      );
+ *
+ * @see {@link Key}
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ *
+ * @extends {ElementInteraction}
+ */
+export declare class Press extends PageElementInteraction {
+    private readonly keys;
+    /**
+     * @desc
+     *  Instantiates this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {...keys: Array<Answerable<Key | string | Key[] | string[]>>} keys
+     *  A sequence of one or more keys to press
+     *
+     * @returns {PressBuilder}
+     */
+    static the(...keys: Array<Answerable<Key | string | Key[] | string[]>>): Activity & PressBuilder;
+    in(field: Answerable<PageElement>): Interaction;
+    /**
+     * @param {Answerable<Array<Key | string>>} keys
+     *  A sequence of one or more keys to press
+     */
+    constructor(keys: Answerable<Array<Key | string>>);
+    /**
+     * @desc
+     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  perform this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     *
+     * @param {UsesAbilities & AnswersQuestions} actor
+     *  An {@link @serenity-js/core/lib/screenplay/actor~Actor} to perform this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *
+     * @returns {PromiseLike<void>}
+     *
+     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~UsesAbilities}
+     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions): Promise<void>;
+}