@sun-asterisk/sungen 3.2.29 → 3.2.31

package/src/generators/test-generator/step-mapper.ts

@@ -1,11 +1,15 @@
 import { ParsedStep } from '../gherkin-parser';
+import { PARENT_CONTAINER_TYPES } from '../gherkin-parser/parent-scope-clause';
 import { TemplateEngine } from './template-engine';
 import { adapterRegistry } from './adapters';
 import { PatternRegistry, PatternContext, Platform } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
+import { locatorIdentityKey } from './utils/dialog-scope-identity';
 import { DiagnosticsCollector } from './diagnostics';
 import { unsupportedStepCode } from './patterns/unsupported-step-code';
+import { maskRefsForMatching } from './utils/mask-refs-for-matching';
+import { isKnownSelectorType } from './utils/selector-type-validation';
 import { loadAppProfile, ResolvedAppProfile } from './app-profile';
 import { capabilityRegistry } from '../../capabilities/registry';
 
@@ -38,6 +42,8 @@ export interface MappedStep {
   code: string; // Generated Playwright code
   comment?: string; // Optional comment
   imports?: string[]; // Required imports
+  pattern?: string; // Name of the step form that produced the code (post-map guards read it)
+  templateData?: Record<string, any>; // What the resolver handed the template (e.g. a recorded refusal)
 }
 
 /**
@@ -203,6 +209,19 @@ export class StepMapper {
     this.dataResolver.registerCaptured(name);
   }
 
+  /**
+   * Register the head of a variable bound by the feature's `@beforeAll` hook. Feature-scoped: it
+   * survives setScenarioContext() so every scenario can read `{{head.*}}` as a runtime get().
+   */
+  registerFeatureCaptured(head: string): void {
+    this.dataResolver.registerFeatureCaptured(head);
+  }
+
+  /** Drop feature-scoped captured vars — call once per feature, before its hooks and scenarios map. */
+  clearFeatureCaptured(): void {
+    this.dataResolver.clearFeatureCaptured();
+  }
+
   /**
    * Map a Gherkin step to Playwright code
    * Uses pattern registry first, falls back to AI if enabled
@@ -216,6 +235,8 @@ export class StepMapper {
       this.lastPrimaryKeyword = keyword;
     }
 
+    this.warnScopeClauseDiscarded(step);
+
     // SG-W015 — `see [X] card with {{n}}` where n is a bare number compiles to a TEXT
     // assertion (toHaveText('3')), not a count. An author reaching for "3 cards are shown"
     // gets an assertion that can only pass if the card's TEXT is the digit — a wrong test
@@ -295,20 +316,25 @@ export class StepMapper {
       this.templateEngine.setBaseContext({ inFrame: true, frameSelector });
       // C1 — routed through the adapter instead of building `page.frameLocator(...)` inline:
       // the Appium adapter's own template performs its webview-context switch instead.
-      const code = this.templateEngine.renderStep('frame-enter-action', { frameSelector });
+      // `frameRef` carries the name as WRITTEN in the Gherkin: the Appium twin can fail (#705),
+      // and its error has to quote the step the author would go and look at, not the resolved
+      // xpath they never typed.
+      const code = this.templateEngine.renderStep('frame-enter-action', { frameSelector, frameRef: selectorRef });
       return { code, comment: `Switch to ${selectorRef} frame` };
     }
 
     // Dialog scope directives — intercept before pattern matching
     if (/\buse dialog\b/i.test(step.text)) {
       this.inDialogScope = true;
-      this.templateEngine.setBaseContext({ inDialog: true });
+      // setBaseContext MERGES — an earlier scope's root keys in the same scenario would
+      // otherwise leak into this unnamed one.
+      this.templateEngine.setBaseContext({ inDialog: true, dialogScopeKey: undefined });
       this.warnDialogScopeIgnoredOnMobile(step);
       return { code: '', comment: 'Enter dialog scope' };
     }
     if (/\b(?:close|dismiss|exit)\s+dialog\b/i.test(step.text)) {
       this.inDialogScope = false;
-      this.templateEngine.setBaseContext({ inDialog: false });
+      this.templateEngine.setBaseContext({ inDialog: false, dialogScopeKey: undefined });
       return { code: '', comment: 'Exit dialog scope' };
     }
     // `is on [X] <type>` supports exactly two shapes: `page` (URL from the page-type selector
@@ -344,6 +370,7 @@ export class StepMapper {
         dialogRootExpr: undefined,
         dialogRoleName: undefined,
         dialogFilterText: undefined,
+        dialogScopeKey: undefined,
       };
 
       if (step.selectorRef && step.dataRef) {
@@ -372,6 +399,16 @@ export class StepMapper {
       }
       // Case 1: no selectorRef → plain page.getByRole('dialog')
 
+      // Record what this root IS, so a later step naming the same element is recognized as the
+      // root rather than nested inside it (issue #692). The declared entry when there is one;
+      // otherwise the named-dialog fallback the element itself will resolve to.
+      if (step.selectorRef) {
+        const entry = this.resolveDialogEntry(step.selectorRef);
+        contextVars.dialogScopeKey = entry
+          ? locatorIdentityKey(entry)
+          : locatorIdentityKey({ strategy: 'role', role: 'dialog', name: step.selectorRef });
+      }
+
       this.templateEngine.setBaseContext(contextVars);
       return { code: '', comment: `Enter dialog scope${step.selectorRef ? ': ' + step.selectorRef : ''}` };
     }
@@ -427,10 +464,14 @@ export class StepMapper {
       this.checkPageAssertionNoOpOnMobile(step, mappedStep);
       this.checkSetupNoOpOnMobile(step, mappedStep);
       this.checkNavigationNoOpOnMobile(step, mappedStep);
-      this.checkPageAssertionFallback(step, mappedStep);
+      this.checkPageStepFallback(step, mappedStep);
       this.checkDeclaredUrlHasNoQuery(step, mappedStep);
+      const positionDropped = this.checkClickPositionDropped(step, mappedStep);
+      if (positionDropped) return positionDropped;
       const swallowed = this.checkAssertionClauseSwallowed(step, mappedStep);
       if (swallowed) return swallowed;
+      const badType = this.checkUnknownSelectorType(step, mappedStep);
+      if (badType) return badType;
       return mappedStep;
     }
 
@@ -487,6 +528,27 @@ export class StepMapper {
    * falls back to the legacy named-dialog root, so behavior is unchanged for those entries.
    */
   private renderDialogRoot(selectorRef: string, opts: { nonRoleOnly?: boolean } = {}): string | undefined {
+    const resolved = this.resolveDialogEntry(selectorRef);
+    if (!resolved) return undefined;
+    if (!StepMapper.DIALOG_ROOT_STRATEGIES.includes(resolved.strategy)) return undefined;
+    if (opts.nonRoleOnly && resolved.strategy === 'role') return undefined;
+
+    // Render the root PAGE-rooted: leaving inDialog set (or `scope: dialog` on the entry
+    // itself) would send the partial back through dialog-root and nest the dialog in itself.
+    const expr = this.templateEngine.renderStep('locator', {
+      ...resolved,
+      scope: resolved.scope === 'dialog' ? undefined : resolved.scope,
+      inDialog: false,
+    }).trim();
+    return expr || undefined;
+  }
+
+  /**
+   * The selectors.yaml entry behind a dialog reference, normalized the way the `locator` partial
+   * needs it. Shared by `renderDialogRoot` (which turns it into the root expression) and the
+   * scope-entry path (which keys off it to recognize the root again later — issue #692).
+   */
+  private resolveDialogEntry(selectorRef: string): any | undefined {
     let resolved: any;
     try {
       resolved = this.selectorResolver.resolveSelector(selectorRef, this.featureName, 'dialog', 0);
@@ -500,34 +562,27 @@ export class StepMapper {
     if (resolved.strategy === 'css' && resolved.locator) {
       resolved = { ...resolved, strategy: 'locator', value: resolved.locator };
     }
-    if (!StepMapper.DIALOG_ROOT_STRATEGIES.includes(resolved.strategy)) return undefined;
-    if (opts.nonRoleOnly && resolved.strategy === 'role') return undefined;
-
-    // Render the root PAGE-rooted: leaving inDialog set (or `scope: dialog` on the entry
-    // itself) would send the partial back through dialog-root and nest the dialog in itself.
-    const expr = this.templateEngine.renderStep('locator', {
-      ...resolved,
-      scope: resolved.scope === 'dialog' ? undefined : resolved.scope,
-      inDialog: false,
-    }).trim();
-    return expr || undefined;
+    return resolved;
   }
 
   /**
-   * SG-W013 — a page assertion whose path came from a fallback rather than from a `type: page`
-   * selector entry. Both resolvers degrade quietly when `[Ref]` does not resolve: `see [X] page`
-   * falls back to the feature's own path, `is on [X] page` to `/<ref>/`. Before the assertion was
-   * anchored that produced a test which always PASSED; anchored, it produces one that can never
-   * pass. Neither is the assertion the author wrote, and nothing said so.
+   * SG-W013 — a page STEP whose path came from a fallback rather than from a `type: page`
+   * selector entry. Every resolver degrades quietly when `[Ref]` does not resolve: `see [X] page`
+   * and `wait for [X] page` fall back to the feature's own path, `is on [X] page` to `/<ref>/`.
+   * Before the match was anchored that produced a test which always PASSED; anchored, it produces
+   * one that can never pass — an assertion that always fails, or, since #677 anchored the wait
+   * too, a wait that can only time out. None is the step the author wrote, and nothing said so.
    *
-   * Detected here rather than in the resolver on purpose: `MappedStep` carries only
-   * `{code, comment, imports}`, and the resolvers live in the driver packages while the collector
-   * lives in core. Re-asking the SAME resolver the step-mapper already owns costs three lines and
+   * Detected here rather than in the resolver on purpose: the resolvers live in the driver packages
+   * while the collector lives in core (the mapped step now also names its pattern and carries the
+   * resolver's data, but the fallback itself is only visible by re-resolving the selector). Re-asking the SAME resolver the step-mapper already owns costs three lines and
    * duplicates no logic — the alternative is widening the adapter contract for every driver.
    */
-  private checkPageAssertionFallback(step: ParsedStep, mapped: MappedStep): void {
+  private checkPageStepFallback(step: ParsedStep, mapped: MappedStep): void {
     if (!this.diagnostics || !step.selectorRef || step.elementType !== 'page') return;
-    if (!/\b(?:urlMatches|expectPage)\(/.test(mapped.code || '')) return;   // both URL-assertion shapes (#662)
+    // every shape that compiles a page path into an ANCHORED match: the two assertions (#662)
+    // and the wait (#677). A step that emitted none of them has no path to get wrong.
+    if (!/\b(?:urlMatches|expectPage|waitForPage)\(/.test(mapped.code || '')) return;
     let resolvedAsPage = false;
     try {
       const resolved = this.selectorResolver.resolveSelector(
@@ -539,7 +594,7 @@ export class StepMapper {
     }
     if (resolvedAsPage) return;
     this.diagnostics.add('SG-W013',
-      `page assertion for "[${step.selectorRef}]" has no "type: page" selector entry, so it asserts a FALLBACK path — the anchored assertion cannot match the real URL. Declare the page, e.g. "${step.selectorRef.toLowerCase()}:\\n  type: page\\n  value: '/your/path'"`,
+      `page step "[${step.selectorRef}]" has no "type: page" selector entry, so it targets a FALLBACK path — the anchored match can never reach the real URL (an assertion always fails; a wait can only time out). Declare the page, e.g. "${step.selectorRef.toLowerCase()}:\\n  type: page\\n  value: '/your/path'"`,
       { feature: this.featureName, step: step.text });
   }
 
@@ -588,6 +643,43 @@ export class StepMapper {
    * Deliberately narrow — it fires only on the bare-visibility shape, so a pattern that genuinely
    * consumed the clause (`is-hidden`, `contains`, `matches-format`, the state family) is untouched.
    */
+  /**
+   * SG-E027 (#711) — the step names an entry whose `type:` is not a selector type, so the resolver
+   * fell to its placeholder default and this step compiled to `getByPlaceholder('<the value>')`:
+   * a locator that cannot match, which would fail much later as a timeout naming placeholder text
+   * the author never wrote. Compile it to a `throw` instead — the same reasoning as SG-E023 above,
+   * that a step which reads as a check and can only ever fail obscurely is worse than one that
+   * fails loudly and says why.
+   *
+   * The DIAGNOSTIC is not added here. `SelectorResolver.loadNewSelectorFile` already reported this
+   * entry once for the whole file; re-reporting per step would print the same line twenty times for
+   * one typo. This method only replaces the code, so the compile-time message and the runtime
+   * failure stay one fact reported once.
+   *
+   * A resolve throw means the key is missing entirely — a different defect that the resolver's own
+   * error already owns — and an auto-inferred selector stamps no `selectorType`, so both skip.
+   */
+  private checkUnknownSelectorType(step: ParsedStep, mapped: MappedStep): MappedStep | null {
+    if (!step.selectorRef) return null;
+    let selectorType: unknown;
+    try {
+      selectorType = this.selectorResolver.resolveSelector(
+        step.selectorRef, this.featureName, step.elementType, step.nth,
+      ).selectorType;
+    } catch {
+      return null;   // missing key — the resolver's own error owns that
+    }
+    if (selectorType === undefined || isKnownSelectorType(selectorType)) return null;
+    const reason = `step "${step.text}" names selector "${step.selectorRef}", whose selectors.yaml `
+      + `entry declares type: "${String(selectorType)}" — not a selector type, so the entry `
+      + `resolved to a placeholder locator that cannot match. See SG-E027 for the valid types and `
+      + `the nearest spelling to what was written.`;
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `Unknown selector type "${String(selectorType)}" — see SG-E027: ${step.text}`,
+    };
+  }
+
   private checkAssertionClauseSwallowed(step: ParsedStep, mapped: MappedStep): MappedStep | null {
     const code = mapped.code || '';
     // Bare visibility: nothing but a visible/displayed assertion on one locator.
@@ -630,6 +722,42 @@ export class StepMapper {
     };
   }
 
+  /**
+   * A click step that names a POSITION (`at position "top-left"`, `at offset x=…, y=…`) must compile
+   * through the positioned-click form with a position it understood. Anything else — a typo in the
+   * keyword, a value the grammar rejects, or a combination another click form claims first (`try to
+   * click … at position`, `… at offset … and accept [OK] alert`, `… with {{v}} … at position`) —
+   * would otherwise click the element's CENTRE and pass, which for a backdrop-dismiss test is the
+   * one outcome that proves nothing. Owned by the compiler rather than the driver so it holds no
+   * matter which pattern wins.
+   */
+  private static readonly CLICK_POSITION_HINT =
+    /\bat\s+(?:position|offset)\b|\bat\s+\w+\s+(?:"(?:top|bottom)-(?:left|right)"|x\s*=)|\b(?:top|bottom)[- ](?:left|right)\b|\bat\s+x\s*=/i;
+
+  private checkClickPositionDropped(step: ParsedStep, mapped: MappedStep): MappedStep | null {
+    // Refs are masked; so is every quoted VALUE except a preset name — `with "Engineer at position 3"`
+    // is a text filter, not a position, while a mistyped `at postion "top-left"` must stay visible.
+    const masked = maskRefsForMatching(step.text)
+      .replace(/"([^"]*)"/g, (quoted, inner: string) => (/^(?:top|bottom)-(?:left|right)$/i.test(inner.trim()) ? quoted : '"~"'));
+    if (!/\bclick/i.test(masked) || !StepMapper.CLICK_POSITION_HINT.test(masked)) return null;
+    // Already refused upstream (off-platform SG-W020, a dropped state clause, a missing template…):
+    // that refusal names the real cause; this guard only exists to stop a SILENT centre click.
+    if (/^throw new Error\("\[sungen\]/.test(mapped.code.trim())) return null;
+    const refused = mapped.templateData?.positionError as string | undefined;
+    if (mapped.pattern === 'click-element-at-position' && !refused) return null;
+    const reason = refused
+      ? `step "${step.text}": ${refused}`
+      : `step "${step.text}" asks for a click position but compiled through the "${mapped.pattern ?? 'unknown'}" `
+        + 'step form, which clicks the element\'s centre — the position would be silently dropped. Write '
+        + 'it as `click [X] <type> at position "<preset>"` or `… at offset x=<n>px|%, y=<n>px|%` on its own: '
+        + '`try to click`, a `with {{v}}` text filter and `… and accept [OK] alert` do not take a position.';
+    this.diagnostics?.add('SG-E026', reason, { feature: this.featureName, step: step.text });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `Click position dropped — see SG-E026: ${step.text}`,
+    };
+  }
+
   private checkDataRefConsumed(step: ParsedStep, mapped: MappedStep): void {
     if (!step.dataRef || !this.diagnostics) return;
     const code = mapped.code || '';
@@ -839,6 +967,22 @@ export class StepMapper {
       { feature: this.featureName, step: step.text });
   }
 
+  /**
+   * SG-W028 — a trailing `in [X] <word>` scope clause whose `<word>` is not a container type.
+   *
+   * The clause is dropped, and everything downstream takes the FIRST `[ref]` and the FIRST
+   * `{{data}}` it finds, so the sentence compiles clean while the assertion silently widens to the
+   * whole screen (#667). Unlike an unrecognized STEP, which at least raises SG-W001, a partially
+   * understood step used to say nothing at all — and a check that runs against more than it names
+   * passes for the wrong reason in exactly the list-of-identical-cards case it was written for.
+   */
+  private warnScopeClauseDiscarded(step: ParsedStep): void {
+    if (!step.unsupportedScopeType) return;
+    this.diagnostics?.add('SG-W028',
+      `\`${step.unsupportedScopeType}\` is not a container type, so the scope clause was DROPPED and this step runs against the whole page, not the named container. Supported: ${PARENT_CONTAINER_TYPES.join(', ')}`,
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W021 — dialog scope is a no-op on the Appium adapter.
    *

package/src/generators/test-generator/template-engine.ts

@@ -1,7 +1,9 @@
 import Handlebars from 'handlebars';
+import { escapeSingleQuoted } from './utils/escape-js-string';
 import fs from 'fs';
 import path from 'path';
-import type { RenderImportsOptions } from './adapters/adapter-interface';
+import type { RenderImportsOptions, HookRenderData } from './adapters/adapter-interface';
+import { locatorIdentityKey } from './utils/dialog-scope-identity';
 
 export class TemplateEngine {
   private templates: Map<string, HandlebarsTemplateDelegate> = new Map();
@@ -28,16 +30,9 @@ export class TemplateEngine {
     // the result in '…' (selector values, attribute values, scope), so a value containing a newline,
     // backslash, or quote must be escaped or the generated spec is a syntax error (e.g. a Flutter
     // composite content-desc like "Quick Convert\nSelect File\n…" used as an accessibility-id).
-    // Order matters: backslash first, then the rest.
-    Handlebars.registerHelper('escapeQuotes', function(text: string) {
-      if (text == null) return '';
-      return String(text)
-        .replace(/\\/g, '\\\\')
-        .replace(/'/g, "\\'")
-        .replace(/\n/g, '\\n')
-        .replace(/\r/g, '\\r')
-        .replace(/\t/g, '\\t');
-    });
+    // The rule itself lives in utils/escape-js-string so the pattern layer, which builds some
+    // locator strings by hand, cannot drift from what the templates do.
+    Handlebars.registerHelper('escapeQuotes', (text: string) => escapeSingleQuoted(text));
 
     // Escape a raw string for embedding inside a REGEX LITERAL (/…/). Metacharacters first —
     // that class doubles a backslash, so the control-char passes below cannot be mis-read as
@@ -152,6 +147,17 @@ export class TemplateEngine {
       // element is dialog-rooted even if its role is portal-exempt (issue #465).
       const explicitDialog = this.scope === 'dialog';
       if (!this.inDialog && !explicitDialog) return 'page';
+      // The element being resolved IS the active scope's own dialog root (issue #692). Prefixing
+      // it with that root asks for a dialog nested inside itself —
+      // getByRole('dialog',{name:X}).getByRole('dialog',{name:X}) — which can never resolve, yet
+      // compiles clean and fails as a plain timeout reading "the dialog never opened". So the
+      // root is idempotent: re-asserting the dialog you are scoped inside means what it reads as.
+      // Skipped for a `with {{v}}` root, whose .filter({ hasText }) form is not expressible as
+      // the element's own locator — identity says nothing about it there.
+      if (this.inDialog && !this.dialogFilterText && this.dialogScopeKey &&
+          locatorIdentityKey(this) === this.dialogScopeKey) {
+        return 'page';
+      }
       // Portal-rendered roles (Radix/MUI/Headless UI/antd render option/menu/tooltip
       // layers onto document.body) live OUTSIDE the dialog's DOM subtree — wrapping
       // them in the dialog root guarantees a timeout. List comes from the app profile
@@ -297,7 +303,7 @@ export class TemplateEngine {
   }
 
   renderImports(options?: RenderImportsOptions): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock, urlAssertImports: options?.urlAssertImports, regexEscapeImport: options?.regexEscapeImport });
+    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi, needsMock: options?.needsMock, urlAssertImports: options?.urlAssertImports, regexEscapeImport: options?.regexEscapeImport, checkedStateImports: options?.checkedStateImports });
   }
 
   renderTestFile(data: {
@@ -332,21 +338,15 @@ export class TemplateEngine {
     return this.render('before-each', data);
   }
 
-  renderBeforeAll(data: {
-    steps: Array<{ comment?: string; code: string }>;
-  }): string {
+  renderBeforeAll(data: HookRenderData): string {
     return this.render('before-all', data);
   }
 
-  renderAfterEach(data: {
-    steps: Array<{ comment?: string; code: string }>;
-  }): string {
+  renderAfterEach(data: HookRenderData): string {
     return this.render('after-each', data);
   }
 
-  renderAfterAll(data: {
-    steps: Array<{ comment?: string; code: string }>;
-  }): string {
+  renderAfterAll(data: HookRenderData): string {
     return this.render('after-all', data);
   }
 

package/src/generators/test-generator/utils/data-resolver.ts

@@ -29,6 +29,27 @@ export class DataResolver {
     this.capturedVars.clear();
   }
 
+  // Vars bound by a `@beforeAll` hook's `@api:`/`@query:` preconditions. The hook runs before every
+  // test of the feature, so its bindings are readable from EVERY scenario — they survive the
+  // per-scenario clearCaptured(). Stored by head (`login`) and matched against the ref's head
+  // (`login.body.token` → `login`), since a scenario may read any sub-path of the bound response.
+  private featureCaptured = new Set<string>();
+
+  /** Register the head of a variable bound by the feature's `@beforeAll` hook (feature-scoped). */
+  registerFeatureCaptured(head: string): void {
+    this.featureCaptured.add(head);
+  }
+
+  /** Clear feature-scoped captured vars — call at the start of each feature. */
+  clearFeatureCaptured(): void {
+    this.featureCaptured.clear();
+  }
+
+  /** Runtime-only ref (scenario-captured, or bound by the feature's `@beforeAll` hook)? */
+  private isCaptured(dataRef: string): boolean {
+    return this.capturedVars.has(dataRef) || this.featureCaptured.has(dataRef.split(/[.[]/)[0]);
+  }
+
   constructor(testDataDir?: string, screenName?: string, runtimeMode: boolean = false) {
     this.testDataDir = testDataDir || path.join(process.cwd(), 'qa', 'test-data');
     this.screenName = screenName;
@@ -52,7 +73,7 @@ export class DataResolver {
   resolveData(dataRef: string, featureName?: string): string {
     // Captured vars exist only at runtime → emit a marker (→ testData.get) and
     // skip YAML validation. Requires runtime mode (capture writes testData.set).
-    if (this.capturedVars.has(dataRef)) {
+    if (this.isCaptured(dataRef)) {
       return DataResolver.encodeMarker(dataRef);
     }
 
@@ -75,7 +96,7 @@ export class DataResolver {
    * anything said about it belongs in a warning, never a gate.
    */
   peekBaseValue(dataRef: string, featureName?: string): string | undefined {
-    if (this.capturedVars.has(dataRef)) return undefined;
+    if (this.isCaptured(dataRef)) return undefined;
     try {
       return this.resolveValue(dataRef, featureName);
     } catch {

package/src/generators/test-generator/utils/dialog-scope-identity.ts

@@ -0,0 +1,71 @@
+/**
+ * Identity of a locator as the `locator` partial actually renders it — issue #692.
+ *
+ * `Given User is on [X] dialog` records a scope root, and the `pageRoot` helper prefixes every
+ * locator rendered afterwards with it. That is the whole point of the scope — except when a later
+ * step names the SAME element as the scope root, where the prefix nests the dialog inside itself:
+ *
+ *     page.getByRole('dialog', { name: 'Confirm' }).getByRole('dialog', { name: 'Confirm' })
+ *
+ * A dialog cannot contain itself, so that query can never resolve. It compiles clean, emits no
+ * diagnostic, and fails as a plain timeout — which reads as "the dialog never opened" rather than
+ * "the query is impossible". Re-asserting the dialog you are scoped inside is the natural thing to
+ * write straight after the `Given`, so the scope root is made idempotent instead.
+ *
+ * The guard needs exactly one question answered: does this element render to the same locator as
+ * the active scope root? So the key carries the fields the partial reads FOR THAT STRATEGY and
+ * nothing else — two entries share a key iff they render the same expression. Comparing role+name
+ * alone (the shape the issue first suggested) would miss `type: locator` and `type: testid`
+ * dialogs, which self-nest just the same.
+ *
+ * Deliberately says nothing about a `with {{v}}` filtered root: that root is
+ * `getByRole('dialog').filter({ hasText })`, which is not expressible as the element's own
+ * locator, so an identity match there would be meaningless. The caller skips the guard in that
+ * case — see the `dialogFilterText` check in `pageRoot`.
+ */
+
+/** The subset of a resolved selector that the `locator` partial reads. */
+export interface LocatorIdentityFields {
+  strategy?: string;
+  value?: string;
+  role?: string;
+  name?: string;
+  exact?: boolean;
+  nth?: number;
+  scope?: string;
+}
+
+/**
+ * A stable key for the locator `fields` renders to, or undefined when there is no strategy to
+ * render (nothing to compare, so no guard).
+ */
+export function locatorIdentityKey(fields: LocatorIdentityFields | undefined): string | undefined {
+  if (!fields || !fields.strategy) return undefined;
+
+  // `scope: dialog` is the dialog-rooting sentinel rather than part of the element's own
+  // identity — renderDialogRoot strips it before rendering the root for the same reason.
+  const scope = fields.scope && fields.scope !== 'dialog' ? fields.scope : '';
+  const nth = typeof fields.nth === 'number' && fields.nth >= 0 ? String(fields.nth) : '';
+  const exact = fields.exact ? '1' : '';
+
+  const parts: string[] = [];
+  switch (fields.strategy) {
+    case 'role':
+      // getByRole reads role/name/exact — never `value`.
+      parts.push('role', fields.role || '', fields.name || '', exact);
+      break;
+    case 'testid':
+      parts.push('testid', fields.value || '');
+      break;
+    case 'placeholder':
+    case 'label':
+    case 'text':
+      parts.push(fields.strategy, fields.value || '', exact);
+      break;
+    default:
+      // 'locator', 'id', 'css' and the partial's own default all render locator('<value>').
+      parts.push('locator', fields.value || '');
+  }
+
+  return [...parts, `nth=${nth}`, `scope=${scope}`].join('|');
+}

package/src/generators/test-generator/utils/escape-js-string.ts

@@ -0,0 +1,24 @@
+/**
+ * Escape a raw string for embedding inside a SINGLE-QUOTED JS string literal.
+ *
+ * Order matters: backslash first, or the escapes added afterwards get re-escaped. Getting this
+ * half-right is worse than not doing it — a value ending in `\` turns `'…\'` into an escaped
+ * closing quote, and the string literal runs on into the rest of the file, so the generated
+ * `.spec.ts` stops parsing and EVERY scenario in it is lost rather than the one step.
+ *
+ * The line terminators are not cosmetic either: a card's accessible text is routinely a composite
+ * of several lines (a Flutter content-desc, a multi-line heading), and a literal newline inside
+ * `'…'` is a syntax error.
+ *
+ * Lives here rather than inside the Handlebars helper because the pattern layer also builds locator
+ * strings by hand — the parent-scope chain among them — and two copies of this rule drift.
+ */
+export function escapeSingleQuoted(text: unknown): string {
+  if (text == null) return '';
+  return String(text)
+    .replace(/\\/g, '\\\\')
+    .replace(/'/g, "\\'")
+    .replace(/\n/g, '\\n')
+    .replace(/\r/g, '\\r')
+    .replace(/\t/g, '\\t');
+}

package/src/generators/test-generator/utils/nearest-match.ts

@@ -0,0 +1,55 @@
+/**
+ * Nearest-known-spelling suggestion, shared by the selector-surface checks.
+ *
+ * Two checks need the same judgement about the same class of author mistake — SG-W004 on an entry
+ * FIELD nobody reads (#712) and SG-E027 on an entry `type:` VALUE nothing dispatches (#711) — so
+ * the rule lives in one place rather than being re-tuned independently in each. The tuning is the
+ * substance here, not the edit distance:
+ *
+ *   - A case-only difference is returned first and always. `testId` for `testid` and
+ *     `contentEditable` for `contenteditable` are the single likeliest way to write either
+ *     wrongly, and both surfaces are lowercase throughout, so this is a near-certainty rather
+ *     than a guess.
+ *   - Otherwise a distance of 1-2 is a typo worth naming.
+ *   - Anything further is a DIFFERENT word, and guessing at it sends the author somewhere wrong.
+ *     `selector` is not a misspelling of `locator` — it is someone reasonably assuming a field
+ *     that does not exist, and "did you mean locator?" would be a worse answer than silence.
+ *     The caller supplies its own hint for that case.
+ */
+
+/** Levenshtein distance. Bounded use only — these are short identifiers. */
+function distance(a: string, b: string): number {
+  const m = a.length, n = b.length;
+  let prev = Array.from({ length: n + 1 }, (_, j) => j);
+  for (let i = 1; i <= m; i++) {
+    const curr = [i];
+    for (let j = 1; j <= n; j++) {
+      curr[j] = Math.min(
+        prev[j] + 1,
+        curr[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+
+/**
+ * The nearest candidate to `value`, when one is close enough to be a likely typo rather than a
+ * different word. Returns undefined when nothing is close enough to name honestly.
+ */
+export function nearestMatch(
+  value: string, candidates: Iterable<string>, maxDistance = 2,
+): string | undefined {
+  const lower = value.toLowerCase();
+  const all = [...candidates];
+  for (const c of all) if (c.toLowerCase() === lower) return c;
+  let best: string | undefined;
+  let bestDist = Infinity;
+  for (const c of all) {
+    const d = distance(lower, c.toLowerCase());
+    if (d < bestDist) { bestDist = d; best = c; }
+  }
+  return bestDist <= maxDistance ? best : undefined;
+}