@serenity-js/web 3.41.1 → 3.42.0

package/esm/screenplay/interactions/Switch.js

@@ -0,0 +1,159 @@
+import { Interaction, Task, the } from '@serenity-js/core';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/) who has the [ability](https://serenity-js.org/api/core/class/Ability/) to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to switch the context for future activities to a [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/), such as a [`Page`](https://serenity-js.org/api/web/class/Page/) or a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+ *
+ * Please note that when the [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) implementing [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/) represents an [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe),
+ * using [`Switch`](https://serenity-js.org/api/web/class/Switch/) will result in switching the top-level browsing context to that [`iframe`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).
+ *
+ * When the [`PageElement`](https://serenity-js.org/api/web/class/PageElement/) represents any other [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement),
+ * using [`Switch`](https://serenity-js.org/api/web/class/Switch/) sets [`HTMLElement#focus`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus)
+ * on the specified element. Assuming it can be focused.
+ *
+ * **Note:** The focused element is the element which will receive keyboard [press](https://serenity-js.org/api/web/class/Press/) events by default.
+ *
+ * ## Perform activities in the context of an iframe
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { By, Click, Enter, PageElement, Switch } from '@serenity-js/web'
+ *
+ * // Lean Page Object describing a login form, embedded in an iframe
+ * class LoginForm {
+ *   static iframe = () =>
+ *     PageElement.located(By.css('iframe'))
+ *       .describedAs('login form')
+ *
+ *   static usernameField = () =>
+ *     PageElement.located(By.css('[data-testid="username"]'))
+ *       .describedAs('username field')
+ *
+ *   static passwordField = () =>
+ *     PageElement.located(By.css('[data-testid="password"]'))
+ *       .describedAs('password field')
+ *
+ *   static submitButton = () =>
+ *     PageElement.located(By.css('button[type="submit"]'))
+ *       .describedAs('submit button')
+ *  }
+ *
+ *  await actorCalled('Francesca')
+ *    .attemptsTo(
+ *      Switch.to(LoginForm.iframe).and(
+ *        Enter.theValue('francesca@example.org').into(LoginForm.usernameField()),
+ *        Enter.theValue('correct-horse-battery-staple').into(LoginForm.passwordField()),
+ *        Click.on(LoginForm.submitButton()),
+ *      )
+ *    )
+ * ```
+ *
+ * ## Perform activities in the context of another page
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Click, Enter, Switch } from '@serenity-js/web'
+ * import { browser } from '@wdio/globals'
+ *
+ * await actorCalled('Francesca')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Switch.to(Page.whichName(startsWith('popup'))).and(
+ *       // perform some activities in the context of the new window
+ *
+ *       // optionally, close the browser tab
+ *       Page.current().close(),
+ *     ),
+ *
+ *     // Note that switching back to the original page happens automatically
+ *     // after the last activity from the list finishes
+ *   )
+ * ```
+ *
+ * ## Perform activities in the context of a focused page element
+ *
+ * ```ts
+ * import { Ensure, equals } from '@serenity-js/assertions'
+ * import { actorCalled } from '@serenity-js/core'
+ * import { Key, PageElement, Press, Switch, Value } from '@serenity-js/web'
+ * import { browser } from '@wdio/globals'
+ *
+ * const inputField = () =>
+ *   PageElement.located(By.css('input'));
+ *
+ * await actorCalled('Francesca')
+ *   .whoCan(BrowseTheWebWithWebdriverIO.using(browser))
+ *   .attemptsTo(
+ *     Switch.to(inputField()).and(
+ *       Press.the('h', 'e', 'l', 'l', 'o'),
+ *       Press.the(Key.Tab),
+ *     ),
+ *     Ensure.that(Value.of(inputField()), equals('hello'))
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/)
+ * - [`SwitchableOrigin`](https://serenity-js.org/api/web/interface/SwitchableOrigin/)
+ *
+ * @group Activities
+ */
+export class Switch extends Interaction {
+    switchable;
+    /**
+     * Instructs the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     * to switch the context for future activities to a [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/),
+     * such as a [`Page`](https://serenity-js.org/api/web/class/Page/) or a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/).
+     *
+     * @param switchable
+     */
+    static to(switchable) {
+        return new Switch(switchable);
+    }
+    constructor(switchable) {
+        super(the `#actor switches to ${switchable}`);
+        this.switchable = switchable;
+    }
+    /**
+     * Instructs the [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+     * to switch the context for future activities to a [`Switchable`](https://serenity-js.org/api/web/interface/Switchable/),
+     * such as a [`Page`](https://serenity-js.org/api/web/class/Page/) or a [`PageElement`](https://serenity-js.org/api/web/class/PageElement/),
+     * perform a sequence of `activities`, and then switch the context back.
+     *
+     * @param activities
+     *  A sequence of activities to perform
+     */
+    and(...activities) {
+        return new SwitchAndPerformActivities(this.switchable, activities);
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const switchable = await actor.answer(this.switchable);
+        await switchable.switchTo();
+    }
+}
+/**
+ * @package
+ */
+class SwitchAndPerformActivities extends Task {
+    switchable;
+    activities;
+    constructor(switchable, activities) {
+        super(the `#actor switches to ${switchable}`);
+        this.switchable = switchable;
+        this.activities = activities;
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const switchable = await actor.answer(this.switchable);
+        const origin = await switchable.switchTo();
+        await actor.attemptsTo(...this.activities);
+        await origin.switchBack();
+    }
+}
+//# sourceMappingURL=Switch.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Switch.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/Switch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,MAAM,OAAO,MAAO,SAAQ,WAAW;IAaI;IAXvC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,UAAkC;QACxC,OAAO,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAED,YAAuC,UAAkC;QACrE,KAAK,CAAC,GAAG,CAAA,sBAAuB,UAAW,EAAE,CAAC,CAAC;QADZ,eAAU,GAAV,UAAU,CAAwB;IAEzE,CAAC;IAED;;;;;;;;OAQG;IACH,GAAG,CAAC,GAAG,UAAsB;QACzB,OAAO,IAAI,0BAA0B,CAAC,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAuC;QACnD,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEvD,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC;IAChC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,0BAA2B,SAAQ,IAAI;IAEpB;IACA;IAFrB,YACqB,UAAkC,EAClC,UAAsB;QAEvC,KAAK,CAAC,GAAG,CAAC,sBAAuB,UAAW,EAAE,CAAC,CAAC;QAH/B,eAAU,GAAV,UAAU,CAAwB;QAClC,eAAU,GAAV,UAAU,CAAY;IAG3C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAAY;QAExB,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEvD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,QAAQ,EAAE,CAAC;QAE3C,MAAM,KAAK,CAAC,UAAU,CAClB,GAAG,IAAI,CAAC,UAAU,CACrB,CAAA;QAED,MAAM,MAAM,CAAC,UAAU,EAAE,CAAC;IAC9B,CAAC;CACJ"}

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

@@ -0,0 +1,47 @@
+import type { Answerable, AnswersQuestions, CollectsArtifacts, UsesAbilities } from '@serenity-js/core';
+import { Interaction } from '@serenity-js/core';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/)
+ * who has the [ability](https://serenity-js.org/api/core/class/Ability/)
+ * to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to take a screenshot and emit an artifact,
+ * which can then be persisted by [`ArtifactArchiver`](https://serenity-js.org/api/core/class/ArtifactArchiver/)
+ * and reported by [Serenity BDD reporter](https://serenity-js.org/api/serenity-bdd).
+ *
+ * #### Taking a screenshot
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Navigate, TakeScreenshot } from '@serenity-js/protractor';
+ *
+ * await actorCalled('Tania')
+ *   .attemptsTo(
+ *     Navigate.to('/app'),
+ *     TakeScreenshot.of('my app'),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`CollectsArtifacts`](https://serenity-js.org/api/core/interface/CollectsArtifacts/)
+ * - [`ArtifactArchiver`](https://serenity-js.org/api/core/class/ArtifactArchiver/)
+ *
+ * @group Activities
+ */
+export declare class TakeScreenshot extends Interaction {
+    private readonly name;
+    /**
+     * Instantiates this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
+     *
+     * @param name
+     *  The name to give the emitted artifact
+     */
+    static of(name: Answerable<string>): Interaction;
+    protected constructor(name: Answerable<string>);
+    /**
+     * @inheritDoc
+     */
+    performAs(actor: UsesAbilities & AnswersQuestions & CollectsArtifacts): Promise<void>;
+}
+//# sourceMappingURL=TakeScreenshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TakeScreenshot.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/TakeScreenshot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAE,WAAW,EAAO,MAAM,mBAAmB,CAAC;AAKrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAe,SAAQ,WAAW;IAYrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAV3C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,WAAW;IAIhD,SAAS,aAA8B,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;IAI/D;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAU9F"}

package/esm/screenplay/interactions/TakeScreenshot.js

@@ -0,0 +1,58 @@
+import { Interaction, the } from '@serenity-js/core';
+import { Name, Photo } from '@serenity-js/core/model';
+import { BrowseTheWeb } from '../abilities/index.js';
+/**
+ * Instructs an [actor](https://serenity-js.org/api/core/class/Actor/)
+ * who has the [ability](https://serenity-js.org/api/core/class/Ability/)
+ * to [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * to take a screenshot and emit an artifact,
+ * which can then be persisted by [`ArtifactArchiver`](https://serenity-js.org/api/core/class/ArtifactArchiver/)
+ * and reported by [Serenity BDD reporter](https://serenity-js.org/api/serenity-bdd).
+ *
+ * #### Taking a screenshot
+ *
+ * ```ts
+ * import { actorCalled } from '@serenity-js/core';
+ * import { Navigate, TakeScreenshot } from '@serenity-js/protractor';
+ *
+ * await actorCalled('Tania')
+ *   .attemptsTo(
+ *     Navigate.to('/app'),
+ *     TakeScreenshot.of('my app'),
+ *   )
+ * ```
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb`](https://serenity-js.org/api/web/class/BrowseTheWeb/)
+ * - [`CollectsArtifacts`](https://serenity-js.org/api/core/interface/CollectsArtifacts/)
+ * - [`ArtifactArchiver`](https://serenity-js.org/api/core/class/ArtifactArchiver/)
+ *
+ * @group Activities
+ */
+export class TakeScreenshot extends Interaction {
+    name;
+    /**
+     * Instantiates this [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
+     *
+     * @param name
+     *  The name to give the emitted artifact
+     */
+    static of(name) {
+        return new TakeScreenshot(name);
+    }
+    constructor(name) {
+        super(the `#actor takes a screenshot of ${name}`);
+        this.name = name;
+    }
+    /**
+     * @inheritDoc
+     */
+    async performAs(actor) {
+        const page = await BrowseTheWeb.as(actor).currentPage();
+        const screenshot = await page.takeScreenshot();
+        const name = await actor.answer(this.name);
+        actor.collect(Photo.fromBase64(screenshot), new Name(name));
+    }
+}
+//# sourceMappingURL=TakeScreenshot.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"TakeScreenshot.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/TakeScreenshot.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,cAAe,SAAQ,WAAW;IAYJ;IAVvC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,IAAwB;QAC9B,OAAO,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,YAAuC,IAAwB;QAC3D,KAAK,CAAC,GAAG,CAAA,gCAAiC,IAAK,EAAE,CAAC,CAAC;QADhB,SAAI,GAAJ,IAAI,CAAoB;IAE/D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,SAAS,CAAC,KAA2D;QACvE,MAAM,IAAI,GAAY,MAAM,YAAY,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QACjE,MAAM,UAAU,GAAM,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;QAClD,MAAM,IAAI,GAAY,MAAM,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEpD,KAAK,CAAC,OAAO,CACT,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC,EAC5B,IAAI,IAAI,CAAC,IAAI,CAAC,CACjB,CAAC;IACN,CAAC;CACJ"}

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

@@ -0,0 +1,16 @@
+export * from './Clear.js';
+export * from './Click.js';
+export * from './DoubleClick.js';
+export * from './Drag.js';
+export * from './Enter.js';
+export * from './ExecuteScript.js';
+export * from './Hover.js';
+export * from './Navigate.js';
+export * from './PageElementInteraction.js';
+export * from './Press.js';
+export * from './RightClick.js';
+export * from './Scroll.js';
+export * from './Select.js';
+export * from './Switch.js';
+export * from './TakeScreenshot.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}

package/esm/screenplay/interactions/index.js

@@ -0,0 +1,16 @@
+export * from './Clear.js';
+export * from './Click.js';
+export * from './DoubleClick.js';
+export * from './Drag.js';
+export * from './Enter.js';
+export * from './ExecuteScript.js';
+export * from './Hover.js';
+export * from './Navigate.js';
+export * from './PageElementInteraction.js';
+export * from './Press.js';
+export * from './RightClick.js';
+export * from './Scroll.js';
+export * from './Select.js';
+export * from './Switch.js';
+export * from './TakeScreenshot.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/interactions/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,6BAA6B,CAAC;AAC5C,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,qBAAqB,CAAC"}

package/esm/screenplay/models/ArgumentDehydrator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @group Models
+ */
+export declare class ArgumentDehydrator<T, U> {
+    private readonly shouldReference;
+    private readonly transformation;
+    constructor(shouldReference: (item: any) => item is T, transformation: (item: T) => U | Promise<U>);
+    dehydrate(inputArgs: Array<any>): Promise<[{
+        argsCount: number;
+        refsCount: number;
+    }, ...any[]]>;
+    private dehydrateRecursively;
+}
+//# sourceMappingURL=ArgumentDehydrator.d.ts.map

package/esm/screenplay/models/ArgumentDehydrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgumentDehydrator.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/ArgumentDehydrator.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,qBAAa,kBAAkB,CAAC,CAAC,EAAE,CAAC;IAE5B,OAAO,CAAC,QAAQ,CAAC,eAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc;gBADd,eAAe,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,IAAI,CAAC,EACzC,cAAc,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAInD,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAC,EAAE,GAAG,GAAG,EAAE,CAAE,CAAC;YAU/F,oBAAoB;CA+BrC"}

package/esm/screenplay/models/ArgumentDehydrator.js

@@ -0,0 +1,45 @@
+import { ValueInspector } from '@serenity-js/core/io';
+/**
+ * @group Models
+ */
+export class ArgumentDehydrator {
+    shouldReference;
+    transformation;
+    constructor(shouldReference, transformation) {
+        this.shouldReference = shouldReference;
+        this.transformation = transformation;
+    }
+    async dehydrate(inputArgs) {
+        const result = await this.dehydrateRecursively(inputArgs);
+        return [
+            { argsCount: result.args.length, refsCount: result.refsCount },
+            ...result.args,
+            ...result.refs
+        ];
+    }
+    async dehydrateRecursively(inputArgs, refsCount = 0) {
+        return inputArgs.reduce(async (acc, arg) => {
+            const { args, refs, refsCount } = await acc;
+            if (Array.isArray(arg)) {
+                const { args: nestedArgs, refs: nestedRefs, refsCount: currentRefsCount } = await this.dehydrateRecursively(arg, refsCount);
+                return {
+                    args: [...args, nestedArgs,],
+                    refs: [...refs, ...nestedRefs],
+                    refsCount: currentRefsCount,
+                };
+            }
+            if (ValueInspector.isPlainObject(arg)) {
+                const { args: nestedArgs, refs: nestedRefs, refsCount: currentRefsCount } = await this.dehydrateRecursively(Object.values(arg), refsCount);
+                return {
+                    args: [...args, Object.fromEntries(Object.keys(arg).map((key, i) => [key, nestedArgs[i]]))],
+                    refs: [...refs, ...nestedRefs],
+                    refsCount: currentRefsCount,
+                };
+            }
+            return this.shouldReference(arg)
+                ? { args: [...args, `$ref${refsCount}`], refs: [...refs, await this.transformation(arg)], refsCount: refsCount + 1 }
+                : { args: [...args, arg], refs, refsCount };
+        }, Promise.resolve({ args: [], refs: [], refsCount }));
+    }
+}
+//# sourceMappingURL=ArgumentDehydrator.js.map

package/esm/screenplay/models/ArgumentDehydrator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ArgumentDehydrator.js","sourceRoot":"","sources":["../../../src/screenplay/models/ArgumentDehydrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAWtD;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAEN;IACA;IAFrB,YACqB,eAAyC,EACzC,cAA2C;QAD3C,oBAAe,GAAf,eAAe,CAA0B;QACzC,mBAAc,GAAd,cAAc,CAA6B;IAEhE,CAAC;IAEM,KAAK,CAAC,SAAS,CAAC,SAAqB;QACxC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAE1D,OAAO;YACH,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE;YAC9D,GAAG,MAAM,CAAC,IAAI;YACd,GAAG,MAAM,CAAC,IAAI;SACjB,CAAC;IACN,CAAC;IAEO,KAAK,CAAC,oBAAoB,CAAC,SAAqB,EAAE,SAAS,GAAG,CAAC;QAKnE,OAAO,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;YACvC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,CAAC;YAE5C,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACrB,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;gBAC5H,OAAO;oBACH,IAAI,EAAE,CAAE,GAAG,IAAI,EAAE,UAAU,EAAG;oBAC9B,IAAI,EAAE,CAAE,GAAG,IAAI,EAAE,GAAG,UAAU,CAAE;oBAChC,SAAS,EAAE,gBAAgB;iBAC9B,CAAC;YACN,CAAC;YAED,IAAI,cAAc,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,gBAAgB,EAAE,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,CAAC,CAAC;gBAC3I,OAAO;oBACH,IAAI,EAAE,CAAE,GAAG,IAAI,EAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,CAAE,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAE;oBAC/F,IAAI,EAAE,CAAE,GAAG,IAAI,EAAE,GAAG,UAAU,CAAE;oBAChC,SAAS,EAAE,gBAAgB;iBAC9B,CAAC;YACN,CAAC;YAED,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC;gBAC5B,CAAC,CAAC,EAAE,IAAI,EAAE,CAAE,GAAG,IAAI,EAAE,OAAQ,SAAU,EAAE,CAAE,EAAE,IAAI,EAAE,CAAE,GAAG,IAAI,EAAE,MAAM,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAE,EAAE,SAAS,EAAE,SAAS,GAAG,CAAC,EAAE;gBAC1H,CAAC,CAAC,EAAE,IAAI,EAAE,CAAE,GAAG,IAAI,EAAE,GAAG,CAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACtD,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;CACJ"}

package/esm/screenplay/models/BrowserCapabilities.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Basic meta-data about the browser used in the test
+ *
+ * ## Learn more
+ *
+ * - [`BrowseTheWeb.browserCapabilities`](https://serenity-js.org/api/web/class/BrowseTheWeb/#browserCapabilities)
+ *
+ * @group Models
+ */
+export interface BrowserCapabilities {
+    /**
+     * Name of the operating system platform the test is executed on, like `darwin`, `linux` or `windows`.
+     */
+    platformName?: string;
+    /**
+     * Name of the Web browser the test is executed in, like `chrome`, `firefox` or `safari`.
+     */
+    browserName?: string;
+    /**
+     * Version number of the browser the test is executed in.
+     */
+    browserVersion?: string;
+}
+//# sourceMappingURL=BrowserCapabilities.d.ts.map

package/esm/screenplay/models/BrowserCapabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserCapabilities.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/BrowserCapabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAEhC;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B"}

package/esm/screenplay/models/BrowserCapabilities.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=BrowserCapabilities.js.map

package/esm/screenplay/models/BrowserCapabilities.js.map

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

package/esm/screenplay/models/BrowsingSession.d.ts

@@ -0,0 +1,74 @@
+import type { CorrelationId } from '@serenity-js/core/model';
+import type { BrowserCapabilities } from './BrowserCapabilities.js';
+import type { Page } from './Page.js';
+/**
+ * Represents the pages open in the current browsing context.
+ *
+ * You'll need to use this class directly only if you're planning to integrate Serenity/JS
+ * with a new Web integration tool.
+ *
+ * @group Models
+ */
+export declare abstract class BrowsingSession<Page_Type extends Page> {
+    protected currentBrowserPage: Page_Type;
+    protected readonly pages: Map<CorrelationId, Page_Type>;
+    closePagesOtherThan(pageOfInterest: Page_Type): Promise<void>;
+    /**
+     * Opens a new browser page and associates it with a [`Page`](https://serenity-js.org/api/web/class/Page/) object.
+     */
+    protected abstract registerCurrentPage(): Promise<Page_Type>;
+    /**
+     * Returns [basic meta-data](https://serenity-js.org/api/web/interface/BrowserCapabilities/) about the browser associated with this browsing session.
+     */
+    abstract browserCapabilities(): Promise<BrowserCapabilities>;
+    /**
+     * Returns a [`Page`](https://serenity-js.org/api/web/class/Page/) representing the currently active top-level browsing context.
+     */
+    currentPage(): Promise<Page_Type>;
+    /**
+     * Registers specified [pages](https://serenity-js.org/api/web/class/Page/) to be managed by this [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/).
+     *
+     * @param pages
+     */
+    register(...pages: Page_Type[]): void;
+    /**
+     * Informs this [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/) that it should no longer manage [pages](https://serenity-js.org/api/web/class/Page/)
+     * identified by the given `pageIds`.
+     *
+     * @param pageIds
+     */
+    deregister(...pageIds: CorrelationId[]): void;
+    /**
+     * Returns a [pages](https://serenity-js.org/api/web/class/Page/) representing all the available
+     * top-level browsing context, e.g. all the open browser tabs.
+     */
+    allPages(): Promise<Array<Page_Type>>;
+    /**
+     * Returns the ids of any [pages](https://serenity-js.org/api/web/class/Page/) this [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/) is aware of.
+     */
+    registeredPageIds(): Array<CorrelationId>;
+    /**
+     * Informs the [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/) that the "current page" has changed to `page`.
+     *
+     * Please note that different Web integration tools have a different definition of what a "current page" is.
+     * For example, Selenium or WebdriverIO use a single "focused" window that a developer
+     * needs to explicitly "switch to" in their tests in order to interact with it.
+     * This is similar to how a regular user would interact with Web pages;
+     * switching from one tab to another, but not interacting with more than one
+     * window/tab simultaneously.
+     *
+     * Playwright and Puppeteer, on the other hand, don't have a concept of the "current" page at all, since they
+     * allow the developer to interact with multiple open tabs/windows at the same time.
+     *
+     * Web integration-specific implementations of this class should override this method to define
+     * how the concept of the "current page" should be interpreted by Serenity/JS.
+     *
+     * @param page
+     */
+    changeCurrentPageTo(page: Page_Type): Promise<void>;
+    /**
+     * Closes all the pages available in this browsing context
+     */
+    closeAllPages(): Promise<void>;
+}
+//# sourceMappingURL=BrowsingSession.d.ts.map

package/esm/screenplay/models/BrowsingSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowsingSession.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/BrowsingSession.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;;;;;;GAOG;AACH,8BAAsB,eAAe,CAAC,SAAS,SAAS,IAAI;IACxD,SAAS,CAAC,kBAAkB,EAAE,SAAS,CAAC;IACxC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,CAAuC;IAExF,mBAAmB,CAAC,cAAc,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnE;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,IAAI,OAAO,CAAC,SAAS,CAAC;IAE5D;;OAEG;aACa,mBAAmB,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAEnE;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,SAAS,CAAC;IAQvC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI;IAMrC;;;;;OAKG;IACH,UAAU,CAAC,GAAG,OAAO,EAAE,aAAa,EAAE,GAAG,IAAI;IAM7C;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAI3C;;OAEG;IACH,iBAAiB,IAAI,KAAK,CAAC,aAAa,CAAC;IAIzC;;;;;;;;;;;;;;;;;OAiBG;IACG,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;CAQvC"}

package/esm/screenplay/models/BrowsingSession.js

@@ -0,0 +1,96 @@
+/**
+ * Represents the pages open in the current browsing context.
+ *
+ * You'll need to use this class directly only if you're planning to integrate Serenity/JS
+ * with a new Web integration tool.
+ *
+ * @group Models
+ */
+export class BrowsingSession {
+    currentBrowserPage;
+    pages = new Map();
+    async closePagesOtherThan(pageOfInterest) {
+        for (const page of await this.allPages()) {
+            if (!page.id.equals(pageOfInterest.id)) {
+                await page.close();
+                this.pages.delete(page.id);
+            }
+        }
+        await this.changeCurrentPageTo(pageOfInterest);
+    }
+    /**
+     * Returns a [`Page`](https://serenity-js.org/api/web/class/Page/) representing the currently active top-level browsing context.
+     */
+    async currentPage() {
+        if (!this.currentBrowserPage || !await this.currentBrowserPage.isPresent()) {
+            this.currentBrowserPage = await this.registerCurrentPage();
+        }
+        return this.currentBrowserPage;
+    }
+    /**
+     * Registers specified [pages](https://serenity-js.org/api/web/class/Page/) to be managed by this [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/).
+     *
+     * @param pages
+     */
+    register(...pages) {
+        for (const page of pages) {
+            this.pages.set(page.id, page);
+        }
+    }
+    /**
+     * Informs this [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/) that it should no longer manage [pages](https://serenity-js.org/api/web/class/Page/)
+     * identified by the given `pageIds`.
+     *
+     * @param pageIds
+     */
+    deregister(...pageIds) {
+        for (const pageId of pageIds) {
+            this.pages.delete(pageId);
+        }
+    }
+    /**
+     * Returns a [pages](https://serenity-js.org/api/web/class/Page/) representing all the available
+     * top-level browsing context, e.g. all the open browser tabs.
+     */
+    async allPages() {
+        return Array.from(this.pages.values());
+    }
+    /**
+     * Returns the ids of any [pages](https://serenity-js.org/api/web/class/Page/) this [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/) is aware of.
+     */
+    registeredPageIds() {
+        return Array.from(this.pages.keys());
+    }
+    /**
+     * Informs the [`BrowsingSession`](https://serenity-js.org/api/web/class/BrowsingSession/) that the "current page" has changed to `page`.
+     *
+     * Please note that different Web integration tools have a different definition of what a "current page" is.
+     * For example, Selenium or WebdriverIO use a single "focused" window that a developer
+     * needs to explicitly "switch to" in their tests in order to interact with it.
+     * This is similar to how a regular user would interact with Web pages;
+     * switching from one tab to another, but not interacting with more than one
+     * window/tab simultaneously.
+     *
+     * Playwright and Puppeteer, on the other hand, don't have a concept of the "current" page at all, since they
+     * allow the developer to interact with multiple open tabs/windows at the same time.
+     *
+     * Web integration-specific implementations of this class should override this method to define
+     * how the concept of the "current page" should be interpreted by Serenity/JS.
+     *
+     * @param page
+     */
+    async changeCurrentPageTo(page) {
+        this.currentBrowserPage = page;
+    }
+    /**
+     * Closes all the pages available in this browsing context
+     */
+    async closeAllPages() {
+        for (const page of this.pages.values()) {
+            await page.close();
+        }
+        this.pages.clear();
+        this.currentBrowserPage = undefined;
+    }
+}
+//# sourceMappingURL=BrowsingSession.js.map

package/esm/screenplay/models/BrowsingSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowsingSession.js","sourceRoot":"","sources":["../../../src/screenplay/models/BrowsingSession.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,OAAgB,eAAe;IACvB,kBAAkB,CAAY;IACrB,KAAK,GAAkC,IAAI,GAAG,EAA4B,CAAC;IAE9F,KAAK,CAAC,mBAAmB,CAAC,cAAyB;QAC/C,KAAK,MAAM,IAAI,IAAI,MAAM,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;YACvC,IAAI,CAAE,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC;gBACtC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;gBACnB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAC/B,CAAC;QACL,CAAC;QAED,MAAM,IAAI,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAC;IACnD,CAAC;IAYD;;OAEG;IACH,KAAK,CAAC,WAAW;QACb,IAAI,CAAE,IAAI,CAAC,kBAAkB,IAAI,CAAE,MAAM,IAAI,CAAC,kBAAkB,CAAC,SAAS,EAAE,EAAE,CAAC;YAC3E,IAAI,CAAC,kBAAkB,GAAG,MAAM,IAAI,CAAC,mBAAmB,EAAE,CAAC;QAC/D,CAAC;QAED,OAAO,IAAI,CAAC,kBAAkB,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACH,QAAQ,CAAC,GAAG,KAAkB;QAC1B,KAAI,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,GAAG,OAAwB;QAClC,KAAI,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ;QACV,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAgB,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,iBAAiB;QACb,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,mBAAmB,CAAC,IAAe;QACrC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACf,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACrC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACvB,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,kBAAkB,GAAG,SAAS,CAAC;IACxC,CAAC;CACJ"}