@sungen/driver-ui 3.2.31 → 3.2.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-ui",
-  "version": "3.2.31",
+  "version": "3.2.32",
   "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.31"
+    "@sun-asterisk/sungen": "3.2.32"
   },
   "peerDependencies": {
     "@playwright/test": "^1.57.0"

package/src/patterns/assertion-patterns.ts

@@ -2,7 +2,7 @@ import { ParsedStep } from '@sun-asterisk/sungen';
 import { formatToRegexLiteral } from '@sun-asterisk/sungen';
 import { StepPattern, StepTemplateData, expandRecipe } from '@sun-asterisk/sungen';
 import { LIST_MEMBER_ROLES } from '@sun-asterisk/sungen';
-import { pathToRegexSource } from '../utils/url-path-regex';
+import { urlToPatternParts } from '../utils/url-path-regex';
 import { resolveColumnHeaderName } from '../utils/column-header';
 
 /**
@@ -173,14 +173,17 @@ export const assertionPatterns: StepPattern[] = [
           query = `\${${step.dataRef}}`;
         }
       }
-      // Convert path to regex-safe string (dynamic :id segments → [^/]+ wildcard)
-      const pathRegex = pathToRegexSource(path);
+      // Convert path to regex-safe string (dynamic :id segments → [^/]+ wildcard). An ABSOLUTE
+      // page value also yields a host pattern: matching only the path let this assertion pass on
+      // any host, so `see [Admin Jobs] page` declared as https://admin.example.com/jobs was
+      // satisfied by the public site's /jobs.
+      const { pathRegex, hostRegex } = urlToPatternParts(path);
       const withSuffix = step.dataRef ? ` with ${step.dataRef}` : '';
       return {
         templateName: 'page-assertion',
         // `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 || '', anchor },
+        data: { pathRegex, hostRegex, query, dataRef: step.dataRef || '', anchor },
         comment: step.selectorRef ? `Assert on ${step.selectorRef} page${withSuffix}` : `Assert on page${withSuffix}`,
       };
     },

package/src/patterns/capture-patterns.ts

@@ -71,10 +71,58 @@ export const capturePatterns: StepPattern[] = [
         step.selectorRef!, undefined, step.elementType, step.nth,
       );
       const varName = step.dataRef!;
-      const isValue = /\bvalue\b/i.test(step.text);
+      // What to capture is stated BETWEEN the reference and `as` — nowhere else (#736). Scanning the
+      // whole sentence also saw the word inside the reference name and inside the variable name, so
+      // `remember [Name Value] text as {{v}}` and `remember [Label] text as {{value}}` both compiled
+      // to .inputValue() and died on a <span> with "Node is not an <input>".
+      //
+      // `step.elementType` alone is NOT enough: it holds only the FIRST token after `]`, so the
+      // documented `remember [Email] field value as {{v}}` reads as 'field' and would lose its value
+      // capture. Slicing after `]` first is also what makes the `as` split safe — a reference like
+      // `[As Of Date]` never reaches it.
+      const descriptor = step.text.slice(step.text.indexOf(']') + 1).split(/\bas\b/i)[0];
+      const isValue = /\bvalue\b/i.test(descriptor);
       // Register so later `{{varName}}` references resolve to testData.get(varName)
       // and skip YAML validation.
       context.dataResolver.registerCaptured(varName);
+      // A capture reads ONE element, and the template now takes the first match rather than dying
+      // in strict mode. That is the right default — the documented workaround for the failure was
+      // `nth: 0`, i.e. this — but taking the first of many is a decision, and nothing else would
+      // ever say so: a capture feeds later steps, so a value read off the wrong row travels
+      // silently into whatever consumes it, possibly in another file.
+      //
+      // Reported on what the entry PROVES about cardinality, not on its strategy name. An id, a
+      // testid, a role WITH an accessible name, a label or a placeholder each address one thing by
+      // construction. `getByText` does not — it matches every element containing the text, which is
+      // exactly a list — and neither does a bare role or a class selector. The earlier reading of
+      // this rule ("warn for locator/css") got both halves wrong: it fired on `#order-id`, which is
+      // singular by definition, and stayed silent on `type: text`, which the `.first()` above
+      // silently narrows.
+      const value = String(resolved.value ?? '');
+      // Strategies that address ONE element by construction. The mobile native four are here for the
+      // same reason `testid` is: they are hand-written targeting expressions naming an element by an
+      // identifying attribute, so warning on them would fire on most captures in a mobile suite.
+      const IDENTIFYING = new Set([
+        'id', 'testid', 'label', 'placeholder',
+        'accessibility-id', 'xpath', 'android-uiautomator', 'ios-predicate',
+      ]);
+      const singular =
+        resolved.nth !== undefined
+        || IDENTIFYING.has(String(resolved.strategy))
+        || (resolved.strategy === 'role' && !!resolved.name)
+        || ((resolved.strategy === 'locator' || resolved.strategy === 'css') && value.includes('#'));
+      if (!singular) {
+        const fix = resolved.strategy === 'role'
+          ? 'give the role an accessible name, or declare the index you want ("nth: 0")'
+          : 'declare the index you want ("nth: 0"), or narrow the selector to the one element';
+        context.diagnostics?.add('SG-W036',
+          `"[${step.selectorRef}]" is captured through a ${resolved.strategy} selector `
+          + `("${value}") that can match several elements and declares no "nth:", so this step reads `
+          + `whichever one the page yields FIRST. If it describes every item in a list, the captured `
+          + `{{${varName}}} is the first row's value rather than the one the scenario means. `
+          + `To say the first one is meant, ${fix}.`,
+          { feature: context.featureName, step: step.text });
+      }
       return {
         templateName: 'capture-variable',
         data: { ...resolved, varName, capture: isValue ? 'inputValue' : 'textContent' },

package/src/patterns/interaction-patterns.ts

@@ -1,6 +1,6 @@
 import { ParsedStep } from '@sun-asterisk/sungen';
 import { StepPattern } from '@sun-asterisk/sungen';
-import { escapeRegex, pathToRegexSource } from '../utils/url-path-regex';
+import { urlToPatternParts } from '../utils/url-path-regex';
 
 /**
  * Extract Playwright waitFor state from step text.
@@ -562,25 +562,11 @@ export const interactionPatterns: StepPattern[] = [
         }
       }
 
-      const isAbsoluteUrl = /^https?:\/\//.test(path);
-      let pathRegex: string;
-      let hostRegex: string | undefined;
-      if (isAbsoluteUrl) {
-        const url = new URL(path);
-        // Host and path are matched SEPARATELY since #677: the wait tests `u.hostname` and
-        // `u.pathname`, and neither string contains the other. Concatenating them into one regex
-        // only worked while the match ran unanchored across the whole URL — the very looseness
-        // that let the wait resolve on a transient URL. Dynamic :id segments still wildcard;
-        // the host stays a literal.
-        hostRegex = escapeRegex(url.hostname);
-        pathRegex = pathToRegexSource(url.pathname);
-      } else {
-        pathRegex = pathToRegexSource(path);
-      }
-
+      // Host and path are matched SEPARATELY since #677 — see urlToPatternParts, which now serves
+      // every URL pattern in the compiler so the two assertion forms cannot drift from this wait.
       return {
         templateName: 'wait-for-page',
-        data: { pathRegex, hostRegex },
+        data: urlToPatternParts(path),
         comment: step.selectorRef ? `Wait for ${step.selectorRef} page` : `Wait for page`,
       };
     },

package/src/patterns/navigation-patterns.ts

@@ -1,7 +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';
+import { urlToPatternParts } from '../utils/url-path-regex';
 
 /**
  * `is on` names a NAVIGATION only for a page — or for an untyped / data-bound reference, the
@@ -90,7 +90,8 @@ export const navigationPatterns: StepPattern[] = [
         return {
           templateName: 'route-assertion',
           // `dataRef` rides along so a runtime failure names the test-data key (see the `see` twin).
-          data: { pathRegex: pathToRegexSource(path), query, dataRef: step.dataRef || '' },
+          // An absolute page value also carries a host pattern — see urlToPatternParts.
+          data: { ...urlToPatternParts(path), query, dataRef: step.dataRef || '' },
           comment: step.selectorRef ? `Assert on ${step.selectorRef} page${withSuffix}` : `Assert page route`,
         };
       }
@@ -157,7 +158,7 @@ export const navigationPatterns: StepPattern[] = [
         // Same rule as above — assert against the pre-resolution path so `:id` wildcards.
         return {
           templateName: 'route-assertion',
-          data: { pathRegex: pathToRegexSource(inferredPath) },
+          data: urlToPatternParts(inferredPath),
           comment: `Assert on ${route}`,
         };
       }
@@ -187,7 +188,7 @@ export const navigationPatterns: StepPattern[] = [
       });
       return {
         templateName: 'route-assertion',
-        data: { pathRegex: pathToRegexSource(inferredPath) },
+        data: urlToPatternParts(inferredPath),
         comment: `Assert current route is ${route}`,
       };
     },

package/src/patterns/table-patterns.ts

@@ -63,7 +63,17 @@ function warnIfRowsLikelyMissing(
 ): void {
   const sink = context.diagnostics;
   if (!sink || resolved.rows) return;
-  if (!['css', 'locator', 'testid', 'id'].includes(String(resolved.strategy))) return;
+  const strategy = String(resolved.strategy);
+  if (strategy === 'role') {
+    // A ROLE-located table was exempt outright, which read the exemption as "the author chose a
+    // role, so they thought about it". They did — but `role: list` or `role: region` contains no
+    // role=row either, so those tables hit the very failure this warning exists to name while
+    // staying completely silent. Only the roles that DO hold rows are evidence of anything.
+    const role = String(resolved.value ?? '').trim().toLowerCase();
+    if (role === 'table' || role === 'grid' || role === 'treegrid') return;
+  } else if (!['css', 'locator', 'testid', 'id'].includes(strategy)) {
+    return;
+  }
   if (/\btable\b/i.test(String(resolved.value ?? ''))) return;
   const key = `${context.featureName ?? ''}::${tableName}`;
   let seen = warnedTables.get(sink);
@@ -71,10 +81,29 @@ function warnIfRowsLikelyMissing(
   if (seen.has(key)) return;
   seen.add(key);
   sink.add('SG-W016',
-    `table "[${tableName}]" is located by ${resolved.strategy} ("${resolved.value}") and declares no "rows:" — if its rows are not role="row" (a <div> list), every table step resolves 0 rows: "is hidden" and "is empty" pass without checking anything, counts and clicks time out. Declare the row shape on the table entry, e.g. "rows: 'div.job-row'", or locate the table by role: table.`,
+    `table "[${tableName}]" is located by ${resolved.strategy} ("${resolved.value}") and declares no "rows:" — if its rows are not role="row" (a <div> list, or a role that holds no rows such as list/region), every table step resolves 0 rows: "is hidden" and "is empty" pass without checking anything, counts and clicks time out. Declare the row shape on the table entry, e.g. "rows: 'div.job-row'", or locate the table by role: table.`,
     { feature: context.featureName, step: stepText });
 }
 
+/**
+ * Does a declared `rows:` SHAPE select `<tr>` elements?
+ *
+ * `rows:` says what a row LOOKS like; it does not say the markup is not a table. `rows: 'tbody tr'`
+ * on a real <table> is a documented, working combination — it pins the row universe without
+ * changing what a row IS, so ARIA rows and `td, th` cells are still there. Only a shape built from
+ * something else (`div.job-row`, `li.card`) loses them, and that is the case the cell-reading steps
+ * cannot serve.
+ *
+ * Keying those steps on "a shape is declared" instead turned a correct table red: the refusal below
+ * would tell an author with a real <table> that their rows "are not ARIA rows", which is false, and
+ * a compile-time throw has to be right.
+ *
+ * Read as an element token so `div.tray` and `[data-tr]` are not mistaken for `tr`.
+ */
+function rowShapeKeepsTableRoles(rows: string | undefined): boolean {
+  return !!rows && /(^|[\s>+~,(])tr\b/i.test(rows);
+}
+
 /** Helper: check if current step is in a Given context */
 function isGivenContext(context: PatternContext): boolean {
   return context.effectiveKeyword === 'Given';
@@ -391,8 +420,16 @@ export const tablePatterns: StepPattern[] = [
     platformAlternative:
       'there is no HTML table on a native screen - tap the control on the row element itself (`When User tap [Row 1 Delete] button`)',
     matcher: (step) => {
+      // The VERB is required, exactly as the `-nth` twin above requires it. Without this test the
+      // pattern claimed every `in [T] table with {{v}}` sentence, verb or not, and the resolver's
+      // `|| 'click'` default then turned an ASSERTION into a click: `Then User see [Status] text in
+      // [Job Table] table with {{v}}` compiled to `.click()`, so the scenario went green having
+      // checked nothing. An action pattern must not be reachable from a sentence that names no
+      // action. `remember` is excluded for the same reason it is on the twin — it reads a value.
       return /\bin\b.*\btable\b/i.test(step.text) &&
              /\bwith\b/i.test(step.text) &&
+             /\b(clicks?|unchecks?|checks?)\b/i.test(step.text) &&
+             !/\bremember\b/i.test(step.text) &&
              !!step.dataRef &&
              step.elementType !== 'column' &&
              step.elementType !== 'row' &&
@@ -497,6 +534,58 @@ export const tablePatterns: StepPattern[] = [
       const resolvedRows = dataTable.rows.map(row => ({ cells: row.cells.map(resolveCell) }));
       const esc = (s: string) => s.replace(/'/g, "\\'");
 
+      // Where a CELL lives, decided at compile time from the table's own declaration.
+      //
+      // The runtime header read below only works on a real <table>: it reads `thead tr` and then
+      // addresses cells as `td, th`. A list whose rows are declared with a `rows:` SHAPE is built
+      // from <div>s, where `thead tr` is 0 elements forever — not a render race — and `td, th` is
+      // 0 elements too, so the step can never pass however long it waits. Declaring `columns:`
+      // replaces the read entirely: the index is known at compile time, and a column that names
+      // its own `elements.cell` addresses the cell without any table role at all.
+      const declaredColumns = resolved.columns ?? {};
+      const columnFor = (header: string) => {
+        const key = header.trim().toLowerCase().normalize('NFC');
+        const direct = declaredColumns[key];
+        if (direct) return direct;
+        return Object.values(declaredColumns).find(
+          (c) => String(c?.header ?? '').trim().toLowerCase().normalize('NFC') === key,
+        );
+      };
+      // A shape that still selects <tr> keeps its ARIA rows and its `td, th` cells, so the runtime
+      // header read below serves it exactly as it always did. Only a shape built from something else
+      // needs — and can use — the compile-time map.
+      const shapeHidesTableRoles = !!resolved.rows && !rowShapeKeepsTableRoles(resolved.rows);
+      // Usable means the column names the selector that matches its cell INSIDE a row. An `index:`
+      // alone cannot help here: it indexes the `td, th` set, which is empty on this markup.
+      const unmapped = headers.filter((h) => !columnFor(h)?.elements?.cell);
+      const mappedByCellSelector = shapeHidesTableRoles && unmapped.length === 0;
+
+      // A row shape that hides the table roles, with no cell selector to reach the cells by, cannot
+      // be served at all — refuse now, loudly, rather than emit an assertion that waits out every
+      // timeout before failing on a header row that will never exist.
+      if (shapeHidesTableRoles && unmapped.length > 0) {
+        const reason = `step "${step.text}" runs \`table match data:\` against table `
+          + `"[${step.selectorRef}]", whose rows are declared with a "rows:" shape — so the rows are `
+          + `not ARIA rows, their cells are not "td, th", and there is no "thead tr" to read the `
+          + `header row from. This assertion cannot pass on that markup however long it waits. `
+          + `Declare the columns it needs (${unmapped.map((h) => `"${h}"`).join(', ')}) on the table `
+          + `entry, each with the selector that matches its cell inside a row: "columns:\\n  `
+          + `${(unmapped[0] ?? 'title').trim().toLowerCase()}:\\n    index: 0\\n    header: `
+          + `'${unmapped[0] ?? 'Title'}'\\n    elements:\\n      cell:\\n        type: locator\\n `
+          + `       value: '.your-cell-class'".`;
+        context.diagnostics?.add('SG-E035', reason,
+          { feature: context.featureName, step: step.text });
+        return {
+          templateName: 'table-match-data',
+          data: {
+            ...resolved,
+            assertions: [`throw new Error(${JSON.stringify(`[sungen] ${reason}`)});`],
+            isGiven: isGivenContext(context),
+          },
+          comment: `Unsupported table match data on a declared row shape — see SG-E035: ${step.text}`,
+        };
+      }
+
       // Header → cell mapping (field report: the header row was parsed and then IGNORED —
       // rows were asserted as chained row-level hasText filters, so column-swapped data and
       // duplicate values like '-' still passed). Now:
@@ -514,12 +603,35 @@ export const tablePatterns: StepPattern[] = [
       assertions.push(
         `await expect(table.locator('[rowspan]:not([rowspan="1"]), [colspan]:not([colspan="1"])'), 'table match data: rowspan/colspan tables are not supported yet — header-to-cell mapping would be wrong').toHaveCount(0);`
       );
-      assertions.push(
-        `const __headers = (await table.locator('thead tr').first().locator('th, td').allTextContents()).map((t) => t.trim());`
-      );
-      assertions.push(
-        `const __colIdx = (h: string): number => { const i = __headers.indexOf(h); if (i !== -1) return i; const c = __headers.filter((t) => t.includes(h)); if (c.length === 1) return __headers.indexOf(c[0]); throw new Error(\`table match data: header "\${h}" \${c.length ? 'is ambiguous' : 'not found'} in table header row [\${__headers.join(' | ')}]\`); };`
-      );
+      // The cell expression for one DataTable column, scoped to `row`.
+      let cellExpr: (header: string) => string;
+      if (mappedByCellSelector) {
+        // Declared cell selectors: no header row is read at run time, so there is nothing to race
+        // with. Taken ONLY when the shape hides the table roles and every header has one — on a real
+        // table the runtime lookup is strictly better, because it is robust to extra DOM columns (a
+        // leading checkbox) that a compile-time index cannot see. Switching a working table onto
+        // compile-time indexes because it happens to declare `columns:` for some other step would
+        // silently re-point its assertions at different cells.
+        cellExpr = (header: string): string => context.renderLocator({
+          ...context.selectorResolver.resolveNestedEntry(columnFor(header)!.elements!.cell!, header),
+          parentLocator: 'row',
+        });
+      } else {
+        // The historical runtime mapping, for a table that declares nothing. The span guard above
+        // is NOT a wait: `toHaveCount(0)` is already true of an empty DOM, so it returns on the
+        // first poll and the one-shot read below then sees an empty header row. This assertion
+        // waits for the header row to actually hold cells before reading it.
+        assertions.push(
+          `await expect(table.locator('thead tr').first().locator('th, td'), 'table match data: the header row is still empty — the table had not rendered by the time this assertion read it').not.toHaveCount(0);`
+        );
+        assertions.push(
+          `const __headers = (await table.locator('thead tr').first().locator('th, td').allTextContents()).map((t) => t.trim());`
+        );
+        assertions.push(
+          `const __colIdx = (h: string): number => { const i = __headers.indexOf(h); if (i !== -1) return i; const c = __headers.filter((t) => t.includes(h)); if (c.length === 1) return __headers.indexOf(c[0]); throw new Error(\`table match data: header "\${h}" \${c.length ? 'is ambiguous' : 'not found'} in table header row [\${__headers.join(' | ')}]\`); };`
+        );
+        cellExpr = (header: string): string => `row.locator('td, th').nth(__colIdx('${esc(header)}'))`;
+      }
       for (const row of resolvedRows) {
         const filters = row.cells
           .map(cell => `.filter({ hasText: '${esc(cell)}' })`)
@@ -530,7 +642,7 @@ export const tablePatterns: StepPattern[] = [
           const header = headers[i];
           if (header === undefined) return;
           assertions.push(
-            `  await expect(row.locator('td, th').nth(__colIdx('${esc(header)}'))).toHaveText('${esc(cell)}');`
+            `  await expect(${cellExpr(header)}).toHaveText('${esc(cell)}');`
           );
         });
         assertions.push(`}`);

package/src/utils/url-path-regex.ts

@@ -37,3 +37,38 @@ export function pathToRegexSource(path: string): string {
     )
     .join('\\/');
 }
+
+/** A page value split into the two patterns the runtime matches SEPARATELY. */
+export interface UrlPatternParts {
+  /** Pattern for `u.pathname`. Always present. */
+  pathRegex: string;
+  /** Pattern for `u.hostname` — set only when the page value named an absolute URL. */
+  hostRegex?: string;
+}
+
+/**
+ * Split a page value into the host and path patterns the runtime matches separately.
+ *
+ * `u.hostname` never appears in `u.pathname`, so one concatenated regex cannot carry both — it
+ * only ever "worked" while the match ran unanchored across the whole URL, which is the looseness
+ * that let a wait resolve on a transient URL (#677). A page value that names an absolute URL
+ * therefore yields two patterns; a relative one yields the path pattern alone, exactly as before.
+ *
+ * Every caller that builds a pathname pattern for a URL assertion or wait goes through here, so
+ * the host half cannot be honoured on one step form and silently dropped on another: before this,
+ * only `wait for [X] page` split the host, while both assertion forms matched the path against
+ * ANY host — `see [X] page` with `https://admin.example.com/jobs` passed on the public site.
+ *
+ * Dynamic `:id` segments still wildcard; the host stays a literal. A value that starts like an
+ * absolute URL but does not parse falls back to the path-only reading rather than throwing — the
+ * pattern is then wrong in a way the author can read, which beats losing the step.
+ */
+export function urlToPatternParts(path: string): UrlPatternParts {
+  if (!/^https?:\/\//i.test(path)) return { pathRegex: pathToRegexSource(path) };
+  try {
+    const url = new URL(path);
+    return { hostRegex: escapeRegex(url.hostname), pathRegex: pathToRegexSource(url.pathname) };
+  } catch {
+    return { pathRegex: pathToRegexSource(path) };
+  }
+}