@sun-asterisk/sungen 3.2.29 → 3.2.30

package/src/generators/test-generator/diagnostics.ts

@@ -10,6 +10,13 @@
  *   SG-W002 — step parsed a {{dataRef}} value but the generated code never uses it
  *   SG-W003 — `name` filter defaulted from the Gherkin reference on a name-from-content
  *             role (status/alert/…) — such a filter can never match; opt out with `name: null`
+ *   SG-W004 — a selectors.yaml entry declares a field no consumer reads, so writing it has no
+ *             effect on the generated test. Reserved for this in the original diagnostics spec
+ *             (`exact: true` with no construct it applies to) and implemented for the wider class
+ *             by #712, where `pagination:` and `contenteditable:` were public, documented,
+ *             plumbed — and read by nothing. The field partition lives in
+ *             utils/selector-entry-fields.ts; a field added there without a named consumer is
+ *             the bug this code exists to catch.
  *   SG-W005 — qa/app.yaml problem (unknown key, unknown preset, unparseable)
  *   SG-W006 — qa/app.<env>.yaml found (per-environment profiles are unsupported by design)
  *   SG-W007 — browser-alert handler step written AFTER an action step: the listener
@@ -59,6 +66,23 @@
  *             but the generated code is a BARE VISIBILITY check: the clause was swallowed by the
  *             catch-all and the test would pass whatever the element says. Four separate defects
  *             have arrived this way, so the step compiles to a runtime throw instead.
