@serenity-js/web 3.0.0-rc.8 → 3.0.0

package/lib/screenplay/interactions/Navigate.js

@@ -2,155 +2,155 @@
 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.
+ * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+ * to navigate to a specific destination, as well as back and forth in the browser history,
+ * or reload the current page.
+ *
+ * ## Learn more
+ *
+ * - {@apilink BrowseTheWeb}
+ *
+ * @group Activities
  */
 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
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to navigate to a given URL.
+     *
+     * The URL can be:
+     * - absolute, e.g. `https://example.org/search`
+     * - relative, e.g. `/search`
+     *
+     * If the URL is relative, your Web test integration tool will append it to any base URL
+     * specified in its respective configuration file.
+     *
+     *
+     * #### Navigate to path relative to baseUrl
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Navigate } from '@serenity-js/web'
+     *
+     * await actorCalled('Hannu')
+     *   .attemptsTo(
+     *     Navigate.to('/search'),
+     *   )
+     * ```
+     *
+     * ## Navigate to an absolute URL (overrides baseUrl)
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Navigate } from '@serenity-js/web'
+     *
+     * await actorCalled('Hannu')
+     *   .whoCan(BrowseTheWeb.using(browser))
+     *   .attemptsTo(
+     *     Navigate.to('https://mycompany.org/login'),
+     *   )
+     * ```
+     *
+     * #### Learn more
      *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * - {@apilink Page.navigateTo}
+     * - [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)
      *
-     * @see {@link BrowseTheWeb}
+     * @param url
+     *  An absolute URL or path an {@apilink Actor}
+     *  should navigate to
      */
     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';
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to navigate back one page in the joint session history of the current top-level browsing context.
      *
-     *  actorCalled('Hannu')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          Navigate.to('/first'),
-     *          Navigate.to('/second'),
+     * #### Navigate back in browsing history
      *
-     *          Navigate.back(),
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Ensure, endsWith } from '@serenity-js/assertions'
+     * import { Navigate, Page } from '@serenity-js/web'
      *
-     *          Ensure.that(Website.url(), endsWith('/first')),
-     *      );
+     * await actorCalled('Hannu')
+     *   .whoCan(BrowseTheWeb.using(browser))
+     *   .attemptsTo(
+     *     Navigate.to('/first'),
+     *     Navigate.to('/second'),
      *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *     Navigate.back(),
      *
-     * @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}
+     *     Ensure.that(Page.current().url().href, endsWith('/first')),
+     *   )
+     * ```
      */
     static back() {
-        return core_1.Interaction.where(`#actor navigates back in the browser history`, actor => abilities_1.BrowseTheWeb.as(actor).navigateBack());
+        return core_1.Interaction.where(`#actor navigates back in the browser history`, async (actor) => {
+            const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+            await page.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';
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to navigate forward one page in the joint session history of the current top-level browsing context.
      *
-     *  actorCalled('Hannu')
-     *      .whoCan(BrowseTheWeb.using(browser))
-     *      .attemptsTo(
-     *          Navigate.to('/first'),
-     *          Navigate.to('/second'),
+     * #### Navigate forward in browsing history
      *
-     *          Navigate.back(),
-     *          Navigate.forward(),
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Ensure, endsWith } from '@serenity-js/assertions'
+     * import { Navigate, Page } from '@serenity-js/web'
      *
-     *          Ensure.that(Website.url(), endsWith('/second')),
-     *      );
+     * await actorCalled('Hannu')
+     *   .whoCan(BrowseTheWeb.using(browser))
+     *   .attemptsTo(
+     *     Navigate.to('/first'),
+     *     Navigate.to('/second'),
      *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     *     Navigate.back(),
+     *     Navigate.forward(),
      *
-     * @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
+     *     Ensure.that(Page.current().url().href, endsWith('/second')),
+     *   )
+     * ```
      */
     static forward() {
-        return core_1.Interaction.where(`#actor navigates forward in the browser history`, actor => abilities_1.BrowseTheWeb.as(actor).navigateForward());
+        return core_1.Interaction.where(`#actor navigates forward in the browser history`, async (actor) => {
+            const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+            await page.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}
+     * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
+     * to reload the current page.
+     *
+     * #### Navigate to path relative to baseUrl
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { Ensure, endsWith } from '@serenity-js/assertions'
+     * import { Navigate, Cookie } from '@serenity-js/web'
+     *
+     * await actorCalled('Hannu')
+     *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+     *   .attemptsTo(
+     *     Navigate.to('/login'),
+     *     Cookie.called('session_id').delete(),
+     *     Navigate.reloadPage(),
+     *   )
+     * ```
      */
     static reloadPage() {
-        return core_1.Interaction.where(`#actor reloads the page`, actor => abilities_1.BrowseTheWeb.as(actor).reloadPage());
+        return core_1.Interaction.where(`#actor reloads the page`, async (actor) => {
+            const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+            await page.reload();
+        });
     }
 }
 exports.Navigate = Navigate;
