@cepharum/contextual-gherkin 3.1.0 → 4.0.1

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/llms.txt

@@ -0,0 +1,137 @@
+# @cepharum/contextual-gherkin
+
+> Flexible, context-aware Gherkin step definitions for Playwright-based E2E tests. Requires v3+.
+> Full documentation: https://cepharum-foss.gitlab.io/contextual-gherkin/
+
+## What it does
+
+contextual-gherkin provides a large library of ready-made Cucumber step definitions and a development API for writing custom ones. Its key feature is *contextuality*: a step that finds elements can track them so a follow-up step can act on them without repeating the selector logic.
+
+## Setup (one-time per project)
+
+```javascript
+// steps/setup.js
+import { BeforeAll, Before } from "@cucumber/cucumber";
+import { ContextualGherkin, use } from "@cepharum/contextual-gherkin";
+
+let adapter;
+
+BeforeAll( async () => {
+    adapter = await use.playwright();   // launches browser once
+} );
+
+Before( () => ContextualGherkin( {
+    selectors: {
+        button: "button",
+        panel: { "": ".panel", button: ".panel__btn" },
+    },
+    aliases: { btn: "button" },
+}, adapter ) );
+```
+
+Use `Before({ tags: "@tag" })` to provide different configurations per Cucumber tag.
+
+## Selectors configuration
+
+### Regular selectors
+Map singular element names to CSS selectors (or Playwright extended selectors):
+```javascript
+button: "button"
+panel: "#main > .panel"
+item: "xpath=//li[@data-active]"
+```
+
+### Selector hierarchies
+Nest selectors so context-specific overrides apply automatically:
+```javascript
+menu: {
+    "": "#menu",         // selector for "menu" itself
+    item: "a",           // "item" inside a menu → <a>
+},
+overview: {
+    "": ".overview",
+    item: "li",          // "item" inside overview → <li>
+},
+item: "li",              // global fallback for "item"
+```
+
+### Virtual selectors
+Customise how built-in steps inspect parts/properties of matched elements:
+- `$label` — element representing the label (default: `"label"`)
+- `$text`  — element representing textual content (default: `false` = self)
+- `$click`, `$enter`, `$hover` — target for action steps (default: `false` = self)
+- `$checked`, `$disabled`, `$value`, `$id`, `$name`, `$selected`, `$classList`
+- `@attrName` — redirect attribute inspection to a different attribute
+- `#propName` — redirect DOM property inspection to a different property
+
+### Custom selectors (cg-*)
+All registered automatically. Use anywhere a selector string is accepted:
+
+| Selector | Meaning |
+|---|---|
+| `cg-property=name:value` | DOM property exact/regex match |
+| `cg-attribute=name:value` | HTML attribute exact/regex match |
+| `cg-list-property=classList:foo` | classList contains "foo" |
+| `cg-list-property=classList!foo` | classList does not contain "foo" |
+| `cg-width=200` / `>=200` / `<=200` | rendered width in px |
+| `cg-height=200` / `>=200` / `<=200` | rendered height in px |
+| `cg-shadow-query=:shadow .inner` | query across shadow DOM boundary |
+| `me=` | the context element itself |
+
+`cg-shadow-query`: `:shadow` is a boundary token (not a CSS pseudo-class). A leading `:shadow` enters the context element's own shadow root. Multiple `:shadow` tokens cross multiple boundaries.
+
+## Accessing the API in custom steps
+
+```javascript
+import { Given, Then } from "@cucumber/cucumber";
+import { ContextualGherkin } from "@cepharum/contextual-gherkin";
+
+// Global search — find elements anywhere on page
+Then( "there is/are {cardinal-word} with a width of {int}px", async ( query, width ) => {
+    const api = await ContextualGherkin();
+    const matches = await api.find( query.word ).filterBySelector( `cg-width=${width}` );
+    await matches.checkCardinalWord( query );
+} );
+
+// Contextual search — find elements relative to a previous match
+Then( "{contextual-word} has/have a width of {int}px", async ( term, width ) => {
+    const api = await ContextualGherkin();
+    const context = api.getContextFor( term );
+    const box = await context.locator.boundingBox();
+    if ( box?.width !== width ) throw new Error( `expected ${width}px, got ${box?.width}` );
+} );
+```
+
+**Important**: Cucumber step callbacks receive one argument per Cucumber expression token — never use array destructuring, as `fn.length` is used for arity validation.
+
+## Key context methods
+
+| Method | Description |
+|---|---|
+| `context.find( name, fallback? )` | search descendants by configured type name |
+| `context.filterByType( name )` | intersect current set with named type (tests elements themselves) |
+| `context.filterBySelector( sel )` | intersect current set with raw selector |
+| `context.filterBySubType( name )` | keep elements that *contain* a descendant of named type |
+| `context.filterBySubSelector( sel )` | keep elements that *contain* a descendant matching selector |
+| `context.nth( index )` | pick single element by zero-based index |
+| `context.withAttribute( name, value )` | filter by attribute value |
+| `context.withProperty( name, value )` | filter by DOM property value |
+| `context.checkCardinalWord( query )` | assert count and track in history |
+| `context.track( type?, cardinality? )` | manually track in history |
+| `context.locator` | underlying Playwright Locator |
+
+## Cucumber expressions provided
+
+- `{cardinal-word}` — e.g. "three buttons", "at least 2 icons" → `{ word, number, mode, cardinality }`
+- `{contextual-word}` — e.g. "this button", "the first icon" → `{ word, index, subIndex, ... }`
+- `{ordinal-word}` — e.g. "the third" → `{ word, index }`
+- `{string-or-word}` — quoted string or single word
+
+## Aliases
+
+```javascript
+aliases: {
+    btn: "button",                          // "btn" ↔ "button"
+    list: [ "menu", "overview", "sidebar" ] // all four alias each other
+}
+```

package/package.json

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