@serenity-js/web 3.0.0-rc.0

package/lib/screenplay/interactions/Wait.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Wait = void 0;
+const core_1 = require("@serenity-js/core");
+const io_1 = require("@serenity-js/core/lib/io");
+const abilities_1 = require("../abilities");
+/**
+ * @desc
+ *  Instructs the {@link @serenity-js/core/lib/screenplay/actor~Actor} to
+ *  wait before proceeding either for a set {@link @serenity-js/core/lib/model~Duration}
+ *  or until a given {@link @serenity-js/core/lib/screenplay/questions~Expectation} is met.
+ *
+ *  Under the hood, `Wait` uses WebdriverIO ["explicit waiting"](https://webdriver.io/docs/autowait/)
+ *  mechanism.
+ *
+ * @example <caption>Example widget</caption>
+ *  <!--
+ *      After about 1 second, the text will change from 'Loading...' to 'Ready!'
+ *  -->
+ *  <h1 id="status">Loading...</h1>
+ *  <script>
+ *      (function () {
+ *          setTimeout(function () {
+ *              document.getElementById('status').textContent = 'Ready!'
+ *          }, 1000);
+ *      })();
+ *  </script>
+ *
+ * @example <caption>Lean Page Object describing the widget</caption>
+ *  import { by, Target } from '@serenity-js/webdriverio';
+ *
+ *  class App {
+ *      static status = Target.the('status widget')
+ *          .located(by.id('status'));
+ *  }
+ *
+ * @example <caption>Waiting for a set amount of time</caption>
+ *  import { actorCalled, Duration } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait } from '@serenity-js/webdriverio';
+ *  import { Ensure, equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.for(Duration.ofSeconds(1.5)),
+ *          Ensure.that(App.status, equals('Ready!')),
+ *      );
+ *
+ *  // Please note that while the above implementation works,
+ *  // this approach is inefficient because at best
+ *  // the actor might wait too long and at worst the test
+ *  // might become "flaky" if any external interference
+ *  // (like network glitches, animations taking a bit too long etc.)
+ *  // makes the actor wait not long enough.
+ *
+ * @example <caption>Waiting until a condition is met</caption>
+ *  import { actorCalled } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait, Text } from '@serenity-js/webdriverio';
+ *  import { equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.until(Text.of(App.status), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ *
+ *  // Wait.until makes the Actor keep asking a Question,
+ *  // in this case Text.of(App.status), until the answer meets
+ *  // the expectation, or a timeout expires (default: 5s).
+ *  //
+ *  // Please note that both Ensure and Wait can be used with
+ *  // the same expectations, like `equals`.
+ *
+ * @example <caption>Changing the default timeout</caption>
+ *  import { actorCalled, Duration } from '@serenity-js/core';
+ *  import { BrowseTheWeb, Wait, Text } from '@serenity-js/webdriverio';
+ *  import { equals } from '@serenity-js/assertions';
+ *
+ *  actorCalled('Wendy')
+ *      .whoCan(BrowseTheWeb.using(browser))
+ *      .attemptsTo(
+ *          Wait.upTo(Duration.ofSeconds(3))
+ *              .until(Text.of(App.status), equals('Ready!')),
+ *          // app is ready, proceed with the scenario
+ *      );
+ *
+ * @see {@link BrowseTheWeb}
+ * @see {@link Target}
+ * @see {@link Text}
+ * @see {@link @serenity-js/assertions~Ensure}
+ * @see {@link @serenity-js/assertions/lib/expectations~equals}
+ * @see {@link @serenity-js/core/lib/model~Duration}
+ *
+ * @see {@link @serenity-js/core/lib/screenplay~Interaction}
+ */
+class Wait {
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait for a set duration.
+     *
+     * @param {Answerable<Duration>} duration
+     *  A set duration the {@link @serenity-js/core/lib/screenplay/actor~Actor} should wait for
+     *  before proceeding
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static for(duration) {
+        return new WaitFor(duration);
+    }
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait until the answer to the question (`actual`) meets the `expectation`,
+     *  or a custom timeout expires.
+     *
+     * @param {Duration} duration
+     *  Custom timeout to override {@link Wait.Default_Timeout}
+     *
+     * @returns {WaitBuilder}
+     */
+    static upTo(duration) {
+        return {
+            until: (actual, expectation) => new WaitUntil(actual, expectation, duration),
+        };
+    }
+    /**
+     * @desc
+     *  Instantiates a version of this {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  configured to wait until the answer to the question (`actual`) meets the `expectation`,
+     *  or a {@link Wait.Default_Timeout} expires.
+     *
+     * @param {Answerable<Actual>} actual
+     *  A {@link @serenity-js/core/lib/screenplay~Question}
+     *  that the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  will keep asking until the answer meets
+     *  the {@link @serenity-js/core/lib/screenplay/questions~Expectation} provided
+     *
+     * @param {@serenity-js/core/lib/screenplay/questions~<any,Actual>} expectation
+     *  An {@link @serenity-js/core/lib/screenplay/questions~Expectation} to be met before proceeding
+     *
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static until(actual, expectation) {
+        return new WaitUntil(actual, expectation, Wait.Default_Timeout);
+    }
+}
+exports.Wait = Wait;
+/**
+ * @desc
+ *  Default timeout of 5 seconds used with {@link Wait.until}.
+ *
+ * @type {@serenity-js/core~Duration}
+ */
+Wait.Default_Timeout = core_1.Duration.ofSeconds(5);
+/**
+ * @package
+ */
+class WaitFor extends core_1.Interaction {
+    constructor(duration) {
+        super();
+        this.duration = duration;
+    }
+    /**
+     * @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
+     * @returns {Promise<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) {
+        return actor.answer(this.duration)
+            .then(duration => abilities_1.BrowseTheWeb.as(actor).waitFor(duration));
+    }
+    /**
+     * @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 waits for ${this.duration}`;
+    }
+}
+/**
+ * @package
+ */
+class WaitUntil extends core_1.Interaction {
+    constructor(actual, expectation, timeout) {
+        super();
+        this.actual = actual;
+        this.expectation = expectation;
+        this.timeout = timeout;
+    }
+    /**
+     * @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
+     * @returns {Promise<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) {
+        const actual = this.actual, expectation = this.expectation.answeredBy(actor);
+        let expectationOutcome;
+        return abilities_1.BrowseTheWeb.as(actor)
+            .waitUntil(function () {
+            return actor.answer(actual)
+                .then(act => expectation(act))
+                .then(outcome => {
+                expectationOutcome = outcome;
+                return outcome instanceof core_1.ExpectationMet;
+            });
+        }, this.timeout)
+            .catch(error => {
+            if (expectationOutcome) {
+                throw new core_1.AssertionError(`Waited ${this.timeout.toString()} for ${(0, io_1.formatted) `${this.actual}`} to ${this.expectation.toString()}`, expectationOutcome.expected, expectationOutcome.actual, error);
+            }
+            throw 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 waits up to ${this.timeout} until ${this.actual} does ${this.expectation}`;
+    }
+}
+//# sourceMappingURL=Wait.js.map

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

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

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

@@ -0,0 +1,32 @@
+import { Answerable, Expectation, Interaction } from '@serenity-js/core';
+/**
+ * @desc
+ *  Fluent interface to make the instantiation of
+ *  the {@link @serenity-js/core/lib/screenplay~Interaction}
+ *  to {@link Wait} more readable.
+ *
+ * @see {@link Wait}
+ *
+ * @interface
+ */
+export interface WaitBuilder {
+    /**
+     * @desc
+     *  Instantiates an {@link @serenity-js/core/lib/screenplay~Interaction}
+     *  to {@link Wait}.
+     *
+     * @param {Answerable<Actual>} actual
+     *  A {@link @serenity-js/core/lib/screenplay~Question}
+     *  that the {@link @serenity-js/core/lib/screenplay/actor~Actor}
+     *  will keep asking until the answer meets
+     *  the {@link @serenity-js/core/lib/screenplay/questions~Expectation} provided
+     *
+     * @param {@serenity-js/core/lib/screenplay/questions~Expectation<any,Actual>} expectation
+     *  An {@link @serenity-js/assertions~Expectation} to be met before proceeding
+     *
+     * @returns {Interaction}
+     *
+     * @see {@link Target}
+     */
+    until: <Actual>(actual: Answerable<Actual>, expectation: Expectation<any, Actual>) => Interaction;
+}

package/lib/screenplay/interactions/WaitBuilder.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=WaitBuilder.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WaitBuilder.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/WaitBuilder.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,16 @@
+export * from './Clear';
+export * from './Click';
+export * from './DoubleClick';
+export * from './Enter';
+export * from './ExecuteScript';
+export * from './Hover';
+export * from './Navigate';
+export * from './Press';
+export * from './PressBuilder';
+export * from './RightClick';
+export * from './Scroll';
+export * from './Select';
+export * from './SelectBuilder';
+export * from './Switch';
+export * from './TakeScreenshot';
+export * from './Wait';

package/lib/screenplay/interactions/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./Clear"), exports);
+__exportStar(require("./Click"), exports);
+__exportStar(require("./DoubleClick"), exports);
+__exportStar(require("./Enter"), exports);
+__exportStar(require("./ExecuteScript"), exports);
+__exportStar(require("./Hover"), exports);
+__exportStar(require("./Navigate"), exports);
+__exportStar(require("./Press"), exports);
+__exportStar(require("./PressBuilder"), exports);
+__exportStar(require("./RightClick"), exports);
+__exportStar(require("./Scroll"), exports);
+__exportStar(require("./Select"), exports);
+__exportStar(require("./SelectBuilder"), exports);
+__exportStar(require("./Switch"), exports);
+__exportStar(require("./TakeScreenshot"), exports);
+__exportStar(require("./Wait"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,0CAAwB;AACxB,0CAAwB;AACxB,gDAA8B;AAC9B,0CAAwB;AACxB,kDAAgC;AAChC,0CAAwB;AACxB,6CAA2B;AAC3B,0CAAwB;AACxB,iDAA+B;AAC/B,+CAA6B;AAC7B,2CAAyB;AACzB,2CAAyB;AACzB,kDAAgC;AAChC,2CAAyB;AACzB,mDAAiC;AACjC,yCAAuB"}

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

@@ -0,0 +1,117 @@
+import { Adapter, Answerable, Interaction, Question, Timestamp } from '@serenity-js/core';
+import { CookieData } from './CookieData';
+export declare abstract class Cookie {
+    protected readonly cookieName: string;
+    /**
+     * @desc
+     *  Creates a {@link @serenity-js/core/lib/screenplay~Question} about a Cookie
+     *
+     * @param {Answerable<string>} name
+     * @returns {Question<Promise<Cookie>> & Adapter<Cookie>}
+     */
+    static called(name: Answerable<string>): Question<Promise<Cookie>> & Adapter<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.
+     *
+     * @param {Answerable<CookieData>} cookieData
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    static set(cookieData: Answerable<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}
+     */
+    static deleteAll(): Interaction;
+    private cookie;
+    protected constructor(cookieName: string);
+    name(): string;
+    /**
+     * @desc
+     *  Checks if a given cookie is set.
+     *
+     * @returns {Promise<boolean>}
+     */
+    isPresent(): Promise<boolean>;
+    /**
+     * @desc
+     *  Returns the value of a given cookie.
+     *
+     * @returns {Promise<string>}
+     */
+    value(): Promise<string>;
+    /**
+     * @desc
+     *  Returns the path of a given cookie, if any was set.
+     *
+     * @returns {Promise<string>}
+     */
+    path(): Promise<string>;
+    /**
+     * @desc
+     *  Returns the domain of a given cookie, if any was set.
+     *
+     * @returns {Promise<string>}
+     */
+    domain(): Promise<string>;
+    /**
+     * @desc
+     *  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>}
+     */
+    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
+     *
+     * @returns {Promise<string>}
+     */
+    isSecure(): Promise<boolean>;
+    /**
+     * @desc
+     *  Returns the expiry date of a given cookie
+     *
+     * @returns {Promise<Timestamp>}
+     */
+    expiry(): Promise<Timestamp>;
+    /**
+     * @desc
+     *  Deletes a given cookie.
+     *
+     * @abstract
+     *
+     * @returns {Promise<void>}
+     */
+    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.
+     *
+     * @protected
+     * @abstract
+     *
+     * @returns {Promise<void>}
+     */
+    protected abstract read(): Promise<CookieData>;
+    /**
+     * @desc
+     *  Invokes {@link Cookie#read} and caches the result in memory.
+     *
+     * @private
+     * @returns {Promise<CookieData>}
+     */
+    private lazyLoadCookie;
+}

package/lib/screenplay/models/Cookie.js

@@ -0,0 +1,176 @@
+"use strict";
+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");
+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
+     *
+     * @param {Answerable<string>} name
+     * @returns {Question<Promise<Cookie>> & Adapter<Cookie>}
+     */
+    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);
+        });
+    }
+    /**
+     * @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.
+     *
+     * @param {Answerable<CookieData>} cookieData
+     * @returns {@serenity-js/core/lib/screenplay~Interaction}
+     */
+    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)());
+            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)()),
+                path: ensureIfPresent(cookie, 'path', (0, tiny_types_1.isString)()),
+                domain: ensureIfPresent(cookie, 'domain', (0, tiny_types_1.isString)()),
+                secure: ensureIfPresent(cookie, 'secure', (0, tiny_types_1.isBoolean)()),
+                httpOnly: ensureIfPresent(cookie, 'httpOnly', (0, tiny_types_1.isBoolean)()),
+                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);
+        });
+    }
+    /**
+     * @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}
+     */
+    static deleteAll() {
+        return core_1.Interaction.where(`#actor deletes all cookies`, actor => {
+            return abilities_1.BrowseTheWeb.as(actor).deleteAllCookies();
+        });
+    }
+    name() {
+        return this.cookieName;
+    }
+    /**
+     * @desc
+     *  Checks if a given cookie is set.
+     *
+     * @returns {Promise<boolean>}
+     */
+    async isPresent() {
+        try {
+            const cookie = await this.lazyLoadCookie();
+            return cookie && cookie.name === this.cookieName;
+        }
+        catch (error) {
+            if (error instanceof errors_1.CookieMissingError) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    /**
+     * @desc
+     *  Returns the value of a given cookie.
+     *
+     * @returns {Promise<string>}
+     */
+    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>}
+     */
+    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>}
+     */
+    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
+     *
+     * @returns {Promise<string>}
+     */
+    async isHttpOnly() {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.httpOnly;
+    }
+    /**
+     * @desc
+     *  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>}
+     */
+    async isSecure() {
+        const cookie = await this.lazyLoadCookie();
+        return cookie.secure;
+    }
+    /**
+     * @desc
+     *  Returns the expiry date of a given cookie
+     *
+     * @returns {Promise<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>}
+     */
+    async lazyLoadCookie() {
+        if (!this.cookie) {
+            this.cookie = await this.read();
+        }
+        return this.cookie;
+    }
+}
+exports.Cookie = Cookie;
+/**
+ * @ignore
+ * @private
+ *
+ * @param data
+ * @param property
+ * @param predicates
+ */
+function ensureIfPresent(data, property, ...predicates) {
+    return data[property] !== undefined
+        ? (0, tiny_types_1.ensure)(`Cookie.set(cookieData.${property})`, data[property], ...predicates)
+        : undefined;
+}
+//# sourceMappingURL=Cookie.js.map

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

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