@sungen/driver-ui 3.2.18 → 3.2.20-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-ui",
-  "version": "3.2.18",
+  "version": "3.2.20-beta.1",
   "description": "Sungen UI capability (Playwright) — step patterns, viewpoint gate, and phase hooks. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.18"
+    "@sun-asterisk/sungen": "3.2.20-beta.1"
   },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"

package/src/index.ts

@@ -37,6 +37,8 @@ import { scrollPatterns } from './patterns/scroll-patterns';
 import { scopePatterns } from './patterns/scope-patterns';
 import { tablePatterns } from './patterns/table-patterns';
 import { capturePatterns } from './patterns/capture-patterns';
+import { storagePatterns } from './patterns/storage-patterns';
+import { focusPatterns } from './patterns/focus-patterns';
 
 /** Inputs the UI gate computation needs (passed by the audit engine via `gateProvider`). */
 export interface UiGateInput {
@@ -108,6 +110,8 @@ export function register(registry: CapabilityRegistry): void {
       ...scopePatterns,
       ...tablePatterns,
       ...capturePatterns,
+      ...storagePatterns,
+      ...focusPatterns,
     ],
     discovery: uiDiscovery,
     contextMapper: uiContextMapper,

package/src/patterns/assertion-patterns.ts

@@ -1,5 +1,6 @@
 import { ParsedStep } from '@sun-asterisk/sungen';
 import { StepPattern, StepTemplateData } from '@sun-asterisk/sungen';
+import { LIST_MEMBER_ROLES } from '@sun-asterisk/sungen';
 import { pathToRegexSource } from '../utils/url-path-regex';
 
 /**
@@ -116,12 +117,27 @@ export const assertionPatterns: StepPattern[] = [
         }
       }
 
+      // `see [X] page with {{v}}` — the query/fragment value the parser put in dataRef. It used
+      // to be dropped here: the step compiled to a bare base-path toHaveURL that PASSES even when
+      // the query is wrong or gone, so a filter/search regression read as green. The `is on` twin
+      // has asserted it since issue #464; this is the same assertion, so it asserts the same way.
+      let query = '';
+      if (step.dataRef) {
+        try {
+          query = context.dataResolver.resolveData(step.dataRef, context.featureName);
+        } catch {
+          query = `\${${step.dataRef}}`;
+        }
+      }
       // Convert path to regex-safe string (dynamic :id segments → [^/]+ wildcard)
       const pathRegex = pathToRegexSource(path);
+      const withSuffix = step.dataRef ? ` with ${step.dataRef}` : '';
       return {
         templateName: 'page-assertion',
-        data: { pathRegex },
-        comment: step.selectorRef ? `Assert on ${step.selectorRef} page` : `Assert on page`,
+        // `dataRef` rides along so a runtime failure can name the test-data key an author must go
+        // fix — an empty/absent value is otherwise the hardest kind of red to trace.
+        data: { pathRegex, query, dataRef: step.dataRef || '' },
+        comment: step.selectorRef ? `Assert on ${step.selectorRef} page${withSuffix}` : `Assert on page${withSuffix}`,
       };
     },
     priority: 13,  // Higher priority than general visibility
@@ -473,11 +489,16 @@ export const assertionPatterns: StepPattern[] = [
       // list-member roles only (listitem/option/cell) — unique labelled elements keep
       // toHaveText (value check), and locator-type lists are unchanged. `row` is excluded
       // (table rows have dedicated existence patterns).
-      const LIST_MEMBER_ROLES = new Set(['listitem', 'option', 'cell']);
+      // The name is NOT stripped here any more. It used to be dropped unconditionally, which also
+      // discarded a `name:` the user had declared explicitly — and the strip only ever protected
+      // THIS branch, leaving `is hidden` / `is disabled` to compile the invented name into a locator
+      // that matches nothing. The resolver now withholds the invented name at its source
+      // (LIST_MEMBER_ROLES in selector-resolver), so every branch is covered and an explicit name
+      // still reaches the locator. What stays here is the ROUTING: filter-then-visible instead of
+      // toHaveText, because a bare getByRole('listitem') strict-mode-fails when many match.
       if (resolved.strategy === 'role' && resolved.role && LIST_MEMBER_ROLES.has(resolved.role)) {
-        const { name: _name, ...resolvedWithoutName } = resolved;
         const code = context.templateEngine.renderStep('visible-filtered-assertion', {
-          ...resolvedWithoutName,
+          ...resolved,
           dataValue,
         });
         return {

package/src/patterns/focus-patterns.ts

@@ -0,0 +1,83 @@
+/**
+ * Focus/tab-order assertion — a Gherkin data table declares the expected keyboard
+ * focus sequence:
+ *
+ *   Then User see tab order:
+ *     | Ref |
+ *     | [Station Dropdown] |
+ *     | [Departure Date] |
+ *
+ * Compiles to: focus row 1 (the pinned origin — there is deliberately no separate
+ * `focus [X]` step), then for each following row press Tab and assert that element
+ * is focused. Web-only: no Appium twin — a mobile feature using this step fails
+ * loudly at compile ("Template not found") instead of faking a result.
+ *
+ * Cell refs ARE selector references (unlike storage keys) — each resolves through
+ * selectors.yaml. Resolution failures are COLLECTED and thrown as one compile error
+ * listing every broken row: neither the fail-open `getByRole` guess some table
+ * paths use (a wrong a11y assertion on a deliverable), nor dying on the first typo.
+ */
+
+import { StepPattern } from '@sun-asterisk/sungen';
+
+// The step line carries no refs, so masked text == raw text. Anchored: exactly
+// `see tab order:` — nothing else fits, nothing else may claim it.
+const reTabOrder = /^\s*(?:user\s+)?sees?\s+tab\s+order\s*:?\s*$/i;
+
+/** `[Ref]` with an optional trailing element type: `[Save] button`. */
+const CELL = /^\s*\[([^\]]+)\]\s*([A-Za-z][A-Za-z-]*)?\s*$/;
+
+export const focusPatterns: StepPattern[] = [
+  {
+    name: 'tab-order-assertion',
+    matcher: (step) => reTabOrder.test(step.text),
+    resolver: (step, context) => {
+      const table = step.dataTable;
+      // The parser silently DROPS a table with fewer than 2 total rows, so a
+      // missing header row and a missing table look identical here — both must
+      // be a loud compile error, or the scenario would pass asserting nothing.
+      if (!table) {
+        throw new Error(
+          `"${step.text}": tab order needs a data table with a header row and at least 2 element rows:\n` +
+          '    | Ref |\n    | [First Element] |\n    | [Second Element] |');
+      }
+      if (/^\s*\[/.test(table.headers[0] ?? '')) {
+        throw new Error(
+          `"${step.text}": the first table row looks like an element ("${table.headers[0]}") — it was consumed as the HEADER. ` +
+          'Add a header row (`| Ref |`) so no element is silently swallowed.');
+      }
+      if (table.rows.length < 2) {
+        throw new Error(
+          `"${step.text}": a tab order needs at least 2 element rows — with one row there is nothing after the origin to assert, and the step would pass unconditionally.`);
+      }
+
+      const cells: Array<Record<string, unknown>> = [];
+      const errors: string[] = [];
+      table.rows.forEach((row, i) => {
+        const raw = row.cells[0] ?? '';
+        const m = raw.match(CELL);
+        if (!m) {
+          errors.push(`row ${i + 1} ("${raw}"): cell must be "[Ref]" with an optional element type, e.g. "[Save] button"`);
+          return;
+        }
+        try {
+          const resolved = context.selectorResolver.resolveSelector(m[1], context.featureName, m[2], 0);
+          cells.push({ ...resolved, label: m[1] });
+        } catch (e) {
+          errors.push(`row ${i + 1} [${m[1]}]: ${e instanceof Error ? e.message : String(e)}`);
+        }
+      });
+      if (errors.length > 0) {
+        throw new Error(
+          `"${step.text}": ${errors.length} tab-order cell(s) failed to resolve — fix selectors.yaml, no fallback is guessed:\n  - ${errors.join('\n  - ')}`);
+      }
+
+      return {
+        templateName: 'tab-order-assertion',
+        data: { cells, stepCounter: context.stepCounter },
+        comment: `Assert tab order: ${cells.map((c) => `[${c.label}]`).join(' → ')}`,
+      };
+    },
+    priority: 60,
+  },
+];

package/src/patterns/keyboard-patterns.ts

@@ -10,17 +10,27 @@ export const keyboardPatterns: StepPattern[] = [
     name: 'press-key-global',
     matcher: (step) => {
       const text = step.text.toLowerCase();
-      return /\bpress(?:es)?\s+\w+\s+key\b/.test(text) && !text.includes(' on ');
+      // Matchers see bracket refs MASKED ([Enter] → [~]), so the bracketed key form
+      // the docs teach ("press [Enter] key") must be accepted as [~] — plain \w+ made
+      // it fall through to a // TODO no-op.
+      return /\bpress(?:es)?\s+(?:\w+|\[~\])\s+key\b/.test(text) && !text.includes(' on ');
     },
     resolver: (step, context) => {
-      // Extract key name: "User press Escape key" → "Escape"
-      const match = step.text.match(/press(?:es)?\s+(\w+)\s+key/i);
-      const key = match ? match[1] : 'Enter';
+      // Resolver reads the ORIGINAL text: "press Escape key" / "press [Enter] key" → key name.
+      // A bracketed key is taken WHOLE — "[Arrow Down]" must not degrade to the 'Enter'
+      // default (a silently wrong key); spaces collapse to the Playwright spelling
+      // (ArrowDown), and anything else (chords like Control+A) passes through so an
+      // invalid name fails loudly at runtime instead of green-and-wrong at compile.
+      const match = step.text.match(/press(?:es)?\s+(?:\[([^\]]+)\]|(\w+))\s+key/i);
+      const key = match ? (match[1] ?? match[2]).trim().replace(/\s+/g, '') : 'Enter';
+      // "press Tab key 5 times" — without this the count silently compiled to ONE press.
+      const times = step.text.match(/\bkey\s+(\d+)\s+times?\b/i);
+      const repeat = times ? parseInt(times[1], 10) : 0;
 
       return {
         templateName: 'keyboard-global-action',
-        data: { key },
-        comment: `Press ${key} key`,
+        data: { key, repeat: repeat > 1 ? repeat : undefined },
+        comment: repeat > 1 ? `Press ${key} key ${repeat} times` : `Press ${key} key`,
       };
     },
     priority: 12,

package/src/patterns/navigation-patterns.ts

@@ -1,6 +1,7 @@
 import { ParsedStep } from '@sun-asterisk/sungen';
 import { StepPattern } from '@sun-asterisk/sungen';
 import { inferPath, resolvePathVariables, getPathCode } from '@sun-asterisk/sungen';
+import { pathToRegexSource } from '../utils/url-path-regex';
 
 /**
  * Navigation patterns: goto, navigate, open page
@@ -26,7 +27,13 @@ export const navigationPatterns: StepPattern[] = [
           const resolved = context.selectorResolver.resolveSelector(
             step.selectorRef, context.featureName, step.elementType, step.nth
           );
-          path = resolved.value || pathFallback;
+          // Only a `page`-type entry carries a URL in `value` — the same guard the `see [X] page`
+          // twin has carried since the key-collision fix (assertion-patterns.ts). Without it a
+          // colliding non-page entry (a `type: role` whose value is 'button') was used verbatim as
+          // the path, so the step asserted `^button/?$` — a wrong, specific path rather than the
+          // documented fallback. These two resolvers have drifted apart twice already; keep them
+          // spelling the same rule.
+          path = resolved.selectorType === 'page' ? (resolved.value || pathFallback) : pathFallback;
         } catch (error) {
           path = pathFallback;
         }
@@ -38,7 +45,7 @@ export const navigationPatterns: StepPattern[] = [
       // `[X] page with {{v}}` — the query/fragment value parsed into dataRef (issue #464).
       // Raw concat, no "smart" URL merging: the primary use case is injecting malformed
       // query input, so the compiler must not sanitize what the test wants broken.
-      // Runtime mode resolves to a __SUNGEN_TD__ marker → `path + testData.get(...)`.
+      // Runtime mode resolves to a __SUNGEN_TD$…$__ marker → `path + testData.get(...)`.
       let query = '';
       if (step.dataRef) {
         try {
@@ -53,16 +60,25 @@ export const navigationPatterns: StepPattern[] = [
       // separately (toHaveURL's regex stays compile-time escapable; the query value is
       // runtime data with regex-special characters).
       if (isThen) {
+        // Regex from the RAW path, not finalPath: resolvePathVariables rewrites `:id` into
+        // `${id}` for a goto template literal, which an assertion then escapes into
+        // `\/users\/\$\{id\}\/profile` — a regex no real URL can match. An assertion wants
+        // the wildcard the `see [X] page` twin already produced.
         return {
           templateName: 'route-assertion',
-          data: { path: finalPath, query },
+          // `dataRef` rides along so a runtime failure names the test-data key (see the `see` twin).
+          data: { pathRegex: pathToRegexSource(path), query, dataRef: step.dataRef || '' },
           comment: step.selectorRef ? `Assert on ${step.selectorRef} page${withSuffix}` : `Assert page route`,
         };
       }
 
       return {
         templateName: 'navigation',
-        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: finalPath + query },
+        // `query` stays SEPARATE from `path` rather than concatenated here: in runtime-data mode
+        // the value is still a `__SUNGEN_TD$…$__` marker at this point, so the compiler cannot see
+        // whether it carries its own path. Deciding that is therefore a runtime job — the template
+        // hands both parts to joinPath(). Concatenating here is what produced `/vi/search/vi/search`.
+        data: { baseURL: isAbsoluteUrl ? undefined : context.baseURL, path: finalPath, query },
         comment: step.selectorRef ? `Open ${step.selectorRef} page${withSuffix}` : `Navigate to page`,
       };
     },
@@ -115,9 +131,10 @@ export const navigationPatterns: StepPattern[] = [
       const isAbsoluteUrl = /^https?:\/\//.test(cleanPath);
 
       if (isThen) {
+        // Same rule as above — assert against the pre-resolution path so `:id` wildcards.
         return {
           templateName: 'route-assertion',
-          data: { path: cleanPath },
+          data: { pathRegex: pathToRegexSource(inferredPath) },
           comment: `Assert on ${route}`,
         };
       }
@@ -142,12 +159,9 @@ export const navigationPatterns: StepPattern[] = [
         featureName: context.featureName,
         screenName: context.screenName,
       });
-      const resolvedPath = resolvePathVariables(inferredPath, context.scenarioSteps || []);
-      const pathCode = getPathCode(resolvedPath);
-
       return {
         templateName: 'route-assertion',
-        data: { path: pathCode.replace(/^['`]|['`]$/g, '') },
+        data: { pathRegex: pathToRegexSource(inferredPath) },
         comment: `Assert current route is ${route}`,
       };
     },

package/src/patterns/storage-patterns.ts

@@ -0,0 +1,151 @@
+/**
+ * Browser-storage assertion patterns — read-only checks against
+ * localStorage/sessionStorage:
+ *
+ *   Then User see [KEY] in local storage exists
+ *   Then User see [KEY] in local storage does not exist
+ *   Then User see [KEY] in local storage is not empty
+ *   Then User see [KEY] in local storage has length {{n}}
+ *   Then User see key matching "PATTERN" in local storage
+ *   (+ the same five with `session storage`)
+ *
+ * Leak-safe by construction: the check runs INSIDE the browser and only a
+ * boolean crosses back — a failed assertion's Expected:/Received: shows
+ * true/false, never the stored value (tokens routinely live in these keys,
+ * and failure text is lifted verbatim into committed deliverables).
+ *
+ * `[KEY]` is NOT a selector reference — resolveSelector is never called.
+ * The bracket content is parsed here; an embedded `{{var}}` compiles to a
+ * testData.get() concatenation directly (same approach as the DB patterns'
+ * value binding), so `[{{code}}_ACCESS_TOKEN]` works without the marker
+ * pipeline. The parser stamps elementType="in" (first word after the
+ * bracket) — meaningless here, deliberately ignored.
+ */
+
+import { StepPattern } from '@sun-asterisk/sungen';
+
+// Matchers see ref contents MASKED ([AUTH_TOKEN] → [~], {{n}} → {{~}}), so they
+// anchor on the discriminator OUTSIDE the brackets. Anchored + priority 60 —
+// the generic `should-be-visible` catch-all (priority 10, any `see [ref]`)
+// otherwise claims every bracketed shape and asserts a DOM element instead.
+const AREA = String.raw`(?:local|session)\s+storage`;
+const reExists = new RegExp(String.raw`\bsees?\s+\[~\]\s+in\s+${AREA}\s+exists\b`, 'i');
+const reNotExist = new RegExp(String.raw`\bsees?\s+\[~\]\s+in\s+${AREA}\s+does\s+not\s+exist\b`, 'i');
+const reNotEmpty = new RegExp(String.raw`\bsees?\s+\[~\]\s+in\s+${AREA}\s+is\s+not\s+empty\b`, 'i');
+const reHasLength = new RegExp(String.raw`\bsees?\s+\[~\]\s+in\s+${AREA}\s+has\s+length\s+(?:\{\{~\}\}|\d+)`, 'i');
+// The one shape with no bracket: the quoted pattern survives masking untouched.
+const reKeyMatching = new RegExp(String.raw`\bsees?\s+key\s+matching\s+"[^"]+"\s+in\s+${AREA}\b`, 'i');
+
+/**
+ * `localStorage` | `sessionStorage` from the step's STRUCTURAL text — bracket keys and
+ * quoted patterns are neutralized first, so a key named "user session storage flag"
+ * (or a pattern containing the words) can never flip the area of a `local storage` step.
+ */
+function storageArea(text: string): string {
+  const structural = text.replace(/\[[^\]]*\]/g, '[~]').replace(/"[^"]*"/g, '""');
+  return /\bin\s+session\s+storage\b/i.test(structural) ? 'sessionStorage' : 'localStorage';
+}
+
+/** 'local storage' | 'session storage' — for comments/messages. */
+function areaLabel(text: string): string {
+  return storageArea(text) === 'sessionStorage' ? 'session storage' : 'local storage';
+}
+
+/**
+ * Bracket content → JS string expression. A plain key becomes a quoted literal;
+ * embedded `{{var}}` refs become `${testData.get('var')}` interpolations in a
+ * template literal (direct concatenation — no marker round-trip).
+ */
+function keyExpr(raw: string): string {
+  if (!/\{\{[^}]+\}\}/.test(raw)) return JSON.stringify(raw);
+  // `$` is escaped too: a literal `${` in the key would otherwise become a LIVE
+  // interpolation in the emitted template literal. The {{var}} substitution below
+  // inserts its own `${testData.get(...)}` afterwards, so it is unaffected.
+  const body = raw
+    .replace(/[\\`$]/g, '\\$&')
+    .replace(/\{\{\s*([^}]+?)\s*\}\}/g, (_, name) => `\${testData.get(${JSON.stringify(name)})}`);
+  return `\`${body}\``;
+}
+
+/** The bracketed key from the ORIGINAL step text (masking never reaches resolvers). */
+function bracketKey(text: string): string {
+  const m = text.match(/sees?\s+\[([^\]]+)\]\s+in/i);
+  return m ? m[1] : '';
+}
+
+interface StorageCheck {
+  /** In-browser predicate over ([k, arg]) — must yield a boolean, never a value. */
+  checkExpr: string;
+  /** Second evaluate argument (JS expression), 'null' when unused. */
+  argExpr: string;
+  /** Human suffix for the assertion message ("expected to exist"). */
+  expectation: string;
+}
+
+function buildCheck(text: string, area: string): StorageCheck | null {
+  if (/\bdoes\s+not\s+exist\b/i.test(text)) {
+    return { checkExpr: `window.${area}.getItem(k) === null`, argExpr: 'null', expectation: 'expected to be absent' };
+  }
+  if (/\bis\s+not\s+empty\b/i.test(text)) {
+    return { checkExpr: `!!window.${area}.getItem(k)`, argExpr: 'null', expectation: 'expected a non-empty value' };
+  }
+  const len = text.match(/\bhas\s+length\s+(\{\{[^}]+\}\}|\d+)/i);
+  if (len) {
+    const v = len[1].match(/^\{\{\s*([^}]+?)\s*\}\}$/);
+    const argExpr = v ? `Number(testData.get(${JSON.stringify(v[1])}))` : len[1];
+    return { checkExpr: `(window.${area}.getItem(k) ?? '').length === arg`, argExpr, expectation: 'expected the given length' };
+  }
+  if (/\bexists\b/i.test(text)) {
+    return { checkExpr: `window.${area}.getItem(k) !== null`, argExpr: 'null', expectation: 'expected to exist' };
+  }
+  return null;
+}
+
+export const storagePatterns: StepPattern[] = [
+  {
+    name: 'storage-key-assertion',
+    matcher: (step) =>
+      reExists.test(step.text) || reNotExist.test(step.text) ||
+      reNotEmpty.test(step.text) || reHasLength.test(step.text),
+    resolver: (step) => {
+      const area = storageArea(step.text);
+      const check = buildCheck(step.text, area);
+      const rawKey = bracketKey(step.text);
+      // Matcher anchoring guarantees both; guard for the type system.
+      if (!check || !rawKey) throw new Error(`unrecognized storage assertion: ${step.text}`);
+      const k = keyExpr(rawKey);
+      return {
+        templateName: 'storage-key-assertion',
+        data: {
+          checkExpr: check.checkExpr,
+          keyExpr: k,
+          argExpr: check.argExpr,
+          // Key NAME is printable; the stored VALUE never crosses this boundary.
+          messageExpr: `'key ' + ${k} + ' in ${areaLabel(step.text)}: ${check.expectation}'`,
+        },
+        comment: `Assert ${rawKey} in ${areaLabel(step.text)} (${check.expectation})`,
+      };
+    },
+    priority: 60,
+  },
+  {
+    name: 'storage-key-matching-assertion',
+    matcher: (step) => reKeyMatching.test(step.text),
+    resolver: (step) => {
+      const area = storageArea(step.text);
+      const m = step.text.match(/key\s+matching\s+"([^"]+)"/i);
+      const pattern = m ? m[1] : '';
+      return {
+        templateName: 'storage-key-assertion',
+        data: {
+          checkExpr: `Object.keys(window.${area}).some((key) => new RegExp(k).test(key))`,
+          keyExpr: JSON.stringify(pattern),
+          argExpr: 'null',
+          messageExpr: `'key matching ' + ${JSON.stringify(JSON.stringify(pattern))} + ' in ${areaLabel(step.text)}: expected a match'`,
+        },
+        comment: `Assert a ${areaLabel(step.text)} key matches "${pattern}"`,
+      };
+    },
+    priority: 60,
+  },
+];