@serenity-js/web - npm Package Compare versions

Comparing version 3.6.1 to 3.7.0

CHANGELOG.md

@@ -6,2 +6,13 @@ # Change Log
 
+# [3.7.0](https://github.com/serenity-js/serenity-js/compare/v3.6.1...v3.7.0) (2023-07-20)
+
+
+### Features
+
+* **web:** new PageElement Query Language API - parentElement.closestTo(childElement) ([7d48fd8](https://github.com/serenity-js/serenity-js/commit/7d48fd8c1dcda6cbd5f8d0579e4cce129b24618f))
+
+
+
+
+
 ## [3.6.1](https://github.com/serenity-js/serenity-js/compare/v3.6.0...v3.6.1) (2023-07-11)
@@ -8,0 +19,0 @@

lib/screenplay/models/Locator.d.ts

@@ -5,3 +5,3 @@ /// <reference types="node" />
 import { RootLocator } from './RootLocator';
-import type { Selector } from './selectors';
+import { ByCss, type Selector } from './selectors';
 /**
@@ -30,3 +30,14 @@ * {@apilink Locator} uses a {@apilink Selector} to locate a {@apilink PageElement} or {@apilink PageElements}
     abstract of(parent: RootLocator<Native_Element_Type>): Locator<Native_Element_Type>;
+    abstract closestTo(child: Locator<Native_Element_Type>): Locator<Native_Element_Type>;
     abstract locate(child: Locator<Native_Element_Type>): Locator<Native_Element_Type>;
+    /**
+     * Expresses {@apilink ByCss}, {@apilink ById}, or {@apilink ByTagName} as a {@apilink ByCss} selector.
+     *
+     * @throws LogicError
+     *  if the `selector` can't be expressed as {@apilink ByCss}
+     *
+     * @param selector
+     * @protected
+     */
+    protected asCssSelector(selector: Selector): ByCss;
     abstract element(): PageElement<Native_Element_Type>;
@@ -33,0 +44,0 @@ abstract allElements(): Promise<Array<PageElement<Native_Element_Type>>>;

lib/screenplay/models/Locator.js

@@ -28,5 +28,7 @@ "use strict";
 exports.Locator = void 0;
+const core_1 = require("@serenity-js/core");
 const io_1 = require("@serenity-js/core/lib/io");
 const util = __importStar(require("util")); // eslint-disable-line unicorn/import-style
 const RootLocator_1 = require("./RootLocator");
+const selectors_1 = require("./selectors");
 /**
@@ -63,2 +65,23 @@ * {@apilink Locator} uses a {@apilink Selector} to locate a {@apilink PageElement} or {@apilink PageElements}
     }
+    /**
+     * Expresses {@apilink ByCss}, {@apilink ById}, or {@apilink ByTagName} as a {@apilink ByCss} selector.
+     *
+     * @throws LogicError
+     *  if the `selector` can't be expressed as {@apilink ByCss}
+     *
+     * @param selector
+     * @protected
+     */
+    asCssSelector(selector) {
+        if (selector instanceof selectors_1.ByCss) {
+            return selector;
+        }
+        if (selector instanceof selectors_1.ById) {
+            return new selectors_1.ByCss(`#${selector.value}`);
+        }
+        if (selector instanceof selectors_1.ByTagName) {
+            return new selectors_1.ByCss(`${selector.value}`);
+        }
+        throw new core_1.LogicError(`${selector} can't be expressed as a CSS selector`);
+    }
     toString() {
@@ -65,0 +88,0 @@ return this.selector.toString();

lib/screenplay/models/PageElement.d.ts

@@ -24,4 +24,60 @@ import type { Answerable, MetaQuestion, Optional, QuestionAdapter } from '@serenity-js/core';
     constructor(locator: Locator<Native_Element_Type>);
+    /**
+     * Locates a child element that:
+     * - matches the given selector
+     * - is located within the `parentElement`
+     *
+     * @param parentElement
+     */
     abstract of(parentElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
     /**
+     * Traverses the element and its parents, heading toward the document root,
+     * until it finds a parent {@apilink PageElement} that matches its associated CSS selector.
+     *
+     * #### Example
+     *
+     * ```html
+     * <div class="form-entry">
+     *     <input id="username" />
+     *     <ul class="warnings">
+     *         <li>Username should be an email address</li>
+     *     </ul>
+     * </div>
+     * ```
+     *
+     * ```typescript
+     * class Username {
+     *   static field = () =>
+     *     PageElement.located(By.id('username'))
+     *       .describedAs('username field')
+     *
+     *   private static container = () =>
+     *     PageElement.located(By.css('.form-entry'))
+     *       .describedAs('form entry container')
+     *
+     *   static warnings = () =>
+     *     PageElements.located(By.css('ul.warnings li'))
+     *       .describedAs('warnings')
+     *       .of(
+     *         Username.container().closestTo(Username.field())
+     *       )
+     * }
+     * ```
+     *
+     * :::info
+     * This method relies on [Element: closest() API](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest),
+     * and so is only compatible with locating parent elements specified using the following CSS selectors:
+     * - {@apilink ByCss}
+     * - {@apilink ById}
+     * - {@apilink ByTagName}
+     * :::
+     *
+     * @param childElement
+     * @returns
+     *
+     * #### Learn more
+     * - [Element: closest() method](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest)
+     */
+    abstract closestTo(childElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
+    /**
      * An "escape hatch" providing access to the integration tool-specific implementation of a Web element.
@@ -28,0 +84,0 @@ */

package.json

 {
   "name": "@serenity-js/web",
-  "version": "3.6.1",
+  "version": "3.7.0",
   "description": "Serenity/JS Screenplay Pattern APIs for the Web",
@@ -47,4 +47,4 @@ "author": {
   "dependencies": {
-    "@serenity-js/assertions": "3.6.1",
-    "@serenity-js/core": "3.6.1",
+    "@serenity-js/assertions": "3.7.0",
+    "@serenity-js/core": "3.7.0",
     "tiny-types": "^1.20.0"
@@ -62,3 +62,3 @@ },
   },
-  "gitHead": "3e7242840af96081c63d12b116e3f95f74b97160"
+  "gitHead": "9a4da7e6080c3628e69bbf01f0efb3cd4e7b0720"
 }

src/screenplay/models/Locator.ts

@@ -0,1 +1,2 @@
+import { LogicError } from '@serenity-js/core';
 import { inspectedObject } from '@serenity-js/core/lib/io';
@@ -6,3 +7,3 @@ import * as util from 'util'; // eslint-disable-line unicorn/import-style
 import { RootLocator } from './RootLocator';
-import type { Selector } from './selectors';
+import { ByCss, ById, ByTagName, type Selector } from './selectors';
 
@@ -49,4 +50,30 @@ /**
     abstract of(parent: RootLocator<Native_Element_Type>): Locator<Native_Element_Type>;
+    abstract closestTo(child: Locator<Native_Element_Type>): Locator<Native_Element_Type>;
     abstract locate(child: Locator<Native_Element_Type>): Locator<Native_Element_Type>;
 
+    /**
+     * Expresses {@apilink ByCss}, {@apilink ById}, or {@apilink ByTagName} as a {@apilink ByCss} selector.
+     *
+     * @throws LogicError
+     *  if the `selector` can't be expressed as {@apilink ByCss}
+     *
+     * @param selector
+     * @protected
+     */
+    protected asCssSelector(selector: Selector): ByCss {
+        if (selector instanceof ByCss) {
+            return selector;
+        }
+
+        if (selector instanceof ById) {
+            return new ByCss(`#${ selector.value }`);
+        }
+
+        if (selector instanceof ByTagName) {
+            return new ByCss(`${ selector.value }`);
+        }
+
+        throw new LogicError(`${ selector } can't be expressed as a CSS selector`)
+    }
+
     abstract element(): PageElement<Native_Element_Type>;
@@ -53,0 +80,0 @@

src/screenplay/models/PageElement.ts

@@ -55,5 +55,62 @@ import type { Answerable, MetaQuestion, Optional, QuestionAdapter } from '@serenity-js/core';
 
+    /**
+     * Locates a child element that:
+     * - matches the given selector
+     * - is located within the `parentElement`
+     *
+     * @param parentElement
+     */
     abstract of(parentElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
 
     /**
+     * Traverses the element and its parents, heading toward the document root,
+     * until it finds a parent {@apilink PageElement} that matches its associated CSS selector.
+     *
+     * #### Example
+     *
+     * ```html
+     * <div class="form-entry">
+     *     <input id="username" />
+     *     <ul class="warnings">
+     *         <li>Username should be an email address</li>
+     *     </ul>
+     * </div>
+     * ```
+     *
+     * ```typescript
+     * class Username {
+     *   static field = () =>
+     *     PageElement.located(By.id('username'))
+     *       .describedAs('username field')
+     *
+     *   private static container = () =>
+     *     PageElement.located(By.css('.form-entry'))
+     *       .describedAs('form entry container')
+     *
+     *   static warnings = () =>
+     *     PageElements.located(By.css('ul.warnings li'))
+     *       .describedAs('warnings')
+     *       .of(
+     *         Username.container().closestTo(Username.field())
+     *       )
+     * }
+     * ```
+     *
+     * :::info
+     * This method relies on [Element: closest() API](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest),
+     * and so is only compatible with locating parent elements specified using the following CSS selectors:
+     * - {@apilink ByCss}
+     * - {@apilink ById}
+     * - {@apilink ByTagName}
+     * :::
+     *
+     * @param childElement
+     * @returns
+     *
+     * #### Learn more
+     * - [Element: closest() method](https://developer.mozilla.org/en-US/docs/Web/API/Element/closest)
+     */
+    abstract closestTo(childElement: PageElement<Native_Element_Type>): PageElement<Native_Element_Type>;
+
+    /**
      * An "escape hatch" providing access to the integration tool-specific implementation of a Web element.
@@ -60,0 +117,0 @@ */

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

692837

increased by0.99%

Lines of code

14865

increased by1.15%

Dependency changes

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

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

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

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

• Updated@serenity-js/assertions@3.7.0

• Updated@serenity-js/core@3.7.0