@serenity-js/web 3.22.4 → 3.23.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.23.0](https://github.com/serenity-js/serenity-js/compare/v3.22.4...v3.23.0) (2024-05-12)
+
+
+### Features
+
+* **webdriverio:** support for injecting scripts parameterised with complex data structures ([e920e67](https://github.com/serenity-js/serenity-js/commit/e920e6709262c8249c992ac02a01f49d5789a35d))
+* **web:** scripts injected into the browser accept data structures containing PageElement objects ([2fbddf5](https://github.com/serenity-js/serenity-js/commit/2fbddf5d78d2965aecd6786b020c93ea079bdaf1))
+
+
+
+
+
 ## [3.22.4](https://github.com/serenity-js/serenity-js/compare/v3.22.3...v3.22.4) (2024-05-07)
 
 **Note:** Version bump only for package @serenity-js/web

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

@@ -2,7 +2,7 @@ import type { Answerable, AnswersQuestions, CollectsArtifacts, UsesAbilities } f
 import { Interaction } from '@serenity-js/core';
 /**
  * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
- * to execute a script within the context of the current browser tab.
+ * to inject a script into the browser and execute it in the context of the current browser tab.
  *
  * ## Learn more
  *
@@ -63,6 +63,24 @@ export declare class ExecuteScript {
      * )
      * ```
      *
+     * #### Executing async script as function
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getText(header, callback) {
+     *     callback(header.innerText)
+     *   }).withArguments(MyPage.header())
+     * )
+     * ```
+     *
      * #### Passing arguments to an async script
      *
      * ```ts
@@ -82,32 +100,58 @@ export declare class ExecuteScript {
      * )
      * ```
      *
-     * #### Passing Target arguments to an async script
+     * #### Passing PageElement arguments to an async script
+     *
+     * Serenity/JS automatically converts {@link PageElement} objects passed as arguments to the script
+     * into their corresponding DOM elements.
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
-     * import { ExecuteScript } from '@serenity-js/web'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
      *
      * await actorCalled('Esti').attemptsTo(
      *   ExecuteScript.async(`
-     *     var header = arguments[0]        // PageElement object gets converted to a WebElement
+     *     var header = arguments[0]
      *     var callback = arguments[arguments.length - 1]
      *
      *     callback(header.innerText)
-     *   `).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     *   `).withArguments(MyPage.header())
      * )
      * ```
      *
-     * #### Executing async script as function
+     * #### Using nested data structures containing PageElement objects
+     *
+     * Serenity/JS automatically converts any {@link PageElement} objects
+     * contained in nested data structures passed to the script
+     * into their corresponding DOM elements.
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
-     * import { ExecuteScript } from '@serenity-js/web'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     *
+     *   article: () =>
+     *     PageElement.located(By.css('article')).describedAs('article'),
+     * }
      *
      * await actorCalled('Esti').attemptsTo(
-     *   ExecuteScript.async(function getText(header, callback) {
-     *     callback(header.innerText)
-     *   }).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     *   ExecuteScript.async(`
+     *     var { include, exclude }  = arguments[0]
+     *     var callback = arguments[arguments.length - 1]
+     *
+     *     callback(include[0].innerText)
+     *   `).withArguments({
+     *     include: [ MyPage.article() ],
+     *     exclude: [ MyPage.header() ],
+     *   })
      * )
      * ```
      *
@@ -138,34 +182,85 @@ export declare class ExecuteScript {
      *   )
      * ```
      *
-     * #### Executing a sync script as function and reading the result
+     * #### Executing a sync script as function and retrieving the result
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
      * import { By, Enter, ExecuteScript, LastScriptExecution, PageElement } from '@serenity-js/web'
      *
-     * const someOfferField = () =>
-     *   PageElement.located(By.id('offer-code'))
-     *     .describedAs('offer code')
+     * const Checkout = {
+     *   someOfferField: () =>
+     *     PageElement.located(By.id('offer-code'))
+     *       .describedAs('offer code')
      *
-     * const applyOfferCodeField = () =>
-     *   PageElement.located(By.id('apply-offer-code'))
-     *     .describedAs('apply offer field')
+     *   applyOfferCodeField = () =>
+     *     PageElement.located(By.id('apply-offer-code'))
+     *       .describedAs('apply offer field')
+     * }
      *
      * await actorCalled('Joseph')
      *   .attemptsTo(
      *     // inject JavaScript to read some property of an element
      *     ExecuteScript.sync(function getValue(element) {
      *         return element.value;
-     *     }).withArguments(someOfferField),
+     *     }).withArguments(Checkout.someOfferField()),
      *
      *     // use LastScriptExecution.result() to read the value
      *     // returned from the injected script
      *     // and pass it to another interaction
-     *     Enter.theValue(LastScriptExecution.result<string>()).into(applyOfferCodeField),
+     *     Enter.theValue(LastScriptExecution.result<string>()).into(Checkout.applyOfferCodeField()),
      *   )
      * ```
      *
+     * #### Passing PageElement arguments to a sync script
+     *
+     * Serenity/JS automatically converts {@link PageElement} objects passed as arguments to the script
+     * into their corresponding DOM elements.
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.sync(function getInnerHtml(element) {
+     *     return element.innerHTML;
+     *   }).withArguments(MyPage.header())
+     * )
+     * ```
+     *
+     * #### Using nested data structures containing PageElement objects
+     *
+     * Serenity/JS automatically converts any {@link PageElement} objects
+     * contained in nested data structures passed to the script
+     * into their corresponding DOM elements.
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     *
+     *   article: () =>
+     *     PageElement.located(By.css('article')).describedAs('article'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getInnerHtml(scope) {
+     *     return scope.include[0].innerHTML;
+     *   `).withArguments({
+     *     include: [ MyPage.article() ],
+     *     exclude: [ MyPage.header() ],
+     *   })
+     * )
+     * ```
+     *
      * #### Learn more
      * - {@apilink LastScriptExecution.result}
      *

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

@@ -1 +1 @@
-{"version":3,"file":"ExecuteScript.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/ExecuteScript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAK,WAAW,EAAc,MAAM,mBAAmB,CAAC;AAM/D;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IAEtB;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,WAAW;IAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgGG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,0BAA0B;IAOnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,0BAA0B;CAMrE;AAED;;;;;;;GAOG;AACH,8BAAsB,0BAA2B,SAAQ,WAAW;IAI5D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAC5C,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBAF/C,WAAW,EAAE,MAAM,EACA,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAY,mDAAmD;IACxF,IAAI,GAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAM;IAKxD;;;;;OAKG;aACa,aAAa,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW;IAE3E;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3F,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;CACnG"}
+{"version":3,"file":"ExecuteScript.d.ts","sourceRoot":"","sources":["../../../src/screenplay/interactions/ExecuteScript.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACxG,OAAO,EAAK,WAAW,EAAc,MAAM,mBAAmB,CAAC;AAM/D;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IAEtB;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,GAAG,WAAW;IAIvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4IG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,0BAA0B;IAOnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwGG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,0BAA0B;CAMrE;AAED;;;;;;;GAOG;AACH,8BAAsB,0BAA2B,SAAQ,WAAW;IAI5D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ;IAC5C,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;gBAF/C,WAAW,EAAE,MAAM,EACA,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAY,mDAAmD;IACxF,IAAI,GAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAM;IAKxD;;;;;OAKG;aACa,aAAa,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW;IAE3E;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3F,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC;CACnG"}

package/lib/screenplay/interactions/ExecuteScript.js

@@ -7,7 +7,7 @@ const model_1 = require("@serenity-js/core/lib/model");
 const abilities_1 = require("../abilities");
 /**
  * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
- * to execute a script within the context of the current browser tab.
+ * to inject a script into the browser and execute it in the context of the current browser tab.
  *
  * ## Learn more
  *
@@ -70,6 +70,24 @@ class ExecuteScript {
      * )
      * ```
      *
+     * #### Executing async script as function
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getText(header, callback) {
+     *     callback(header.innerText)
+     *   }).withArguments(MyPage.header())
+     * )
+     * ```
+     *
      * #### Passing arguments to an async script
      *
      * ```ts
@@ -89,32 +107,58 @@ class ExecuteScript {
      * )
      * ```
      *
-     * #### Passing Target arguments to an async script
+     * #### Passing PageElement arguments to an async script
+     *
+     * Serenity/JS automatically converts {@link PageElement} objects passed as arguments to the script
+     * into their corresponding DOM elements.
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
-     * import { ExecuteScript } from '@serenity-js/web'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
      *
      * await actorCalled('Esti').attemptsTo(
      *   ExecuteScript.async(`
-     *     var header = arguments[0]        // PageElement object gets converted to a WebElement
+     *     var header = arguments[0]
      *     var callback = arguments[arguments.length - 1]
      *
      *     callback(header.innerText)
-     *   `).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     *   `).withArguments(MyPage.header())
      * )
      * ```
      *
-     * #### Executing async script as function
+     * #### Using nested data structures containing PageElement objects
+     *
+     * Serenity/JS automatically converts any {@link PageElement} objects
+     * contained in nested data structures passed to the script
+     * into their corresponding DOM elements.
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
-     * import { ExecuteScript } from '@serenity-js/web'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     *
+     *   article: () =>
+     *     PageElement.located(By.css('article')).describedAs('article'),
+     * }
      *
      * await actorCalled('Esti').attemptsTo(
-     *   ExecuteScript.async(function getText(header, callback) {
-     *     callback(header.innerText)
-     *   }).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     *   ExecuteScript.async(`
+     *     var { include, exclude }  = arguments[0]
+     *     var callback = arguments[arguments.length - 1]
+     *
+     *     callback(include[0].innerText)
+     *   `).withArguments({
+     *     include: [ MyPage.article() ],
+     *     exclude: [ MyPage.header() ],
+     *   })
      * )
      * ```
      *
@@ -147,34 +191,85 @@ class ExecuteScript {
      *   )
      * ```
      *
-     * #### Executing a sync script as function and reading the result
+     * #### Executing a sync script as function and retrieving the result
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
      * import { By, Enter, ExecuteScript, LastScriptExecution, PageElement } from '@serenity-js/web'
      *
-     * const someOfferField = () =>
-     *   PageElement.located(By.id('offer-code'))
-     *     .describedAs('offer code')
+     * const Checkout = {
+     *   someOfferField: () =>
+     *     PageElement.located(By.id('offer-code'))
+     *       .describedAs('offer code')
      *
-     * const applyOfferCodeField = () =>
-     *   PageElement.located(By.id('apply-offer-code'))
-     *     .describedAs('apply offer field')
+     *   applyOfferCodeField = () =>
+     *     PageElement.located(By.id('apply-offer-code'))
+     *       .describedAs('apply offer field')
+     * }
      *
      * await actorCalled('Joseph')
      *   .attemptsTo(
      *     // inject JavaScript to read some property of an element
      *     ExecuteScript.sync(function getValue(element) {
      *         return element.value;
-     *     }).withArguments(someOfferField),
+     *     }).withArguments(Checkout.someOfferField()),
      *
      *     // use LastScriptExecution.result() to read the value
      *     // returned from the injected script
      *     // and pass it to another interaction
-     *     Enter.theValue(LastScriptExecution.result<string>()).into(applyOfferCodeField),
+     *     Enter.theValue(LastScriptExecution.result<string>()).into(Checkout.applyOfferCodeField()),
      *   )
      * ```
      *
+     * #### Passing PageElement arguments to a sync script
+     *
+     * Serenity/JS automatically converts {@link PageElement} objects passed as arguments to the script
+     * into their corresponding DOM elements.
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.sync(function getInnerHtml(element) {
+     *     return element.innerHTML;
+     *   }).withArguments(MyPage.header())
+     * )
+     * ```
+     *
+     * #### Using nested data structures containing PageElement objects
+     *
+     * Serenity/JS automatically converts any {@link PageElement} objects
+     * contained in nested data structures passed to the script
+     * into their corresponding DOM elements.
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     *
+     *   article: () =>
+     *     PageElement.located(By.css('article')).describedAs('article'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getInnerHtml(scope) {
+     *     return scope.include[0].innerHTML;
+     *   `).withArguments({
+     *     include: [ MyPage.article() ],
+     *     exclude: [ MyPage.header() ],
+     *   })
+     * )
+     * ```
+     *
      * #### Learn more
      * - {@apilink LastScriptExecution.result}
      *

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

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

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

@@ -0,0 +1,11 @@
+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/lib/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,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/lib/screenplay/models/ArgumentDehydrator.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArgumentDehydrator = void 0;
+const io_1 = require("@serenity-js/core/lib/io");
+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 ((0, io_1.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 }));
+    }
+}
+exports.ArgumentDehydrator = ArgumentDehydrator;
+//# sourceMappingURL=ArgumentDehydrator.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ArgumentDehydrator.js","sourceRoot":"","sources":["../../../src/screenplay/models/ArgumentDehydrator.ts"],"names":[],"mappings":";;;AAAA,iDAAyD;AAWzD,MAAa,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;gBACpB,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;aACL;YAED,IAAI,IAAA,kBAAa,EAAC,GAAG,CAAC,EAAE;gBACpB,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;aACL;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;AAhDD,gDAgDC"}

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

@@ -1,3 +1,4 @@
+export * from './ArgumentDehydrator';
 export * from './BrowserCapabilities';
 export * from './BrowsingSession';
 export * from './Cookie';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,OAAO,CAAC;AACtB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC"}

package/lib/screenplay/models/index.js

@@ -14,6 +14,7 @@ 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("./ArgumentDehydrator"), exports);
 __exportStar(require("./BrowserCapabilities"), exports);
 __exportStar(require("./BrowsingSession"), exports);
 __exportStar(require("./Cookie"), exports);

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,wDAAsC;AACtC,oDAAkC;AAClC,2CAAyB;AACzB,+CAA6B;AAC7B,4CAA0B;AAC1B,wCAAsB;AACtB,4CAA0B;AAC1B,yCAAuB;AACvB,gDAA8B;AAC9B,iDAA+B;AAC/B,wDAAsC;AACtC,gDAA8B;AAC9B,iDAA+B;AAC/B,8CAA4B;AAC5B,+CAA6B;AAC7B,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/screenplay/models/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC;AACrC,wDAAsC;AACtC,oDAAkC;AAClC,2CAAyB;AACzB,+CAA6B;AAC7B,4CAA0B;AAC1B,wCAAsB;AACtB,4CAA0B;AAC1B,yCAAuB;AACvB,gDAA8B;AAC9B,iDAA+B;AAC/B,wDAAsC;AACtC,gDAA8B;AAC9B,iDAA+B;AAC/B,8CAA4B;AAC5B,+CAA6B;AAC7B,qDAAmC"}

package/lib/scripts/index.d.ts

@@ -1,2 +1,3 @@
 export * from './isVisible';
+export * from './rehydrate';
 //# sourceMappingURL=index.d.ts.map

package/lib/scripts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC"}

package/lib/scripts/index.js

@@ -15,4 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./isVisible"), exports);
+__exportStar(require("./rehydrate"), exports);
 //# sourceMappingURL=index.js.map

package/lib/scripts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/scripts/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,8CAA4B"}

package/lib/scripts/rehydrate.d.ts

@@ -0,0 +1,5 @@
+export declare function rehydrate(...result: [{
+    argsCount: number;
+    refsCount: number;
+}, ...any[]]): Array<any>;
+//# sourceMappingURL=rehydrate.d.ts.map

package/lib/scripts/rehydrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.d.ts","sourceRoot":"","sources":["../../src/scripts/rehydrate.ts"],"names":[],"mappings":"AAEA,wBAAgB,SAAS,CAAC,GAAG,MAAM,EAAE,CAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,GAAG,EAAE,CAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAmCvG"}

package/lib/scripts/rehydrate.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rehydrate = void 0;
+/* eslint-disable unicorn/consistent-function-scoping */
+// todo: instead of manually including isPlainObject, each script from web/lib/scripts should be pre-built and included in the global browser scope
+function rehydrate(...result) {
+    function isPlainObject(v) {
+        if (typeof v === 'object' && v !== null) {
+            if (typeof Object.getPrototypeOf === 'function') {
+                const proto = Object.getPrototypeOf(v);
+                return proto === Object.prototype || proto === null;
+            }
+            return Object.prototype.toString.call(v) === '[object Object]';
+        }
+        return false;
+    }
+    function rehydrateRecursively(arg, refs) {
+        if (Array.isArray(arg)) {
+            return arg.map(item => rehydrateRecursively(item, refs));
+        }
+        if (isPlainObject(arg)) {
+            return Object.fromEntries(Object.entries(arg)
+                .map(([key, value]) => [key, rehydrateRecursively(value, refs)]));
+        }
+        if (typeof arg === 'string' && arg.startsWith('$ref')) {
+            return refs[Number.parseInt(arg.replace('$ref', ''), 10)];
+        }
+        return arg;
+    }
+    const [{ argsCount }, ...items] = result;
+    const args = items.slice(0, argsCount);
+    const refs = items.slice(argsCount);
+    return args.map(arg => rehydrateRecursively(arg, refs));
+}
+exports.rehydrate = rehydrate;
+//# sourceMappingURL=rehydrate.js.map

package/lib/scripts/rehydrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rehydrate.js","sourceRoot":"","sources":["../../src/scripts/rehydrate.ts"],"names":[],"mappings":";;;AAAA,wDAAwD;AACxD,mJAAmJ;AACnJ,SAAgB,SAAS,CAAC,GAAG,MAA8D;IACvF,SAAS,aAAa,CAAC,CAAU;QAC7B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,EAAE;YACrC,IAAI,OAAO,MAAM,CAAC,cAAc,KAAK,UAAU,EAAE;gBAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;gBACvC,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;aACvD;YACD,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,iBAAiB,CAAC;SAClE;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,SAAS,oBAAoB,CAAC,GAAQ,EAAE,IAAW;QAC/C,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;YACpB,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;SAC5D;QACD,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE;YACpB,OAAO,MAAM,CAAC,WAAW,CACrB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;iBACd,GAAG,CAAC,CAAC,CAAE,GAAG,EAAE,KAAK,CAAE,EAAE,EAAE,CAAC,CAAE,GAAG,EAAE,oBAAoB,CAAC,KAAK,EAAE,IAAI,CAAC,CAAE,CAAC,CAC3E,CAAC;SACL;QACD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE;YACnD,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;SAC7D;QAED,OAAO,GAAG,CAAC;IACf,CAAC;IAED,MAAM,CAAE,EAAE,SAAS,EAAE,EAAE,GAAG,KAAK,CAAE,GAAG,MAAM,CAAC;IAE3C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAEpC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAC5D,CAAC;AAnCD,8BAmCC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serenity-js/web",
-  "version": "3.22.4",
+  "version": "3.23.0",
   "description": "Serenity/JS Screenplay Pattern APIs for the Web",
   "author": {
     "name": "Jan Molak",
@@ -45,8 +45,8 @@
     "node": "^16.13 || ^18.12 || ^20"
   },
   "dependencies": {
-    "@serenity-js/assertions": "3.22.4",
-    "@serenity-js/core": "3.22.4",
+    "@serenity-js/assertions": "3.23.0",
+    "@serenity-js/core": "3.23.0",
     "tiny-types": "1.22.0"
   },
   "devDependencies": {
@@ -59,5 +59,5 @@
     "ts-node": "10.9.2",
     "typescript": "5.2.2"
   },
-  "gitHead": "f5db024cf16bf75489b55253dec6ef6e66114728"
+  "gitHead": "be1bb276388c295df01146eb8589a003b3d8214c"
 }

package/src/screenplay/interactions/ExecuteScript.ts

@@ -7,7 +7,7 @@ import { BrowseTheWeb } from '../abilities';
 
 /**
  * Instructs an {@apilink Actor|actor} who has the {@apilink Ability|ability} to {@apilink BrowseTheWeb}
- * to execute a script within the context of the current browser tab.
+ * to inject a script into the browser and execute it in the context of the current browser tab.
  *
  * ## Learn more
  *
@@ -72,6 +72,24 @@ export class ExecuteScript {
      * )
      * ```
      *
+     * #### Executing async script as function
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getText(header, callback) {
+     *     callback(header.innerText)
+     *   }).withArguments(MyPage.header())
+     * )
+     * ```
+     *
      * #### Passing arguments to an async script
      *
      * ```ts
@@ -91,32 +109,58 @@ export class ExecuteScript {
      * )
      * ```
      *
-     * #### Passing Target arguments to an async script
+     * #### Passing PageElement arguments to an async script
+     *
+     * Serenity/JS automatically converts {@link PageElement} objects passed as arguments to the script
+     * into their corresponding DOM elements.
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
-     * import { ExecuteScript } from '@serenity-js/web'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
      *
      * await actorCalled('Esti').attemptsTo(
      *   ExecuteScript.async(`
-     *     var header = arguments[0]        // PageElement object gets converted to a WebElement
+     *     var header = arguments[0]
      *     var callback = arguments[arguments.length - 1]
      *
      *     callback(header.innerText)
-     *   `).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     *   `).withArguments(MyPage.header())
      * )
      * ```
      *
-     * #### Executing async script as function
+     * #### Using nested data structures containing PageElement objects
+     *
+     * Serenity/JS automatically converts any {@link PageElement} objects
+     * contained in nested data structures passed to the script
+     * into their corresponding DOM elements.
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
-     * import { ExecuteScript } from '@serenity-js/web'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     *
+     *   article: () =>
+     *     PageElement.located(By.css('article')).describedAs('article'),
+     * }
      *
      * await actorCalled('Esti').attemptsTo(
-     *   ExecuteScript.async(function getText(header, callback) {
-     *     callback(header.innerText)
-     *   }).withArguments(PageElement.located(By.css('h1')).describedAs('header'))
+     *   ExecuteScript.async(`
+     *     var { include, exclude }  = arguments[0]
+     *     var callback = arguments[arguments.length - 1]
+     *
+     *     callback(include[0].innerText)
+     *   `).withArguments({
+     *     include: [ MyPage.article() ],
+     *     exclude: [ MyPage.header() ],
+     *   })
      * )
      * ```
      *
@@ -153,34 +197,85 @@ export class ExecuteScript {
      *   )
      * ```
      *
-     * #### Executing a sync script as function and reading the result
+     * #### Executing a sync script as function and retrieving the result
      *
      * ```ts
      * import { actorCalled } from '@serenity-js/core'
      * import { By, Enter, ExecuteScript, LastScriptExecution, PageElement } from '@serenity-js/web'
      *
-     * const someOfferField = () =>
-     *   PageElement.located(By.id('offer-code'))
-     *     .describedAs('offer code')
+     * const Checkout = {
+     *   someOfferField: () =>
+     *     PageElement.located(By.id('offer-code'))
+     *       .describedAs('offer code')
      *
-     * const applyOfferCodeField = () =>
-     *   PageElement.located(By.id('apply-offer-code'))
-     *     .describedAs('apply offer field')
+     *   applyOfferCodeField = () =>
+     *     PageElement.located(By.id('apply-offer-code'))
+     *       .describedAs('apply offer field')
+     * }
      *
      * await actorCalled('Joseph')
      *   .attemptsTo(
      *     // inject JavaScript to read some property of an element
      *     ExecuteScript.sync(function getValue(element) {
      *         return element.value;
-     *     }).withArguments(someOfferField),
+     *     }).withArguments(Checkout.someOfferField()),
      *
      *     // use LastScriptExecution.result() to read the value
      *     // returned from the injected script
      *     // and pass it to another interaction
-     *     Enter.theValue(LastScriptExecution.result<string>()).into(applyOfferCodeField),
+     *     Enter.theValue(LastScriptExecution.result<string>()).into(Checkout.applyOfferCodeField()),
      *   )
      * ```
      *
+     * #### Passing PageElement arguments to a sync script
+     *
+     * Serenity/JS automatically converts {@link PageElement} objects passed as arguments to the script
+     * into their corresponding DOM elements.
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.sync(function getInnerHtml(element) {
+     *     return element.innerHTML;
+     *   }).withArguments(MyPage.header())
+     * )
+     * ```
+     *
+     * #### Using nested data structures containing PageElement objects
+     *
+     * Serenity/JS automatically converts any {@link PageElement} objects
+     * contained in nested data structures passed to the script
+     * into their corresponding DOM elements.
+     *
+     * ```ts
+     * import { actorCalled } from '@serenity-js/core'
+     * import { ExecuteScript, PageElement } from '@serenity-js/web'
+     *
+     * const MyPage = {
+     *   header: () =>
+     *     PageElement.located(By.css('h1')).describedAs('header'),
+     *
+     *   article: () =>
+     *     PageElement.located(By.css('article')).describedAs('article'),
+     * }
+     *
+     * await actorCalled('Esti').attemptsTo(
+     *   ExecuteScript.async(function getInnerHtml(scope) {
+     *     return scope.include[0].innerHTML;
+     *   `).withArguments({
+     *     include: [ MyPage.article() ],
+     *     exclude: [ MyPage.header() ],
+     *   })
+     * )
+     * ```
+     *
      * #### Learn more
      * - {@apilink LastScriptExecution.result}
      *

package/src/screenplay/models/ArgumentDehydrator.ts

@@ -0,0 +1,60 @@
+import { isPlainObject } from '@serenity-js/core/lib/io';
+
+/* eslint-disable @typescript-eslint/indent */
+type TransformedArgument<T, U> =
+    T extends Array<infer E> ? Array<TransformedArgument<E, U>> :
+    T extends object ? { [K in keyof T]: TransformedArgument<T[K], U> }
+    : U;
+/* eslint-enable */
+
+type RefId = `$ref${number}`;
+
+export class ArgumentDehydrator<T, U> {
+    constructor(
+        private readonly shouldReference: (item: any) => item is T,
+        private readonly transformation: (item: T) => U | Promise<U>,
+    ) {
+    }
+
+    public async dehydrate(inputArgs: Array<any>): Promise<[ { argsCount: number, refsCount: number}, ...any[] ]> {
+        const result = await this.dehydrateRecursively(inputArgs);
+
+        return [
+            { argsCount: result.args.length, refsCount: result.refsCount },
+            ...result.args,
+            ...result.refs
+        ];
+    }
+
+    private async dehydrateRecursively(inputArgs: Array<any>, refsCount = 0): Promise<{
+        args: Array<TransformedArgument<T, RefId>>;
+        refs: Array<U>;
+        refsCount: number;
+    }> {
+        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 (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 }));
+    }
+}

package/src/screenplay/models/index.ts

@@ -1,3 +1,4 @@
+export * from './ArgumentDehydrator';
 export * from './BrowserCapabilities';
 export * from './BrowsingSession';
 export * from './Cookie';

package/src/scripts/index.ts

@@ -1 +1,2 @@
 export * from './isVisible';
+export * from './rehydrate';

package/src/scripts/rehydrate.ts

@@ -0,0 +1,38 @@
+/* eslint-disable unicorn/consistent-function-scoping */
+// todo: instead of manually including isPlainObject, each script from web/lib/scripts should be pre-built and included in the global browser scope
+export function rehydrate(...result: [ { argsCount: number; refsCount: number }, ...any[] ]): Array<any> {
+    function isPlainObject(v: unknown): v is object {   // eslint-disable-line @typescript-eslint/ban-types
+        if (typeof v === 'object' && v !== null) {
+            if (typeof Object.getPrototypeOf === 'function') {
+                const proto = Object.getPrototypeOf(v);
+                return proto === Object.prototype || proto === null;
+            }
+            return Object.prototype.toString.call(v) === '[object Object]';
+        }
+        return false;
+    }
+
+    function rehydrateRecursively(arg: any, refs: any[]): any {
+        if (Array.isArray(arg)) {
+            return arg.map(item => rehydrateRecursively(item, refs));
+        }
+        if (isPlainObject(arg)) {
+            return Object.fromEntries(
+                Object.entries(arg)
+                    .map(([ key, value ]) => [ key, rehydrateRecursively(value, refs) ])
+            );
+        }
+        if (typeof arg === 'string' && arg.startsWith('$ref')) {
+            return refs[Number.parseInt(arg.replace('$ref', ''), 10)];
+        }
+
+        return arg;
+    }
+
+    const [ { argsCount }, ...items ] = result;
+
+    const args = items.slice(0, argsCount);
+    const refs = items.slice(argsCount);
+
+    return args.map(arg => rehydrateRecursively(arg, refs));
+}