@cepharum/contextual-gherkin 3.1.0 → 4.0.0

package/index.d.ts

@@ -690,18 +690,43 @@ declare module "@cepharum/contextual-gherkin" {
 		nth( index: number|null ): AbstractContext;
 
 		/**
-		 * Reduces current context's set of matching elements to those matching
-		 * another selector for given type of element.
+		 * Limits current set of matching elements to those also matching the
+		 * selector configured for a given element type, intersecting the current
+		 * set rather than searching descendants.
 		 *
-		 * @note In opposition to filter(), this function isn't descending into
-		 *       the hierarchy of elements but inspects currently matching
-		 *       elements, only.
+		 * @param typeOfElement type of element to intersect current matches with
+		 * @param defaultSelector selector to use if none has been configured for the named type of elements
+		 * @returns another context representing only those matching elements of current context that also match selector of given type
+		 */
+		filterByType( typeOfElement: string, defaultSelector?: SimpleSelector ): AbstractContext;
+
+		/**
+		 * Limits current set of matching elements to those also matching a given
+		 * selector, intersecting the current set rather than searching descendants.
+		 *
+		 * @param selector selector string to intersect current matches with
+		 * @returns another context representing only those matching elements of current context that also match given selector
+		 */
+		filterBySelector( selector: string ): AbstractContext;
+
+		/**
+		 * Limits current set of matching elements to those containing a descendant
+		 * matching the selector configured for a given element type.
 		 *
-		 * @param typeOfElement type of element to reduce matches to
+		 * @param typeOfElement type of element to look for in descendants
 		 * @param defaultSelector selector to use if none has been configured for the named type of elements
-		 * @returns another context representing only those matching elements of current context that match selector of given name, too
+		 * @returns another context representing only those matching elements of current context that contain a descendant of given type
+		 */
+		filterBySubType( typeOfElement: string, defaultSelector?: SimpleSelector ): AbstractContext;
+
+		/**
+		 * Limits current set of matching elements to those containing a descendant
+		 * matching a given selector.
+		 *
+		 * @param selector selector string to look for in descendants
+		 * @returns another context representing only those matching elements of current context that contain a descendant matching given selector
 		 */
-		filter( typeOfElement: string, defaultSelector?: SimpleSelector ): AbstractContext;
+		filterBySubSelector( selector: string ): AbstractContext;
 
 		/**
 		 * Reduces current context's set of matching elements to those marked as

package/lib/context/playwright.js

@@ -171,25 +171,78 @@ export class PlaywrightContext extends AbstractContext {
 	}
 
 	/**
-	 * Limits current set of matches to those matching as a given type of
-	 * elements, too.
+	 * Limits current set of matches to those also matching a given element
+	 * type's selector, intersecting the current set rather than searching
+	 * descendants.
 	 *
-	 * @param {string} typeOfElement names type of elements to focus on
+	 * @param {string} typeOfElement names type of elements to intersect with
 	 * @param {SimpleSelector} defaultSelector selector to use as fallback
-	 * @returns {Context} node describing matches of filtering and their processing context
+	 * @returns {Context} node describing the filtered set of elements
 	 */
-	filter( typeOfElement, defaultSelector = undefined ) {
+	filterByType( typeOfElement, defaultSelector = undefined ) {
 		const type = this.api.toNormalizedSingularName( typeOfElement );
 		const { query, dependencies } = this.getSelector( type, defaultSelector );
 
 		return new this.constructor( this, {
-			locator: this.locator.filter( { has: this.createSubLocator( query, dependencies ) } ),
+			locator: this.locator.and( this.createSubLocator( query, dependencies, true ) ),
 			type: this.type,
 			selectors: this.selectors,
 			cardinality: this.cardinality
 		} );
 	}
 
+	/**
+	 * Limits current set of matches to those also matching a given selector,
+	 * intersecting the current set rather than searching descendants.
+	 *
+	 * @param {string} selector selector string accepted by Playwright locators
+	 * @returns {Context} node describing the filtered set of elements
+	 */
+	filterBySelector( selector ) {
+		return new this.constructor( this, {
+			locator: this.locator.and( this.locator.page().locator( selector ) ),
+			type: this.type,
+			selectors: this.selectors,
+			cardinality: this.cardinality,
+		} );
+	}
+
+	/**
+	 * Limits current set of matches to those containing a descendant matching
+	 * a given element type's selector.
+	 *
+	 * @param {string} typeOfElement names type of elements to look for in descendants
+	 * @param {SimpleSelector} defaultSelector selector to use as fallback
+	 * @returns {Context} node describing the filtered set of elements
+	 */
+	filterBySubType( typeOfElement, defaultSelector = undefined ) {
+		const type = this.api.toNormalizedSingularName( typeOfElement );
+		const { query, dependencies } = this.getSelector( type, defaultSelector );
+
+		return new this.constructor( this, {
+			locator: this.locator.filter( { has: this.createSubLocator( query, dependencies ) } ),
+			type: this.type,
+			selectors: this.selectors,
+			cardinality: this.cardinality,
+		} );
+	}
+
+	/**
+	 * Limits current set of matches to those containing a descendant matching
+	 * a given selector.
+	 *
+	 * @param {string} selector selector string accepted by Playwright locators
+	 * @returns {Context} node describing the filtered set of elements
+	 */
+	filterBySubSelector( selector ) {
+		return new this.constructor( this, {
+			locator: this.locator.filter( { has: this.locator.page().locator( selector ) } ),
+			type: this.type,
+			selectors: this.selectors,
+			cardinality: this.cardinality,
+		} );
+	}
+
 	/**
 	 * Limits current set of matches to those picked by a given callback
 	 * function invoked in browser.

package/lib/support/playwright/custom-selectors.js

@@ -10,6 +10,8 @@ export async function registerPlaywrightSelectors() {
 		registerAttributeSelector(),
 		registerShadowQuerySelector(),
 		registerMeSelector(),
+		registerWidthSelector(),
+		registerHeightSelector(),
 	] );
 }
 
@@ -141,6 +143,116 @@ export function registerShadowQuerySelector() {
 	} ) );
 }
 
+/**
+ * Registers custom selector engine `cg-width` for locating elements whose
+ * rendered width satisfies a numeric constraint.
+ *
+ * Query syntax:  <value>          exact match (px)
+ *                >=<value>        minimum width (px)
+ *                <=<value>        maximum width (px)
+ *
+ * When the engine root is an Element it is tested directly. When the root is
+ * a Document or ShadowRoot all descendant elements are searched instead.
+ */
+export function registerWidthSelector() {
+	return selectors.register( "cg-width", () => ( {
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		query( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by width" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().width;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? root : undefined;
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).find( test );
+		},
+
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		queryAll( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by width" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().width;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? [root] : [];
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).filter( test );
+		},
+	} ) );
+}
+
+/**
+ * Registers custom selector engine `cg-height` for locating elements whose
+ * rendered height satisfies a numeric constraint.
+ *
+ * Query syntax:  <value>          exact match (px)
+ *                >=<value>        minimum height (px)
+ *                <=<value>        maximum height (px)
+ *
+ * When the engine root is an Element it is tested directly. When the root is
+ * a Document or ShadowRoot all descendant elements are searched instead.
+ */
+export function registerHeightSelector() {
+	return selectors.register( "cg-height", () => ( {
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		query( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by height" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().height;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? root : undefined;
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).find( test );
+		},
+
+		// client function, runs in browser, can't reliably use shared code other than what is injected as init script
+		queryAll( root, query ) {
+			const [ , op, value ] = /^(>=|<=)?(\d+(?:\.\d+)?)$/.exec( query ) || [];
+			if ( value == null ) {
+				throw new TypeError( "malformed query for matching elements by height" );
+			}
+
+			const target = parseFloat( value );
+			const test = node => {
+				const actual = node.getBoundingClientRect().height;
+				return op === ">=" ? actual >= target : op === "<=" ? actual <= target : actual === target;
+			};
+
+			if ( typeof root.getBoundingClientRect === "function" ) {
+				return test( root ) ? [root] : [];
+			}
+
+			return Array.from( root.querySelectorAll( "*" ) ).filter( test );
+		},
+	} ) );
+}
+
 /**
  * Registers custom selector for locating current root element itself primarily
  * to feature its combination with other locators.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cepharum/contextual-gherkin",
-	"version": "3.1.0",
+	"version": "4.0.0",
 	"description": "flexible step definitions for Gherkin",
 	"author": "cepharum GmbH <thomas.urban@cepharum.de>",
 	"homepage": "https://cepharum-foss.gitlab.io/contextual-gherkin/",