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

package/lib/screenplay/models/Cookie.d.ts

@@ -1,117 +1,157 @@
-import { Answerable, Interaction, Optional, QuestionAdapter, Timestamp } from '@serenity-js/core';
+import { Answerable, Interaction, Optional, QuestionAdapter, Timestamp, WithAnswerableProperties } from '@serenity-js/core';
 import { CookieData } from './CookieData';
+/**
+ * A Screenplay Pattern-style model responsible for managing cookies available to the current {@apilink Page}.
+ *
+ * ## Checking if a cookie exists
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Cookie } from '@serenity-js/web'
+ * import { Ensure, isPresent } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Sid')
+ *   .attemptsTo(
+ *     Navigate.to('https://example.org'),
+ *
+ *     Ensure.that(
+ *       Cookie.called('example-cookie-name'),
+ *       isPresent()
+ *     ),
+ * )
+ * ```
+ *
+ * ## Setting a cookie
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Cookie } from '@serenity-js/web'
+ * import { Ensure, isPresent, not } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Sid')
+ *   .attemptsTo(
+ *     Navigate.to('https://example.org'),
+ *
+ *     Ensure.that(Cookie.called('example-cookie-name'), not(isPresent())),
+ *
+ *     Cookie.set({
+ *       name:  'favourite',
+ *       value: 'triple chocolate',
+ *     }),
+ *
+ *     Ensure.that(Cookie.called('example-cookie-name'), isPresent()),
+ *   )
+ * ```
+ *
+ * ## Reading a cookie
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Cookie } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Sid')
+ *   .attemptsTo(
+ *     Navigate.to('https://example.org'),
+ *
+ *     Ensure.that(
+ *       Cookie.called('some-cookie-name').value(),
+ *       equals('triple chocolate')
+ *     ),
+ * )
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink CookieData}
+ * - {@apilink Page.cookie}
+ *
+ * @group Models
+ */
 export declare abstract class Cookie implements Optional {
     protected readonly cookieName: string;
     /**
-     * @desc
-     *  Creates a {@link @serenity-js/core/lib/screenplay~Question} about a Cookie
+     * Creates a {@apilink QuestionAdapter} that resolves to {@apilink Cookie} identified by `name`.
      *
-     * @param {Answerable<string>} name
-     * @returns {Question<Promise<Cookie>> & Adapter<Cookie>}
+     * @param name
      */
     static called(name: Answerable<string>): QuestionAdapter<Cookie>;
     /**
-     * @desc
-     *  Sets a cookie for the current page.
-     *  Make sure that the actor performing this interaction is on the page that should receive the cookie.
-     *  An actor can't set a cookie for an arbitrary page without being on that page.
+     * Sets a cookie for the current {@apilink Page}. Note that {@apilink CookieData} can be either a plain-old JavaScript object, or an {@apilink Answerable} {@apilink WithAnswerableProperties}.
      *
-     * @param {Answerable<CookieData>} cookieData
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * :::info
+     * Make sure that the actor performing this interaction is on the page that should receive the cookie.
+     * Because of browser security restrictions, an actor can't set a cookie for an arbitrary page without being on that page.
+     * :::
+     *
+     * @param cookieData
      */
-    static set(cookieData: Answerable<CookieData>): Interaction;
+    static set(cookieData: Answerable<WithAnswerableProperties<CookieData>>): Interaction;
     /**
-     * @desc
-     *  Creates an {@link @serenity-js/core/lib/screenplay~Interaction} to delete all cookies currently set in the browser.
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * Creates an {@apilink Interaction|interaction} to delete all cookies available to the current {@apilink Page}..
      */
     static deleteAll(): Interaction;
     private cookie;
     protected constructor(cookieName: string);
+    /**
+     * Returns the name of this cookie.
+     */
     name(): string;
     /**
-     * @desc
-     *  Checks if a given cookie is set.
+     * Checks if a given cookie is set.
      *
-     * @returns {Promise<boolean>}
+     * #### Learn more
+     * - {@apilink Optional}
      */
     isPresent(): Promise<boolean>;
     /**
-     * @desc
-     *  Returns the value of a given cookie.
-     *
-     * @returns {Promise<string>}
+     * Returns the value of a given cookie.
      */
     value(): Promise<string>;
     /**
-     * @desc
-     *  Returns the path of a given cookie, if any was set.
-     *
-     * @returns {Promise<string>}
+     * Returns the path of a given cookie, if any was set.
      */
     path(): Promise<string>;
     /**
-     * @desc
-     *  Returns the domain of a given cookie, if any was set.
-     *
-     * @returns {Promise<string>}
+     * Returns the domain of a given cookie, if any was set.
      */
     domain(): Promise<string>;
     /**
-     * @desc
-     *  Checks if a given cookie is HTTP-only.
+     * Checks if a given cookie is HTTP-only.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies
-     *
-     * @returns {Promise<string>}
+     * #### Learn more
+     * - [Mozilla Developer Network: Restricting access to cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies)
      */
     isHttpOnly(): Promise<boolean>;
     /**
-     * @desc
-     *  Checks if a given cookie is secure.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies
+     * Checks if a given cookie is secure.
      *
-     * @returns {Promise<string>}
+     * #### Learn more
+     * - [Mozilla Developer Network: Restricting access to cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies)
      */
     isSecure(): Promise<boolean>;
     /**
-     * @desc
-     *  Returns the expiry date of a given cookie
+     * Returns the expiry date of a given cookie
      *
-     * @returns {Promise<Timestamp>}
+     * #### Learn more
+     * - {@apilink Timestamp}
      */
     expiry(): Promise<Timestamp>;
     /**
-     * @desc
-     *  Deletes a given cookie.
-     *
-     * @abstract
-     *
-     * @returns {Promise<void>}
+     * Deletes a given cookie.
      */
     abstract delete(): Promise<void>;
     /**
-     * @desc
-     *  Reads a given cookie from the browser.
-     *
-     *  This method is to be implemented by integration tool-specific adapters.
-     *  **Please note**: you don't need to implement any response caching here
-     *  since it is covered by {@link Cookie#lazyLoadCookie} method.
+     * Reads a given cookie from the browser.
      *
-     * @protected
-     * @abstract
+     * This method is to be implemented by test integration tool-specific adapters.
      *
-     * @returns {Promise<void>}
+     * **Please note**: you don't need to implement any response caching here
+     * since it is covered by {@apilink Cookie.lazyLoadCookie} method.
      */
     protected abstract read(): Promise<CookieData>;
     /**
-     * @desc
-     *  Invokes {@link Cookie#read} and caches the result in memory.
-     *
-     * @private
-     * @returns {Promise<CookieData>}
+     * Invokes {@apilink Cookie.read} and caches the result in memory.
      */
     private lazyLoadCookie;
 }