+ *   SG-W017 — a step needs a selector-entry field the entry does not declare, so there is nothing
+ *             honest to compile. Today: a table paginate step whose table declares no
+ *             `pagination.next`/`.prev` (#712). The mirror of SG-W004 — that one reports a field
+ *             written that nothing reads, this one a field a consumer needs that nobody wrote.
+ *             Compiles the step to a loud runtime throw rather than guessing a locator, which is
+ *             the #690 failure (a locator no page has, failing far from the cause).
+ *   SG-W018 — a selectors.yaml entry declares an `nth:` the compiler cannot use (#720). `nth:` was
+ *             the one entry field whose VALUE nothing checked: the key is known (SG-W004 quiet) and
+ *             the `type:` is valid (SG-E027 quiet), so `nth: -1`, `nth: 'last'`, `nth: 1.5` and
+ *             `nth: -2` all compiled clean — the web side dropped the filter entirely (identical to
+ *             deleting the line, then a strict-mode violation naming the DOM) while the mobile side
+ *             emitted `$$('~x')[-1]` / `[last]`, undefined-indexing and a bare identifier that even
+ *             the SG-E022 parse check reads as valid JavaScript. The contract is an integer `>= -1`
+ *             (`0..N` a zero-based index, `-1` the last match); anything else is normalised away
+ *             before it reaches a template, and reported here so "ignored" is stated rather than
+ *             discovered. A warning, on SG-W004's reasoning — the value is inert once dropped and
+ *             `--strict` already turns the channel non-zero
  *   SG-E020 — the step matched a pattern whose template the ACTIVE adapter does not ship. Before
  *             the platform SPI this was an unhandled `Template not found` that killed the WHOLE
  *             feature file and named neither the step nor the adapter. The step now compiles to a
@@ -111,6 +135,13 @@
  *             RUN time, so the compiler cannot know — the matrix, not this code, is the net that
  *             covers that case. Reported as an E-code and compiled to a loud throw, because the
  *             feature has declared the one OS where the step is known not to work.
+ *   SG-E026 — a click step names a POSITION (`at position "top-left"`, `at offset x=…, y=…`) that
+ *             would not be honoured: the keyword is misspelt, a value is outside the grammar (not a
+ *             number, negative, above 100%, a missing axis, an unknown preset), or another click form
+ *             claimed the step first (`try to click`, a `with {{v}}` text filter, `… and accept [OK]
+ *             alert`). Each of those would compile to a click on the element's CENTRE and pass — for a
+ *             backdrop-dismiss overlay that is the one outcome that proves nothing — so the step
+ *             compiles to a loud throw instead
  *   SG-W026 — a mobile ACTIVE-NAVIGATION step that emitted NO executable code, so a promised screen
  *             change never happens. `When User open [Settings] page` compiles to the one-line
  *             `navigation` template — a comment noting the app was already launched by the wdio
@@ -137,6 +168,15 @@
  *             Reported rather than resolved by precedence — two tests genuinely sharing one title
  *             cannot be told apart by a name-keyed lookup, so the only honest fix is a rename. Silently
  *             picking a winner would be the same silent-discard shape as SG-W021
+ *   SG-E027 — a selectors.yaml entry declares a `type:` that is not a selector type at all. YAML is
+ *             untyped at run time, so `type: 'testId'` (capital I), `'xpth'`, `'rol'` or any other
+ *             misspelling used to compile clean and resolve through the strategy switch's
+ *             `default:` branch as `getByPlaceholder('<the value>')` — a locator that cannot
+ *             match, failing much later as a timeout naming placeholder text the author never
+ *             wrote. Checked where the selector FILE is loaded rather than in the switch: `page`
+ *             legitimately reaches that `default:` on every page assertion, and the load point can
+ *             name the entry key and the nearest valid spelling. Reported once per entry, and
+ *             every step naming that entry compiles to a `throw`
  *   SG-E022 — the generated spec is not parseable JS/TS, so NOTHING in the file runs — Playwright
  *             reports one SyntaxError and every scenario in the unit is lost. A compiler self-check
  *             (@babel/parser) on the emitted code, added after a field report where the runtime-data
@@ -145,16 +185,50 @@
  *             compiler, not the Gherkin: it should be impossible, and it is reported so a broken
  *             build names itself at generate time instead of one step further downstream
  *
+ *   SG-W028 — a step's trailing scope clause was DROPPED, so the step runs against more of the page
+ *             than its sentence names. Two causes, one code: the `<word>` after `in [X]` is not a
+ *             container type (a typo, or a leaf element used as a parent), or the by-content form
+ *             `in [X] <type> with {{v}}` was written for the mobile adapter, which chains a parent
+ *             element and has no content filter. Before this, both compiled clean and silently
+ *             widened the assertion to the whole screen — the failure mode that only a diff of the
+ *             generated spec against the Gherkin could reveal (#667)
+ *   SG-W029 — a mobile (appium) feature compiled with NO usable app-package `Path:` — either the line
+ *             is missing outright, or it holds a web-style route (`Path: /applied-jobs`) that the
+ *             package guard rejects. Both used to be silent, and both cost the same two things: the
+ *             per-scenario `beforeEach` was not emitted at all, so Background dropped to Mocha's
+ *             `before()` (once per FILE, every scenario sharing one continuous app session — a tab
+ *             switch or a scroll in one scenario stranding elements off-screen for every later one),
+ *             and the `@reset:` tier ladder went with it, leaving the tag inert. The spec now always
+ *             emits the reset machinery and resolves the app id from the session capability that
+ *             wdio.conf sets, throwing a named error when nothing supplies one — so this is a
+ *             warning about an under-declared feature file, not a broken build (#669)
+ *   SG-W030 — a selectors.yaml `expanded.class`/`expanded.attribute` carries a character outside the
+ *             accepted class/attribute-name set (whitespace, a quote, a backslash, `$`, `{`, `}`).
+ *             The value is pasted into the generated spec (string literal, regex, classList argument),
+ *             and selectors.yaml is often generated from the page under test, so it is refused and the
+ *             field dropped — the step falls back to driving/asserting `aria-expanded`. Reported once
+ *             per entry and field. A WARNING rather than a refusal because the fallback still tests
+ *             something; the checked/selected signal has no fallback and is refused outright instead
+ *
+ *   SG-E031 — a selectors.yaml `checked:`/`selected:` declaration the compiler refuses: the two
+ *             spellings disagree, a class token or attribute name carries whitespace/a quote/a
+ *             backslash, or one entry declares both a class and an attribute. Each is silent at run
+ *             time — the matcher would never match and the step would time out blaming the
+ *             component — so the declaration is refused rather than compiled. Unlike the expanded
+ *             signal (SG-W030) it is not dropped-and-warned: with no signal the step is back on the
+ *             failure the declaration exists to fix. Recorded here AND thrown, so a pattern that
+ *             resolves selectors inside a `catch` cannot swallow it silently
  * Diagnostics never change the EXIT CODE by themselves; `sungen generate --strict` turns any
  * collected diagnostic into a non-zero exit. They are not all inert, though: SG-W001, SG-W011,
- * SG-E020, SG-E021, SG-W020, SG-E023 and SG-E024 additionally compile the offending step to a runtime
- * `throw`, because a step that reads as a check and silently checks nothing is worse than one that
- * fails loudly. (SG-E022 is the one exception to the "blame the Gherkin" rule and throws nothing: the
- * file is still written so the user keeps the artifact to inspect.)
+ * SG-E020, SG-E021, SG-W020, SG-E023, SG-E024, SG-E025, SG-E026 and SG-E027 additionally compile
+ * the offending step to a runtime `throw` — a step that reads as a check and silently checks
+ * nothing is worse than one that fails loudly — and SG-E031 refuses the file outright. (SG-E022 is
+ * the one exception to the "blame the Gherkin" rule and throws nothing: the file is still written
+ * so the user keeps the artifact to inspect.)
  * Generation always COMPLETES — the rest of the scenario and the rest of the file still compile.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-W016' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-W026' | 'SG-E025' | 'SG-E022' | 'SG-E023' | 'SG-E024';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W004' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-W016' | 'SG-W017' | 'SG-W018' | 'SG-E020' | 'SG-E021' | 'SG-W020' | 'SG-W021' | 'SG-W022' | 'SG-W023' | 'SG-W024' | 'SG-W026' | 'SG-E025' | 'SG-E026' | 'SG-E022' | 'SG-E023' | 'SG-E024' | 'SG-E027' | 'SG-W028' | 'SG-W029' | 'SG-W030' | 'SG-E031';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/patterns/index.ts

@@ -6,6 +6,8 @@ import { discoverAndRegisterCapabilities } from '../../../capabilities/discover'
 import { maskRefsForMatching } from '../utils/mask-refs-for-matching';
 import { unsupportedStepCode } from './unsupported-step-code';
 import { osSupportOfTemplate } from '../adapters/appium/os-support';
+import { withParentScope } from './with-parent-scope';
+import { escapeSingleQuoted } from '../utils/escape-js-string';
 
 // Both helpers moved out of this file so the Gherkin parser (state-clause extraction) and the
 // step-mapper (SG-W001 no-pattern fallback) can use them without importing the pattern registry.
@@ -135,6 +137,10 @@ export class PatternRegistry {
     // Matching mirrors findPattern exactly: refs masked FIRST (so `[Tap Water]` is not a
     // verb), then `tap` → `click` normalisation for the mobile vocabulary.
     const matchStep: ParsedStep = { ...step, text: normalizeVerbs(maskRefsForMatching(step.text)) };
+    // The step's parent scope, resolved ONCE for the whole search. Not per candidate pattern: a
+    // resolver may decline and hand the step to the next one, and re-resolving here would report
+    // the mobile by-content refusal (SG-W028) once per attempt instead of once per step.
+    const parentScope = PatternRegistry.resolveParentLocator(step, context);
     for (const pattern of this.patterns) {
       if (!this.matchesPattern(matchStep, pattern.matcher)) continue;
 
@@ -144,10 +150,20 @@ export class PatternRegistry {
       const platformMiss = PatternRegistry.platformMiss(pattern, context, step);
       if (platformMiss) return platformMiss;
 
+      // Shared by BOTH code paths below. The injection used to live inside the resolver branch, so
+      // a `generator` pattern discarded a perfectly parsed scope: `see [Tag] header with {{label}}
+      // in [Job Card] section` routes to `see-with-variable` (a generator) and asserted against the
+      // whole page (#667). Scope that is parsed and then dropped widens the step just as silently
+      // as scope that never parsed at all.
+      // `table-*` patterns opt out by name — they resolve the container from the step text
+      // themselves and would otherwise scope it twice.
+      const parentLocator = pattern.name.startsWith('table-') ? undefined : parentScope;
+      const scoped = parentLocator ? withParentScope(context, parentLocator) : context;
+
       try {
         // Prefer resolver (framework-agnostic) over generator (legacy)
         if (pattern.resolver) {
-          const resolved = pattern.resolver(step, context);
+          const resolved = pattern.resolver(step, scoped);
           if (!resolved) continue; // resolver declined — fall through
 
           // iOS gate — AFTER the resolver, because it needs the template the step actually reached.
@@ -167,17 +183,16 @@ export class PatternRegistry {
           if (resolverStateMiss) return resolverStateMiss;
 
           // Auto-inject parent scoping if step has parentRef
-          // Skip for table-* patterns — they resolve the table name internally from step text
-          if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
-            resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
-              step.parentRef, step.parentType, context
-            );
-          }
+          if (parentLocator) resolved.data.parentLocator = parentLocator;
 
           const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
+          // The compiler's post-map guards need to know WHICH form won and what it resolved to (e.g.
+          // a refusal a resolver recorded in its data) — without re-matching.
           return {
             code,
             comment: resolved.comment,
+            pattern: pattern.name,
+            templateData: resolved.data,
           };
         }
 
@@ -185,7 +200,9 @@ export class PatternRegistry {
           // A legacy generator has no decline path, so this pattern owns the step already.
           const generatorStateMiss = PatternRegistry.stateMiss(pattern, context, step);
           if (generatorStateMiss) return generatorStateMiss;
-          return pattern.generator(step, context);
+          // A generator returning nothing still falls through to the no-pattern path.
+          const generated = pattern.generator(step, scoped);
+          return generated ? { ...generated, pattern: pattern.name } : null;
         }
 
         return null;
@@ -347,14 +364,23 @@ export class PatternRegistry {
   }
 
   /**
-   * Resolve parent scoping to a Playwright locator string.
-   * Tries YAML lookup first, falls back to auto-infer from parentType.
+   * Resolve a step's `in [Parent] <type> [with <value>]` scope to a locator string, or `undefined`
+   * when the step carries no scope.
    *
-   * Parent type → Playwright role:
-   *   table → 'table', list → 'list', section → 'region',
-   *   dialog → 'dialog', form → 'form'
+   * Tries YAML lookup first, falls back to auto-inferring a role from the container type with the
+   * reference as the accessible name. A reference written as `{{var}}` is resolved through
+   * test-data before it reaches that name — containers are routinely labelled with the text under
+   * test, and a literal `{{var}}` in the name matches nothing.
    */
-  private static resolveParentLocator(
+  private static resolveParentLocator(step: ParsedStep, context: PatternContext): string | undefined {
+    const { parentRef, parentType } = step;
+    if (!parentRef || !parentType) return undefined;
+
+    const base = PatternRegistry.parentContainerLocator(parentRef, parentType, context);
+    return PatternRegistry.filterParentByValue(base, step, context);
+  }
+
+  private static parentContainerLocator(
     parentRef: string, parentType: string, context: PatternContext
   ): string {
     // Try resolving from selectors YAML
@@ -370,13 +396,68 @@ export class PatternRegistry {
     const roleMap: Record<string, string> = {
       table: 'table',
       list: 'list',
+      'list-item': 'listitem',
+      listitem: 'listitem',
+      item: 'listitem',
+      row: 'row',
       section: 'region',
+      container: 'region',
+      panel: 'region',
+      card: 'region',
+      group: 'group',
       dialog: 'dialog',
+      modal: 'dialog',
+      drawer: 'dialog',
+      overlay: 'dialog',
       form: 'form',
+      tab: 'tabpanel',
+      menu: 'menu',
     };
     const role = roleMap[parentType] || parentType;
-    const escapedName = parentRef.replace(/'/g, "\\'");
-    return `page.getByRole('${role}', { name: '${escapedName}' })`;
+    const name = escapeSingleQuoted(PatternRegistry.resolveInlineData(parentRef, context));
+    return `page.getByRole('${role}', { name: '${name}' })`;
+  }
+
+  /**
+   * Narrow the container to the ONE whose content matches the step's parent value — the
+   * `with {{job_title}}` tail of `see [Tag] header with {{label}} in [Job Card] card with
+   * {{job_title}}`. Without it a list of identical cards leaves the assertion matching whichever
+   * one Playwright reaches first.
+   *
+   * Web-only, and refused rather than approximated elsewhere: the Appium partial chains a parent
+   * with `$()`, which has no content filter, so emitting one would be invalid code and pretending
+   * the scope applied would be the very silence this whole fix exists to end (SG-W028).
+   */
+  private static filterParentByValue(
+    base: string, step: ParsedStep, context: PatternContext
+  ): string {
+    const raw = step.parentValueRef
+      ? PatternRegistry.resolveInlineData(`{{${step.parentValueRef}}}`, context)
+      : step.parentValueText;
+    if (raw === undefined) return base;
+
+    if (context.platform === 'mobile') {
+      context.diagnostics?.add('SG-W028',
+        `scoping a container BY CONTENT ("in [${step.parentRef}] ${step.parentType} with …") is web-only — the mobile adapter chains a parent element, which has no content filter, so this step would search every ${step.parentType} on the screen. Give the container an accessibility id that identifies it and scope by that instead, or assert on the element the value belongs to`,
+        { feature: context.featureName, step: step.text });
+      return base;
+    }
+    return `${base}.filter({ hasText: '${escapeSingleQuoted(raw)}' })`;
+  }
+
+  /**
+   * Resolve a `{{var}}` written where literal text is expected, leaving anything else untouched.
+   * An unknown variable stays as written rather than throwing — the locator is then wrong in a way
+   * the author can read, which beats losing the whole step.
+   */
+  private static resolveInlineData(text: string, context: PatternContext): string {
+    const match = text.match(/^\{\{([a-z0-9\-._]+)\}\}$/i);
+    if (!match) return text;
+    try {
+      return context.dataResolver.resolveData(match[1], context.featureName);
+    } catch {
+      return text;
+    }
   }
 
   /**

package/src/generators/test-generator/patterns/with-parent-scope.ts

@@ -0,0 +1,41 @@
+import { PatternContext } from './types';
+
+/**
+ * Return a `PatternContext` in which every selector the pattern resolves comes back already scoped
+ * to `parentLocator`.
+ *
+ * Why a wrapped context rather than one assignment. A `resolver` pattern hands its template data
+ * back to the registry, which can stamp `parentLocator` on it; a `generator` pattern renders its own
+ * code and never exposes that object, so the registry had no seam and the scope was simply lost
+ * (#667). The seam both kinds share is where they ASK for a selector — `selectorResolver` and
+ * `renderLocator` — so the scope is attached there instead, and every locator partial (Playwright
+ * and Appium alike) already knows what to do with a `parentLocator` field.
+ *
+ * Only the target's own scope is stamped; anything a pattern resolves that ALREADY carries a
+ * `parentLocator` is left alone, so a pattern that builds its own container chain (table rows) keeps
+ * winning over the generic one.
+ */
+export function withParentScope(context: PatternContext, parentLocator: string): PatternContext {
+  const scope = <T>(resolved: T): T =>
+    resolved && typeof resolved === 'object' && !(resolved as any).parentLocator
+      ? { ...(resolved as any), parentLocator }
+      : resolved;
+
+  // A Proxy rather than a copy: SelectorResolver carries more than the one method patterns call,
+  // and a hand-written stand-in would silently drop whatever it forgot.
+  const selectorResolver = new Proxy(context.selectorResolver, {
+    get(target, prop, receiver) {
+      if (prop === 'resolveSelector') {
+        return (...args: unknown[]) => scope((target as any).resolveSelector(...args));
+      }
+      const value = Reflect.get(target, prop, receiver);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+
+  return {
+    ...context,
+    selectorResolver,
+    renderLocator: (resolved: any) => context.renderLocator(scope(resolved)),
+  };
+}