@serenity-js/web - npm Package Compare versions

Comparing version 3.22.4 to 3.23.0

CHANGELOG.md

@@ -6,2 +6,14 @@ # Change Log
 
+# [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)
@@ -8,0 +20,0 @@

lib/screenplay/interactions/ExecuteScript.d.ts

@@ -5,3 +5,3 @@ import type { Answerable, AnswersQuestions, CollectsArtifacts, UsesAbilities } 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.
  *
@@ -67,2 +67,20 @@ * ## Learn more
      *
+     * #### 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
@@ -87,28 +105,54 @@ *
      *
-     * #### 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() ],
+     *   })
      * )
@@ -144,3 +188,3 @@ * ```
      *
-     * #### Executing a sync script as function and reading the result
+     * #### Executing a sync script as function and retrieving the result
      *
@@ -151,9 +195,11 @@ * ```ts
      *
-     * 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')
+     * }
      *
@@ -165,3 +211,3 @@ * await actorCalled('Joseph')
      *         return element.value;
-     *     }).withArguments(someOfferField),
+     *     }).withArguments(Checkout.someOfferField()),
      *
@@ -171,6 +217,55 @@ *     // use LastScriptExecution.result() to read the value
      *     // 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
@@ -177,0 +272,0 @@ * - {@apilink LastScriptExecution.result}

lib/screenplay/interactions/ExecuteScript.js

@@ -10,3 +10,3 @@ "use strict";
  * 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.
  *
@@ -74,2 +74,20 @@ * ## Learn more
      *
+     * #### 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
@@ -94,28 +112,54 @@ *
      *
-     * #### 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,3 +197,3 @@ * ```
      *
-     * #### Executing a sync script as function and reading the result
+     * #### Executing a sync script as function and retrieving the result
      *
@@ -160,9 +204,11 @@ * ```ts
      *
-     * 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')
+     * }
      *
@@ -174,3 +220,3 @@ * await actorCalled('Joseph')
      *         return element.value;
-     *     }).withArguments(someOfferField),
+     *     }).withArguments(Checkout.someOfferField()),
      *
@@ -180,6 +226,55 @@ *     // use LastScriptExecution.result() to read the value
      *     // 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
@@ -186,0 +281,0 @@ * - {@apilink LastScriptExecution.result}

lib/screenplay/models/index.d.ts

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

lib/screenplay/models/index.js

@@ -17,2 +17,3 @@ "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ArgumentDehydrator"), exports);
 __exportStar(require("./BrowserCapabilities"), exports);
@@ -19,0 +20,0 @@ __exportStar(require("./BrowsingSession"), exports);

lib/scripts/index.d.ts

 export * from './isVisible';
+export * from './rehydrate';
 //# sourceMappingURL=index.d.ts.map

lib/scripts/index.js

@@ -18,2 +18,3 @@ "use strict";
 __exportStar(require("./isVisible"), exports);
+__exportStar(require("./rehydrate"), exports);
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "@serenity-js/web",
-  "version": "3.22.4",
+  "version": "3.23.0",
   "description": "Serenity/JS Screenplay Pattern APIs for the Web",
@@ -48,4 +48,4 @@ "author": {
   "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"
@@ -63,3 +63,3 @@ },
   },
-  "gitHead": "f5db024cf16bf75489b55253dec6ef6e66114728"
+  "gitHead": "be1bb276388c295df01146eb8589a003b3d8214c"
 }

src/screenplay/interactions/ExecuteScript.ts

@@ -10,3 +10,3 @@ import type { Answerable, AnswersQuestions, CollectsArtifacts, UsesAbilities } 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.
  *
@@ -76,2 +76,20 @@ * ## Learn more
      *
+     * #### 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
@@ -96,28 +114,54 @@ *
      *
-     * #### 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() ],
+     *   })
      * )
@@ -159,3 +203,3 @@ * ```
      *
-     * #### Executing a sync script as function and reading the result
+     * #### Executing a sync script as function and retrieving the result
      *
@@ -166,9 +210,11 @@ * ```ts
      *
-     * 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')
+     * }
      *
@@ -180,3 +226,3 @@ * await actorCalled('Joseph')
      *         return element.value;
-     *     }).withArguments(someOfferField),
+     *     }).withArguments(Checkout.someOfferField()),
      *
@@ -186,6 +232,55 @@ *     // use LastScriptExecution.result() to read the value
      *     // 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
@@ -192,0 +287,0 @@ * - {@apilink LastScriptExecution.result}

src/screenplay/models/index.ts

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

src/scripts/index.ts

 export * from './isVisible';
+export * from './rehydrate';

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

746432

increased by3.14%

Number of package files

406

increased by2.53%

Lines of code

15859

increased by3.05%

Dependency changes

• + Added@serenity-js/assertions@3.23.0(transitive)

• + Added@serenity-js/core@3.23.0(transitive)

• + Addedsemver@7.6.2(transitive)

• - Removed@serenity-js/assertions@3.22.4(transitive)

• - Removed@serenity-js/core@3.22.4(transitive)

• - Removedlru-cache@6.0.0(transitive)

• - Removedsemver@7.6.0(transitive)

• - Removedyallist@4.0.0(transitive)

• Updated@serenity-js/assertions@3.23.0

• Updated@serenity-js/core@3.23.0