+//# sourceMappingURL=Cookie.d.ts.map

package/lib/screenplay/models/Cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Cookie.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/Cookie.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAK,WAAW,EAAE,QAAQ,EAAY,eAAe,EAAE,SAAS,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAKzI,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,8BAAsB,MAAO,YAAW,QAAQ;IA2DtB,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM;IAzD3D;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC;IAQhE;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC,GAAG,WAAW;IAsBrF;;OAEG;IACH,MAAM,CAAC,SAAS,IAAI,WAAW;IAO/B,OAAO,CAAC,MAAM,CAAa;IAE3B,SAAS,aAAgC,UAAU,EAAE,MAAM;IAI3D;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAcnC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAK9B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAK7B;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAK/B;;;;;OAKG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;IAKpC;;;;;OAKG;IACG,QAAQ,IAAI,OAAO,CAAC,OAAO,CAAC;IAKlC;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,SAAS,CAAC;IAKlC;;OAEG;IACH,QAAQ,CAAC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAE9C;;OAEG;YACW,cAAc;CAO/B"}

package/lib/screenplay/models/Cookie.js

@@ -2,40 +2,103 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Cookie = void 0;
 const core_1 = require("@serenity-js/core");
-const io_1 = require("@serenity-js/core/lib/io");
 const tiny_types_1 = require("tiny-types");
 const errors_1 = require("../../errors");
 const abilities_1 = require("../abilities");