@@ -159,40 +159,18 @@ exports.Navigate = Navigate;
  */
 class NavigateToUrl extends core_1.Interaction {
     constructor(url) {
-        super();
+        super((0, core_1.d) `#actor navigates to ${url}`);
         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}
+     * @inheritDoc
      */
-    performAs(actor) {
-        return actor.answer(this.url)
-            .then(url => abilities_1.BrowseTheWeb.as(actor)
-            .navigateTo(url)
-            .catch(error => {
+    async performAs(actor) {
+        const url = await actor.answer(this.url);
+        const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+        return page.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

@@ -1 +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"}
+{"version":3,"file":"Navigate.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Navigate.ts"],"names":[],"mappings":";;;AAAA,4CAAsH;AAEtH,4CAA4C;AAE5C;;;;;;;;;;GAUG;AACH,MAAa,QAAQ;IAEjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACH,MAAM,CAAC,EAAE,CAAC,GAAuB;QAC7B,OAAO,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,IAAI;QACP,OAAO,kBAAW,CAAC,KAAK,CAAC,8CAA8C,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACnF,MAAM,IAAI,GAAG,MAAM,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAExD,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QAC9B,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,MAAM,CAAC,OAAO;QACV,OAAO,kBAAW,CAAC,KAAK,CAAC,iDAAiD,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACtF,MAAM,IAAI,GAAG,MAAM,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAExD,MAAM,IAAI,CAAC,eAAe,EAAE,CAAC;QACjC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,UAAU;QACb,OAAO,kBAAW,CAAC,KAAK,CAAC,yBAAyB,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC9D,MAAM,IAAI,GAAG,MAAM,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAExD,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;QACxB,CAAC,CAAC,CAAC;IACP,CAAC;CACJ;AAjJD,4BAiJC;AAED;;GAEG;AACH,MAAM,aAAc,SAAQ,kBAAW;IACnC,YAA6B,GAAuB;QAChD,KAAK,CAAC,IAAA,QAAC,EAAA,uBAAwB,GAAI,EAAE,CAAC,CAAC;QADd,QAAG,GAAH,GAAG,CAAoB;IAEpD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAExD,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;YACtC,MAAM,IAAI,2BAAoB,CAAC,wBAAyB,GAAI,EAAE,EAAE,KAAK,CAAC,CAAC;QAC3E,CAAC,CAAC,CAAC;IACP,CAAC;CACJ"}

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

@@ -1,39 +1,23 @@
 import { Answerable, AnswersQuestions, Interaction } from '@serenity-js/core';
+import { FileSystemLocation } from '@serenity-js/core/lib/io';
 import { PageElement } from '../models';
 /**
- * @desc
- *  A base class for interactions with {@link PageElement}s.
+ * A base class for interactions with {@apilink PageElement} objects.
  *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * **Note:** The recommended way to implement custom interactions
+ * in your code is to use the {@apilink Interaction.where} factory method.
+ *
+ * @group Activities
  */
 export declare abstract class PageElementInteraction extends Interaction {
-    private readonly description;
+    protected constructor(description: string, location?: FileSystemLocation);
     /**
-     * @param {string} description
-     *  A human-readable description to be used when reporting
-     *  this {@link @serenity-js/core/lib/screenplay~Interaction}.
+     * Returns the resolved {@apilink PageElement}, or throws a {@apilink LogicError}
+     * if the element is `undefined`.
      *
-     * @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
+     * @param actor
+     * @param element
      */
     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;
 }
+//# sourceMappingURL=PageElementInteraction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"PageElementInteraction.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/PageElementInteraction.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAK,WAAW,EAAc,MAAM,mBAAmB,CAAC;AAC7F,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAE9D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC;;;;;;;GAOG;AACH,8BAAsB,sBAAuB,SAAQ,WAAW;IAE5D,SAAS,aAAa,WAAW,EAAE,MAAM,EAAE,QAAQ,GAAE,kBAAkD;IAIvG;;;;;;OAMG;cACa,OAAO,CACnB,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,UAAU,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,WAAW,CAAC;CAS1B"}

package/lib/screenplay/interactions/PageElementInteraction.js

@@ -2,53 +2,32 @@
 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.
+ * A base class for interactions with {@apilink PageElement} objects.
  *
- * @extends {@serenity-js/core/lib/screenplay~Interaction}
+ * **Note:** The recommended way to implement custom interactions
+ * in your code is to use the {@apilink Interaction.where} factory method.
+ *
+ * @group Activities
  */
 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;
+    constructor(description, location = core_1.Interaction.callerLocation(4)) {
+        super(description, location);
     }
     /**
-     * @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 the resolved {@apilink PageElement}, or throws a {@apilink LogicError}
+     * if the element is `undefined`.
      *
-     * @returns {Promise<PageElement>}
-     *
-     * @protected
+     * @param actor
+     * @param element
      */
     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}`);
+            throw new core_1.LogicError((0, core_1.d) `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

@@ -1 +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"}
+{"version":3,"file":"PageElementInteraction.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/PageElementInteraction.ts"],"names":[],"mappings":";;;AAAA,4CAA6F;AAK7F;;;;;;;GAOG;AACH,MAAsB,sBAAuB,SAAQ,kBAAW;IAE5D,YAAsB,WAAmB,EAAE,WAA+B,kBAAW,CAAC,cAAc,CAAC,CAAC,CAAC;QACnG,KAAK,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;OAMG;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,QAAC,EAAC,iBAAkB,OAAQ,EAAE,CAAC,CAAC;SACxD;QAED,OAAO,QAAQ,CAAC;IACpB,CAAC;CACJ;AAzBD,wDAyBC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"Press.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/Press.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,gBAAgB,EAAK,WAAW,EAAY,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAIpH,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBAAa,KAAM,SAAQ,sBAAsB;IA+BzC,OAAO,CAAC,QAAQ,CAAC,IAAI;IA7BzB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,GAAG,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC,GAAG,QAAQ,GAAG;QAAE,EAAE,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,WAAW,CAAA;KAAE;IAI3I;;;;OAIG;IACH,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,WAAW;IAI/C;;;OAGG;IACH,SAAS,aACY,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,CAAC;IAK1D;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAK1E"}