@cepharum/contextual-gherkin 4.0.0 → 4.0.2

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": "4.0.0",
+	"version": "4.0.2",
 	"description": "flexible step definitions for Gherkin",
 	"author": "cepharum GmbH <thomas.urban@cepharum.de>",
 	"homepage": "https://cepharum-foss.gitlab.io/contextual-gherkin/",