+/**
+ * A Screenplay Pattern-style model responsible for managing cookies available to the current {@apilink Page}.
+ *
+ * ## Checking if a cookie exists
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Cookie } from '@serenity-js/web'
+ * import { Ensure, isPresent } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Sid')
+ *   .attemptsTo(
+ *     Navigate.to('https://example.org'),
+ *
+ *     Ensure.that(
+ *       Cookie.called('example-cookie-name'),
+ *       isPresent()
+ *     ),
+ * )
+ * ```
+ *
+ * ## Setting a cookie
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Cookie } from '@serenity-js/web'
+ * import { Ensure, isPresent, not } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Sid')
+ *   .attemptsTo(
+ *     Navigate.to('https://example.org'),
+ *
+ *     Ensure.that(Cookie.called('example-cookie-name'), not(isPresent())),
+ *
+ *     Cookie.set({
+ *       name:  'favourite',
+ *       value: 'triple chocolate',
+ *     }),
+ *
+ *     Ensure.that(Cookie.called('example-cookie-name'), isPresent()),
+ *   )
+ * ```
+ *
+ * ## Reading a cookie
+ *
+ * ```typescript
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Navigate, Cookie } from '@serenity-js/web'
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ *
+ * await actorCalled('Sid')
+ *   .attemptsTo(
+ *     Navigate.to('https://example.org'),
+ *
+ *     Ensure.that(
+ *       Cookie.called('some-cookie-name').value(),
+ *       equals('triple chocolate')
+ *     ),
+ * )
+ * ```
+ *
+ * ## Learn more
+ * - {@apilink CookieData}
+ * - {@apilink Page.cookie}
+ *
+ * @group Models
+ */
 class Cookie {
-    constructor(cookieName) {
-        this.cookieName = cookieName;
-        (0, tiny_types_1.ensure)('browser', cookieName, (0, tiny_types_1.isDefined)());
-    }
     /**
-     * @desc
-     *  Creates a {@link @serenity-js/core/lib/screenplay~Question} about a Cookie
+     * Creates a {@apilink QuestionAdapter} that resolves to {@apilink Cookie} identified by `name`.
      *
-     * @param {Answerable<string>} name
-     * @returns {Question<Promise<Cookie>> & Adapter<Cookie>}
+     * @param name
      */
     static called(name) {
         return core_1.Question.about(`"${name}" cookie`, async (actor) => {
             const cookieName = await actor.answer(name);
-            return abilities_1.BrowseTheWeb.as(actor).cookie(cookieName);
+            const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+            return page.cookie(cookieName);
         });
     }
     /**
-     * @desc
-     *  Sets a cookie for the current page.
-     *  Make sure that the actor performing this interaction is on the page that should receive the cookie.
-     *  An actor can't set a cookie for an arbitrary page without being on that page.
+     * Sets a cookie for the current {@apilink Page}. Note that {@apilink CookieData} can be either a plain-old JavaScript object, or an {@apilink Answerable} {@apilink WithAnswerableProperties}.
+     *
+     * :::info
+     * Make sure that the actor performing this interaction is on the page that should receive the cookie.
+     * Because of browser security restrictions, an actor can't set a cookie for an arbitrary page without being on that page.
+     * :::
      *
-     * @param {Answerable<CookieData>} cookieData
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * @param cookieData
      */
     static set(cookieData) {
-        return core_1.Interaction.where((0, io_1.formatted) `#actor sets cookie: ${cookieData}`, async (actor) => {
-            const cookie = (0, tiny_types_1.ensure)('cookieData', await actor.answer(cookieData), (0, tiny_types_1.isDefined)(), (0, tiny_types_1.isPlainObject)());
+        return core_1.Interaction.where((0, core_1.d) `#actor sets cookie: ${cookieData}`, async (actor) => {
+            const cookie = (0, tiny_types_1.ensure)('cookieData', await actor.answer(core_1.Question.fromObject(cookieData)), (0, tiny_types_1.isDefined)(), (0, tiny_types_1.isPlainObject)());
+            const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
             const sanitisedCookieData = {
                 name: (0, tiny_types_1.ensure)(`Cookie.set(cookieData.name)`, cookie.name, (0, tiny_types_1.isDefined)(), (0, tiny_types_1.isString)()),
                 value: (0, tiny_types_1.ensure)(`Cookie.set(cookieData.value)`, cookie.value, (0, tiny_types_1.isDefined)(), (0, tiny_types_1.isString)()),
@@ -46,28 +109,33 @@ class Cookie {
                 expiry: ensureIfPresent(cookie, 'expiry', (0, tiny_types_1.isInstanceOf)(core_1.Timestamp)),
                 sameSite: ensureIfPresent(cookie, 'sameSite', (0, tiny_types_1.isOneOf)('Lax', 'Strict', 'None')),
             };
-            return abilities_1.BrowseTheWeb.as(actor).setCookie(sanitisedCookieData);
+            return page.setCookie(sanitisedCookieData);
         });
     }
     /**
-     * @desc
-     *  Creates an {@link @serenity-js/core/lib/screenplay~Interaction} to delete all cookies currently set in the browser.
-     *
-     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     * Creates an {@apilink Interaction|interaction} to delete all cookies available to the current {@apilink Page}..
      */
     static deleteAll() {
-        return core_1.Interaction.where(`#actor deletes all cookies`, actor => {
-            return abilities_1.BrowseTheWeb.as(actor).deleteAllCookies();
+        return core_1.Interaction.where(`#actor deletes all cookies`, async (actor) => {
+            const page = await abilities_1.BrowseTheWeb.as(actor).currentPage();
+            await page.deleteAllCookies();
         });
     }
+    constructor(cookieName) {
+        this.cookieName = cookieName;
+        (0, tiny_types_1.ensure)('browser', cookieName, (0, tiny_types_1.isDefined)());
+    }
+    /**
+     * Returns the name of this cookie.
+     */
     name() {
         return this.cookieName;
     }
     /**
-     * @desc
-     *  Checks if a given cookie is set.
+     * Checks if a given cookie is set.
      *
-     * @returns {Promise<boolean>}
+     * #### Learn more
+     * - {@apilink Optional}
      */
     async isPresent() {
         try {
@@ -82,75 +150,58 @@ class Cookie {
         }
     }
     /**
-     * @desc
-     *  Returns the value of a given cookie.
-     *
-     * @returns {Promise<string>}
+     * Returns the value of a given cookie.
      */
     async value() {
         const cookie = await this.lazyLoadCookie();
         return cookie.value;
     }
     /**
-     * @desc
-     *  Returns the path of a given cookie, if any was set.
-     *
-     * @returns {Promise<string>}
+     * Returns the path of a given cookie, if any was set.
      */
     async path() {
         const cookie = await this.lazyLoadCookie();
         return cookie.path;
     }
     /**
-     * @desc
-     *  Returns the domain of a given cookie, if any was set.
-     *
-     * @returns {Promise<string>}
+     * Returns the domain of a given cookie, if any was set.
      */
     async domain() {
         const cookie = await this.lazyLoadCookie();
         return cookie.domain;
     }
     /**
-     * @desc
-     *  Checks if a given cookie is HTTP-only.
-     *
-     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies
+     * Checks if a given cookie is HTTP-only.
      *
-     * @returns {Promise<string>}
+     * #### Learn more
+     * - [Mozilla Developer Network: Restricting access to cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies)
      */
     async isHttpOnly() {
         const cookie = await this.lazyLoadCookie();
         return cookie.httpOnly;
     }
     /**
-     * @desc
-     *  Checks if a given cookie is secure.
+     * Checks if a given cookie is secure.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies
-     *
-     * @returns {Promise<string>}
+     * #### Learn more
+     * - [Mozilla Developer Network: Restricting access to cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#restrict_access_to_cookies)
      */
     async isSecure() {
         const cookie = await this.lazyLoadCookie();
         return cookie.secure;
     }
     /**
-     * @desc
-     *  Returns the expiry date of a given cookie
+     * Returns the expiry date of a given cookie
      *
-     * @returns {Promise<Timestamp>}
+     * #### Learn more
+     * - {@apilink Timestamp}
      */
     async expiry() {
         const cookie = await this.lazyLoadCookie();
         return cookie.expiry;
     }
     /**
-     * @desc
-     *  Invokes {@link Cookie#read} and caches the result in memory.
-     *
-     * @private
-     * @returns {Promise<CookieData>}
+     * Invokes {@apilink Cookie.read} and caches the result in memory.
      */
     async lazyLoadCookie() {
         if (!this.cookie) {
@@ -169,7 +220,7 @@ exports.Cookie = Cookie;
  * @param predicates
  */
 function ensureIfPresent(data, property, ...predicates) {
-    return data[property] !== undefined
+    return data[property]
         ? (0, tiny_types_1.ensure)(`Cookie.set(cookieData.${property})`, data[property], ...predicates)
         : undefined;
 }

package/lib/screenplay/models/Cookie.js.map

@@ -1 +1 @@
-{"version":3,"file":"Cookie.js","sourceRoot":"","sources":["../../../src/screenplay/models/Cookie.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Cookie.js","sourceRoot":"","sources":["../../../src/screenplay/models/Cookie.ts"],"names":[],"mappings":";;;AAAA,4CAAyI;AACzI,2CAAqH;AAErH,yCAAkD;AAClD,4CAA4C;AAG5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAsB,MAAM;IAExB;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,IAAwB;QAClC,OAAO,eAAQ,CAAC,KAAK,CAAC,IAAK,IAAK,UAAU,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACtD,MAAM,UAAU,GAAM,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC/C,MAAM,IAAI,GAAY,MAAM,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACjE,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACnC,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,CAAC,UAA4D;QAEnE,OAAO,kBAAW,CAAC,KAAK,CAAC,IAAA,QAAC,EAAC,uBAAwB,UAAW,EAAE,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YAC5E,MAAM,MAAM,GAAG,IAAA,mBAAM,EAAC,YAAY,EAAE,MAAM,KAAK,CAAC,MAAM,CAAC,eAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,CAAe,EAAE,IAAA,sBAAS,GAAE,EAAE,IAAA,0BAAa,GAAE,CAAC,CAAC;YAErI,MAAM,IAAI,GAAG,MAAM,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YAExD,MAAM,mBAAmB,GAAe;gBACpC,IAAI,EAAU,IAAA,mBAAM,EAAC,6BAA6B,EAAM,MAAM,CAAC,IAAI,EAAG,IAAA,sBAAS,GAAE,EAAE,IAAA,qBAAQ,GAAE,CAAC;gBAC9F,KAAK,EAAS,IAAA,mBAAM,EAAC,8BAA8B,EAAK,MAAM,CAAC,KAAK,EAAE,IAAA,sBAAS,GAAE,EAAE,IAAA,qBAAQ,GAAE,CAAC;gBAC9F,IAAI,EAAU,eAAe,CAAC,MAAM,EAAE,MAAM,EAAQ,IAAA,qBAAQ,GAAE,CAAC;gBAC/D,MAAM,EAAQ,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAM,IAAA,qBAAQ,GAAE,CAAC;gBAC/D,MAAM,EAAQ,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAM,IAAA,sBAAS,GAAE,CAAC;gBAChE,QAAQ,EAAM,eAAe,CAAC,MAAM,EAAE,UAAU,EAAI,IAAA,sBAAS,GAAE,CAAC;gBAChE,MAAM,EAAQ,eAAe,CAAC,MAAM,EAAE,QAAQ,EAAM,IAAA,yBAAY,EAAC,gBAAS,CAAC,CAAC;gBAC5E,QAAQ,EAAM,eAAe,CAAC,MAAM,EAAE,UAAU,EAAI,IAAA,oBAAO,EAA4B,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;aACnH,CAAA;YAED,OAAO,IAAI,CAAC,SAAS,CAAC,mBAAmB,CAAC,CAAC;QAC/C,CAAC,CAAC,CAAC;IACP,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,SAAS;QACZ,OAAO,kBAAW,CAAC,KAAK,CAAC,4BAA4B,EAAE,KAAK,EAAC,KAAK,EAAC,EAAE;YACjE,MAAM,IAAI,GAAG,MAAM,wBAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;YACxD,MAAM,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAClC,CAAC,CAAC,CAAC;IACP,CAAC;IAID,YAAyC,UAAkB;QAAlB,eAAU,GAAV,UAAU,CAAQ;QACvD,IAAA,mBAAM,EAAC,SAAS,EAAE,UAAU,EAAE,IAAA,sBAAS,GAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,IAAI;QACA,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS;QACX,IAAI;YACA,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;YAC3C,OAAO,MAAM,IAAI,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,UAAU,CAAC;SACpD;QACD,OAAM,KAAK,EAAE;YACT,IAAI,KAAK,YAAY,2BAAkB,EAAE;gBACrC,OAAO,KAAK,CAAC;aAChB;YAED,MAAM,KAAK,CAAC;SACf;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACP,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC,KAAK,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI;QACN,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC,IAAI,CAAC;IACvB,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,MAAM;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC,MAAM,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACZ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAQ;QACV,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC,MAAM,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAC3C,OAAO,MAAM,CAAC,MAAM,CAAC;IACzB,CAAC;IAiBD;;OAEG;IACK,KAAK,CAAC,cAAc;QACxB,IAAI,CAAE,IAAI,CAAC,MAAM,EAAE;YACf,IAAI,CAAC,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;SACnC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC;IACvB,CAAC;CACJ;AA5KD,wBA4KC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAA6B,IAAgB,EAAE,QAAW,EAAE,GAAG,UAA2C;IAC9H,OAAO,IAAI,CAAC,QAAQ,CAAC;QACjB,CAAC,CAAC,IAAA,mBAAM,EAAC,yBAAyB,QAAQ,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,UAAU,CAAC;QAC7E,CAAC,CAAC,SAAS,CAAC;AACpB,CAAC"}

package/lib/screenplay/models/CookieData.d.ts

@@ -1,89 +1,51 @@
 import { Timestamp } from '@serenity-js/core';
 /**
- * @desc
- *  A data structure describing a {@link Cookie} to be set or that's been read.
+ * A data structure describing a {@apilink Cookie} to be set, or one that's been read.
  *
- * @public
+ * ## Learn more
+ *
+ * - {@apilink Cookie}
+ * - {@apilink Page.cookie}
+ *
+ * @group Models
  */
 export interface CookieData {
     /**
-     * @desc
-     *  The name of the cookie.
-     *
-     * @type {string}
-     * @public
+     * The name of the cookie.
      */
     name: string;
     /**
-     * @desc
-     *  The value of the cookie.
-     *
-     * @type {string}
-     * @public
+     * The value of the cookie.
      */
     value: string;
     /**
-     * @desc
-     *  The domain the cookie is visible to.
-     *  Defaults to the current browsing context's document's URL when setting a cookie.
+     * The domain this cookie is visible to.
      *
-     * Optional.
-     *
-     * @type {string}
-     * @public
+     * Defaults to the current browsing context's document's URL when setting a cookie.
      */
     domain?: string;
     /**
-     * @desc
-     *  The cookie path. Defaults to "/" when adding a cookie.
-     *
-     * Optional.
-     *
-     * @type {string}
-     * @public
+     * The cookie path. Defaults to "/" when adding a cookie.
      */
     path?: string;
     /**
-     * @desc
-     *  The {@link @serenity-js/core/lib/model~Timestamp} of when the cookie expires.
-     *
-     * Optional.
-     *
-     * @type {@serenity-js/core/lib/model~Timestamp}
-     * @public
+     * The {@apilink Timestamp} describing the point in time when this cookie expires.
      */
     expiry?: Timestamp;
     /**
-     * @desc
-     *  Whether the cookie is an HTTP-only cookie. Defaults to false when adding a new cookie.
-     *
-     * Optional.
-     *
-     * @type {boolean}
-     * @public
+     * Whether the cookie is an HTTP-only cookie.
+     * Defaults to `false` when adding a new cookie.
      */
     httpOnly?: boolean;
     /**
-     * @desc
-     *  Whether the cookie is a secure cookie. Defaults to false when adding a new cookie.
-     *
-     *  Optional.
-     *
-     * @type {boolean}
-     * @public
+     * Whether the cookie is a secure cookie.
+     * Defaults to `false` when adding a new cookie.
      */
     secure?: boolean;
     /**
-     * @desc
-     *  Whether the cookie applies to a SameSite policy.
-     *  Defaults to "None" if omitted when adding a cookie.
-     *
-     *  Can be set to either "Lax" or "Strict".
-     *
-     *  Optional.
-     *
-     * @type {string}
-     * @public
+     * Whether the cookie applies to a `SameSite` policy.
+     * Defaults to `None` if omitted when adding a cookie.
      */
     sameSite?: 'Lax' | 'Strict' | 'None';
 }
+//# sourceMappingURL=CookieData.d.ts.map

package/lib/screenplay/models/CookieData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CookieData.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/CookieData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IAEvB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;CACxC"}

package/lib/{input → screenplay/models}/Key.d.ts

@@ -1,15 +1,18 @@
 /**
- * @desc
- *  Represents pressable keys that aren't text to be used with {@link Press}.
+ * Represents keyboard keys that aren't text, and that can be used with the {@apilink Interaction|interaction} to {@apilink Press}.
  *
- *  Note that modifier like Shift, Alt and Meta (a.k.a. Command on Mac) will stay pressed
+ * **Note:** Modifier keys like {@apilink Key.Shift}, {@apilink Key.Alt} and {@apilink Key.Meta} (a.k.a. "Command" on Mac) will stay pressed,
+ * so there's no need to depress them.
  *
- * @enum {string}
- * @see {@link Press}
- * @see https://w3c.github.io/webdriver/webdriver-spec.html#keyboard-actions
- * @see https://github.com/puppeteer/puppeteer/blob/v7.1.0/src/common/USKeyboardLayout.ts
- * @see https://github.com/SeleniumHQ/selenium/blob/trunk/javascript/node/selenium-webdriver/lib/input.js#L46
- * @see https://github.com/webdriverio/webdriverio/blob/main/packages/wdio-utils/src/constants.ts#L5
+ * ## Learn more
+ *
+ * - {@apilink Press}
+ * - {@apilink Page.sendKeys}
+ * - [W3C WebDriver Spec: Keyboard Actions](https://w3c.github.io/webdriver/webdriver-spec.html#keyboard-actions)
+ * - [Selenium WebDriver: Inputs](https://github.com/SeleniumHQ/selenium/blob/trunk/javascript/node/selenium-webdriver/lib/input.js#L46)
+ * - [WebdriverIO: Constants](https://github.com/webdriverio/webdriverio/blob/main/packages/wdio-utils/src/constants.ts#L5)
+ *
+ * @group Models
  */
 export declare class Key {
     readonly devtoolsName: string;
@@ -71,3 +74,4 @@ export declare class Key {
     constructor(devtoolsName: string, utf16codePoint: string, isModifier?: boolean);
     toString(): string;
 }
+//# sourceMappingURL=Key.d.ts.map

package/lib/screenplay/models/Key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Key.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/Key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,GAAG;aA4DQ,YAAY,EAAE,MAAM;aACpB,cAAc,EAAE,MAAM;aACtB,UAAU,EAAE,OAAO;IA7DvC,OAAc,GAAG,MAAkC;IACnD,OAAc,SAAS,MAAkC;IACzD,OAAc,SAAS,MAAkC;IACzD,OAAc,UAAU,MAAmC;IAC3D,OAAc,OAAO,MAAgC;IACrD,OAAc,SAAS,MAAkC;IACzD,OAAc,MAAM,MAA+B;IACnD,OAAc,KAAK,MAA8B;IACjD,OAAc,OAAO,MAAsC;IAC3D,OAAc,MAAM,MAA+B;IACnD,OAAc,GAAG,MAA4B;IAC7C,OAAc,KAAK,MAA8B;IACjD,OAAc,MAAM,MAA+B;IACnD,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,EAAE,MAA2B;IAC3C,OAAc,GAAG,MAA4B;IAC7C,OAAc,GAAG,MAA4B;IAC7C,OAAc,GAAG,MAA4B;IAC7C,OAAc,IAAI,MAA6B;IAC/C,OAAc,IAAI,MAA6B;IAC/C,OAAc,MAAM,MAA+B;IACnD,OAAc,IAAI,MAAmC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,OAAO,MAAgC;IACrD,OAAc,SAAS,MAAkC;IACzD,OAAc,aAAa,MAAsC;IACjE,OAAc,YAAY,MAAqC;IAC/D,OAAc,WAAW,MAAoC;IAC7D,OAAc,cAAc,MAAuC;IACnE,OAAc,cAAc,MAAuC;IACnE,OAAc,QAAQ,MAAiC;IACvD,OAAc,MAAM,MAA+B;IACnD,OAAc,KAAK,MAA8B;IACjD,OAAc,SAAS,MAAkC;IACzD,OAAc,KAAK,MAAoC;IACvD,OAAc,KAAK,MAA8B;IACjD,OAAc,GAAG,MAA4B;WAE/B,KAAK,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,GAAG;gBAMnC,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,MAAM,EACtB,UAAU,GAAE,OAAe;IAI/C,QAAQ,IAAI,MAAM;CAGrB"}