@sun-asterisk/sungen 3.2.18 → 3.2.20

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

@@ -311,20 +311,29 @@ export class CodeGenerator {
     const activeCapabilityIds = this.activeCapabilityIds(feature);
     const needsDb = activeCapabilityIds.includes('db');
     const needsApi = activeCapabilityIds.includes('api');
+    const needsMock = activeCapabilityIds.includes('mock');
     for (const id of activeCapabilityIds) {
       for (const h of capabilityRegistry.get(id)?.runtimeHelpers ?? []) this.syncGeneratedHelper(outputDir, h.file, h.template);
     }
 
-    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi });
-
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
 
+    // `url-assert` is imported from what the body actually emitted, not from an active capability:
+    // page assertions belong to the DEFAULT ui capability, so a capability flag would import the
+    // helper into every UI spec — including the many that touch no URL at all. Hence the body is
+    // rendered BEFORE the imports. Importing exactly the names used keeps the import honest; the
+    // helper file itself is synced only when something needs it (an api-only unit carries none).
+    const urlAssertImports = ['urlMatches', 'joinPath'].filter((n) => testCode.includes(`${n}(`)).join(', ');
+    if (urlAssertImports) this.syncGeneratedHelper(outputDir, 'url-assert.ts', 'specs-url-assert.ts');
+
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock, urlAssertImports });
+
     // Combine and collapse any runs of 3+ newlines down to 2 (one blank line max)
     const raw = `${imports}\n\n${testCode}`;
     let code = raw.replace(/\n{3,}/g, '\n\n');
 
-    // Runtime data: replace __SUNGEN_TD_ markers with testData.get() calls
+    // Runtime data: replace __SUNGEN_TD$…$__ markers with testData.get() calls
     if (this.options.runtimeData) {
       code = transformToRuntimeData(code);
     }
@@ -382,15 +391,40 @@ export class CodeGenerator {
     const steps: ParsedStep[] = [];
     if (feature.background?.steps) steps.push(...feature.background.steps);
     for (const sc of feature.scenarios || []) if (sc.steps) steps.push(...sc.steps);
-    const scenarioTags = (feature.scenarios || []).flatMap((sc) => sc.tags || []);
+    // FEATURE-level tags count too: a feature-wide `@mock` must sync the helper and
+    // emit the import exactly like a per-scenario tag — reading scenario tags only
+    // left patterns matching while the helper/import never arrived, generating a
+    // spec that does not compile.
+    const tagPool = [
+      ...(feature.tags || []),
+      ...(feature.scenarios || []).flatMap((sc) => sc.tags || []),
+    ];
     const ids = new Set<string>();
     const def = capabilityRegistry.defaultCapabilityId();
     if (def) ids.add(def);
     for (const cap of capabilityRegistry.all()) {
-      const annoMatch = (cap.annotations ?? []).some((a) => scenarioTags.some((t) => t === a || t.startsWith(a + ':')));
+      const annoMatch = (cap.annotations ?? []).some((a) => tagPool.some((t) => t === a || t.startsWith(a + ':')));
       const stepMatch = cap.detectsStep ? steps.some((s) => s && typeof s.text === 'string' && cap.detectsStep!(s.text)) : false;
       if (annoMatch || stepMatch) ids.add(cap.id);
     }
+
+    // Opt-in driver ABSENT while the feature clearly wants it = hard error. Discovery
+    // swallows a missing driver silently and unmatched steps become warn-only TODOs —
+    // a "mocked" scenario would then run green against the REAL backend.
+    const wantsMock =
+      tagPool.some((t) => t === '@mock' || t.startsWith('@mock:') || t === '@network') ||
+      steps.some((s) => s && typeof s.text === 'string' && /\[[^\]]+\]\s+mock\s+(?:is\s+active|called)\b/i.test(s.text));
+    if (wantsMock && !capabilityRegistry.get('mock')) {
+      throw new Error(
+        `feature "${feature.name}" uses network mocking (@mock / mock steps) but the mock capability is not installed — run: sungen capability add mock`);
+    }
+    // Web-only: the runtime rides Playwright's page.route. Failing here beats a
+    // confusing "Cannot find name 'mock'" tsc error in the generated appium spec.
+    if (wantsMock && this.adapter.frameworkName === 'appium') {
+      throw new Error(
+        `feature "${feature.name}" uses network mocking (@mock / mock steps), which is web-only — mobile drivers have no request-interception seam. Keep these scenarios @manual on mobile.`);
+    }
+
     return [...ids];
   }
 
@@ -525,10 +559,33 @@ export class CodeGenerator {
       // tab`) is silently dropped and every scenario runs on the launcher. So branch on isParallel only
       // for web; for appium always use generateBackgroundSteps().
       const isMobile = this.adapter.frameworkName === 'appium';
+      const mockActive = !isMobile && this.activeCapabilityIds(feature).includes('mock');
       if (isParallel && !isMobile) {
-        background = await this.generateBeforeEach(feature.background);
+        background = await this.generateBeforeEach(
+          feature.background,
+          // The passthrough flag must be armed BEFORE the Background installs + goto —
+          // a scenario-body statement runs too late: boot-time requests of an opted-out
+          // scenario would be aborted and recorded as violations. beforeEach reads the
+          // scenario's own tags via test.info().
+          mockActive
+            ? [{
+                comment: '@mock:passthrough scenarios opt out before any mock installs',
+                code: this.indentCode("if (test.info().tags.includes('@mock:passthrough')) mock.setPassthrough(page);", 4),
+              }]
+            : [],
+        );
       } else {
         backgroundSteps = await this.generateBackgroundSteps(feature.background);
+        // @serial: Background (beforeAll) mocks + the guard must survive each scenario's
+        // scoped reset — snapshot them so reset() removes only scenario-added routes.
+        // Without this, scenario 1's reset kills the Background mocks and scenarios 2+
+        // run against the REAL backend with no guard.
+        if (mockActive && !isMobile) {
+          backgroundSteps.push({
+            comment: 'Background mocks persist across the @serial scenarios',
+            code: this.indentCode('await mock.snapshotBackground(page);', 4),
+          });
+        }
       }
     }
 
@@ -736,9 +793,12 @@ export class CodeGenerator {
     return steps;
   }
 
-  private async generateBeforeEach(background: ParsedScenario): Promise<string> {
+  private async generateBeforeEach(
+    background: ParsedScenario,
+    preambleSteps: Array<{ comment?: string; code: string }> = [],
+  ): Promise<string> {
     // Map all steps
-    const steps: Array<{ comment?: string; code: string }> = [];
+    const steps: Array<{ comment?: string; code: string }> = [...preambleSteps];
     for (const step of background.steps) {
       const mapped = await Promise.resolve(this.stepMapper.mapStep(step));
       steps.push({
@@ -885,6 +945,29 @@ export class CodeGenerator {
       steps.unshift(...preconditions.map((p) => ({ comment: p.comment, code: this.indentCode(p.code, 4) })));
     }
 
+    // Mock scenario epilogue. (a) EVERY path: the fail-on-unmocked verdict — the guard
+    // records+aborts unmatched requests (it must not throw inside a route handler:
+    // that surfaces as an unhandled rejection), so the scenario ends by asserting the
+    // violation list is empty. (b) @serial shared page only: a scoped reset so this
+    // scenario's routes/counters don't leak into the next (the router unroutes only
+    // what IT installed — never page.unrouteAll(), which would also kill Background
+    // mocks and third-party routes; the per-test path gets that free at page close).
+    const usesMock =
+      [...(featureTags || []), ...(scenario.tags || [])].some((t) => t === '@mock' || t.startsWith('@mock:') || t === '@network') ||
+      stepsToMap.some((s) => /\[[^\]]+\]\s+mock\s+is\s+active\b/i.test(s.text || ''));
+    if (usesMock && this.adapter.frameworkName !== 'appium' && capabilityRegistry.get('mock')) {
+      steps.push({
+        comment: 'Fail-on-unmocked verdict: any unmatched request aborted by the guard fails here',
+        code: this.indentCode('await mock.assertNoUnmocked(page);', 4),
+      });
+      if (!isParallel) {
+        steps.push({
+          comment: 'Reset mock routes and counters (shared @serial page)',
+          code: this.indentCode('await mock.reset(page);', 4),
+        });
+      }
+    }
+
     // Extract pass-through tags (feature + scenario, excluding functional tags)
     const tags = extractPassThroughTags(scenario.tags, featureTags);
 

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

@@ -20,12 +20,27 @@
  *   SG-W010 — a row step's [Ref] looks POSITIONAL (First/Last/Top/…) but has no selectors.yaml
  *             entry: the label is display-only, so the step checks existence anywhere in the
  *             table — an ordering rule would pass even when the row moved
+ *   SG-W011 — a storage assertion written in `expect … in local/session storage` form:
+ *             `expect` steps only read `{{response}}` refs, so this compiles to a silent
+ *             no-op — the supported grammar is `User see [KEY] in local storage exists/…`
+ *   SG-W012 — a mock-install step AFTER a navigation step in the same block: page.route()
+ *             registered after goto() misses every request fired during page load — move
+ *             the install before the navigation (or into Background)
+ *   SG-W013 — a page assertion whose path came from a FALLBACK, not from a `type: page` selector
+ *             entry: the `[Ref]` did not resolve (or resolved to a non-page entry), so the step
+ *             asserts the feature's own path (or `/<ref>/`) instead of the page it names. The
+ *             assertion is anchored, so this is now a test that cannot pass rather than one that
+ *             always passed — either way it is not asserting what it reads as
+ *   SG-W014 — `[X] page with {{v}}` where the value carries no query and no fragment: there is
+ *             nothing for the query half to assert, so the step checks the PATH only. Not an
+ *             error (the value may legitimately vary per environment), but the step asserts
+ *             strictly less than it appears to
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010';
+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';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/recipe-expander.ts

@@ -21,7 +21,7 @@
 export interface RecipeExpandContext {
   /** Pre-rendered locator code for the widget element (dialog/frame scoping included). */
   triggerCode: string;
-  /** The step's value — a literal or a __SUNGEN_TD__ runtime marker. */
+  /** The step's value — a literal or a __SUNGEN_TD$…$__ runtime marker. */
   value: string;
 }
 
@@ -53,7 +53,7 @@ function expandPrimitive(prim: unknown, ctx: RecipeExpandContext, itemVar: strin
   const targetExpr = (v: unknown): string =>
     v === '$trigger' ? ctx.triggerCode : `page.locator('${escape(String(v))}')`;
   // Resolve a `$value`/`$item`/literal into a JS value EXPRESSION (quoted unless $item;
-  // a quoted __SUNGEN_TD__ marker is rewritten to testData.get(...) by the runtime transform).
+  // a quoted __SUNGEN_TD$…$__ marker is rewritten to testData.get(...) by the runtime transform).
   const valueExpr = (v: unknown): string => {
     if (v === '$item') {
       if (!itemVar) throw new Error('$item is only valid inside forEach');

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

@@ -43,6 +43,8 @@ export class StepMapper {
   private tableRowDeclared: boolean = false;
   /** SG-W007: an action step already ran in this scenario (alert handlers registered after it are too late) */
   private sawActionStep: boolean = false;
+  /** SG-W012: a navigation already ran in this scenario (mocks installed after it miss page-load requests) */
+  private sawNavigationStep: boolean = false;
   /** Compile-time warning channel (SG-W001/W002); optional — absent means silent legacy behavior */
   private diagnostics?: DiagnosticsCollector;
   /** App profile (qa/app.yaml merged over presets/defaults) — the per-project BEHAVIOR layer */
@@ -91,6 +93,14 @@ export class StepMapper {
     this.featureName = featureName;
     this.featurePath = featurePath;
     this.selectorResolver.setFeatureContext(featureName);
+    // One StepMapper serves every feature in a run, so the step counter that names the
+    // generated temporaries (`__t_<n>`) used to carry over between files: a screen's spec
+    // then depended on how many steps the PRECEDING files happened to contain — i.e. on
+    // readdir order and on whether the run was `--all` or `--screen`. Same input, different
+    // output, which is exactly what a deterministic compiler must not do (and what made a
+    // multi-feature screen report permanent false DRIFT in script-check). The counter only
+    // needs to be unique WITHIN one spec file, so it restarts with each feature.
+    this.stepCounter = 0;
   }
 
   /**
@@ -137,6 +147,7 @@ export class StepMapper {
     this.tableRowScopeSteps = steps.filter((s) => this.isRowScopeEntryStep(s)).length;
     this.tableRowDeclared = false;
     this.sawActionStep = false;
+    this.sawNavigationStep = false;
     this.lastPrimaryKeyword = 'Given';
     this.dataResolver.clearCaptured(); // captured vars are scenario-scoped
     this.templateEngine.resetBaseContext();
@@ -181,6 +192,20 @@ export class StepMapper {
       this.sawActionStep = true;
     }
 
+    // A mock must be routed BEFORE the navigation whose requests it should intercept —
+    // page.route() registered after goto() misses everything fired during page load
+    // (mirror of the late-alert-listener check above). Background installs compile
+    // into beforeEach, before any scenario step, so they never trip this.
+    const isMockInstallStep = /\[[^\]]+\]\s+mock\s+is\s+active\b/i.test(step.text);
+    if (isMockInstallStep && this.sawNavigationStep) {
+      this.diagnostics?.add('SG-W012',
+        'mock installed AFTER a navigation step — requests fired during page load were not intercepted. Move the mock step before the navigation, or declare it in Background',
+        { feature: this.featureName, step: step.text });
+    } else if (!isMockInstallStep && step.elementType === 'page' &&
+      /\b(?:is on|navigates?\s+to|opens?)\b/i.test(step.text)) {
+      this.sawNavigationStep = true;
+    }
+
     // Frame scope directives — intercept before pattern matching
     if (/\bswitch(?:es)?\s+to\b/i.test(step.text) &&
         (step.elementType === 'frame' || step.elementType === 'iframe')) {
@@ -221,7 +246,14 @@ export class StepMapper {
     // Given User is on [...] dialog — set dialog scope (3 cases)
     if (step.text.includes('is on') && step.elementType === 'dialog') {
       this.inDialogScope = true;
-      const contextVars: Record<string, any> = { inDialog: true };
+      // setBaseContext MERGES — clear every root key so a previous dialog scope in the
+      // same scenario cannot leak its root into this one.
+      const contextVars: Record<string, any> = {
+        inDialog: true,
+        dialogRootExpr: undefined,
+        dialogRoleName: undefined,
+        dialogFilterText: undefined,
+      };
 
       if (step.selectorRef && step.dataRef) {
         // Case 3: [panel] dialog with {{value}}
@@ -234,16 +266,18 @@ export class StepMapper {
           filterText = `\${${step.dataRef}}`;
         }
         contextVars.dialogFilterText = filterText;
+        // The declared entry still owns the ROOT the filter applies to — but only when it
+        // is a non-role strategy (locator/testid/css). A role entry keeps the bare
+        // getByRole('dialog') base on purpose here: the name is dynamic, hence the filter.
+        const rootExpr = this.renderDialogRoot(step.selectorRef, { nonRoleOnly: true });
+        if (rootExpr) contextVars.dialogRootExpr = rootExpr;
       } else if (step.selectorRef) {
-        // Case 2: [Title] dialog → named dialog role
-        let roleName = step.selectorRef;
-        try {
-          const resolved = this.selectorResolver.resolveSelector(step.selectorRef, this.featureName, 'dialog', 0);
-          roleName = resolved.name || step.selectorRef;
-        } catch {
-          roleName = step.selectorRef;
-        }
-        contextVars.dialogRoleName = roleName;
+        // Case 2: [Title] dialog → the root the DECLARED selectors.yaml entry asks for
+        // (issue: an explicit `type: locator` / `value: '[role="dialog"]'` was being
+        // discarded in favour of getByRole('dialog', { name: <reference text> })).
+        const rootExpr = this.renderDialogRoot(step.selectorRef);
+        if (rootExpr) contextVars.dialogRootExpr = rootExpr;
+        else contextVars.dialogRoleName = step.selectorRef;
       }
       // Case 1: no selectorRef → plain page.getByRole('dialog')
 
@@ -299,20 +333,127 @@ export class StepMapper {
         console.log(`  ✓ Pattern matched: ${step.text.substring(0, 50)}...`);
       }
       this.checkDataRefConsumed(step, mappedStep);
+      this.checkPageAssertionFallback(step, mappedStep);
+      this.checkDeclaredUrlHasNoQuery(step, mappedStep);
       return mappedStep;
     }
 
     // No pattern matched - return TODO comment
-    this.diagnostics?.add('SG-W001', 'step matched no pattern — compiled to a no-op // TODO comment', {
-      feature: this.featureName,
-      step: step.text,
-    });
+    if (/\bexpect\b.*\b(?:local|session)\s+storage\b/i.test(step.text)) {
+      // The natural first guess for a storage check — but `expect` steps only read
+      // {{response}} refs, so this shape silently compiles to nothing. Point at the
+      // supported grammar instead of emitting the generic no-pattern warning.
+      this.diagnostics?.add('SG-W011',
+        'storage assertions use `User see [KEY] in local storage exists` (also: does not exist / is not empty / has length {{n}} / key matching "PATTERN") — the `expect …` form compiles to a no-op', {
+        feature: this.featureName,
+        step: step.text,
+      });
+    } else {
+      this.diagnostics?.add('SG-W001', 'step matched no pattern — compiled to a no-op // TODO comment', {
+        feature: this.featureName,
+        step: step.text,
+      });
+    }
     return {
       code: `// TODO: Implement step: ${step.text}`,
       comment: `Unrecognized step pattern: ${step.text}`,
     };
   }
 
+  /** Strategies the `locator` partial renders into a usable ROOT expression. Anything else
+   *  (mobile native strategies) has no meaning as a Playwright dialog root. */
+  private static readonly DIALOG_ROOT_STRATEGIES = ['locator', 'testid', 'role', 'id', 'label', 'text', 'placeholder'];
+
+  /**
+   * Render the Playwright root expression for `Given User is on [X] dialog` from the entry
+   * DECLARED in selectors.yaml, through the same `locator` partial every other step renders
+   * with — so `type: locator`, `type: testid`, a non-`dialog` role, `name: null`, `exact:`
+   * and `nth:` mean here exactly what they mean everywhere else. Before this, the entry was
+   * read for its `name` only and the root was hardcoded to getByRole('dialog', { name }),
+   * silently discarding an explicit `type: locator` / `value: '[role="dialog"]'`.
+   *
+   * Returns undefined when the reference does not resolve to a usable root — the caller then
+   * falls back to the legacy named-dialog root, so behavior is unchanged for those entries.
+   */
+  private renderDialogRoot(selectorRef: string, opts: { nonRoleOnly?: boolean } = {}): string | undefined {
+    let resolved: any;
+    try {
+      resolved = this.selectorResolver.resolveSelector(selectorRef, this.featureName, 'dialog', 0);
+    } catch {
+      return undefined;
+    }
+    if (!resolved) return undefined;
+
+    // `type: role` + a `locator:` field collapses to strategy 'css', which the locator partial
+    // has no case for — normalize it to the raw-locator strategy it actually means.
+    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;
+  }
+
+  /**
+   * 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.
+   *
+   * 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
+   * duplicates no logic — the alternative is widening the adapter contract for every driver.
+   */
+  private checkPageAssertionFallback(step: ParsedStep, mapped: MappedStep): void {
+    if (!this.diagnostics || !step.selectorRef || step.elementType !== 'page') return;
+    if (!(mapped.code || '').includes('urlMatches(')) return;
+    let resolvedAsPage = false;
+    try {
+      const resolved = this.selectorResolver.resolveSelector(
+        step.selectorRef, this.featureName, step.elementType, step.nth
+      );
+      resolvedAsPage = resolved.selectorType === 'page' && !!resolved.value;
+    } catch {
+      resolvedAsPage = false;
+    }
+    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'"`,
+      { feature: this.featureName, step: step.text });
+  }
+
+  /**
+   * SG-W014 — `[X] page with {{v}}` where the value carries neither a query nor a fragment, so the
+   * query half of the assertion has nothing to check and the step asserts the PATH only.
+   *
+   * Deliberately a warning, not an error, and deliberately judged on the BASE test-data value: an
+   * env overlay can supply a query the base file lacks, so failing generation here would block a
+   * suite over data that is fine at run time. But it must not be silent either — asserting less
+   * than the step reads as is exactly the false-positive class this assertion exists to remove.
+   * Distinct from SG-W002: there the value is DROPPED, here it is used and found to hold no query.
+   */
+  private checkDeclaredUrlHasNoQuery(step: ParsedStep, mapped: MappedStep): void {
+    if (!this.diagnostics || !step.dataRef || step.elementType !== 'page') return;
+    if (!(mapped.code || '').includes('urlMatches(')) return;
+    // The base value, never resolveData(): in runtime mode that returns the marker, which carries
+    // no query by construction — the diagnostic would then fire on every single step.
+    const value = this.dataResolver.peekBaseValue(step.dataRef, this.featureName);
+    if (value == null || /[?#]/.test(value)) return;
+    this.diagnostics.add('SG-W014',
+      `{{${step.dataRef}}} = "${value}" carries no query and no fragment, so this page assertion checks the PATH only. Pass a value like "?q=…" (or drop the "with" and let the step assert a bare page).`,
+      { feature: this.featureName, step: step.text });
+  }
+
   /**
    * SG-W002 — a step carried a parsed {{dataRef}} but the matched pattern's generated
    * code never uses it (neither the runtime marker, the ${ref} fallback, nor the
@@ -323,7 +464,11 @@ export class StepMapper {
   private checkDataRefConsumed(step: ParsedStep, mapped: MappedStep): void {
     if (!step.dataRef || !this.diagnostics) return;
     const code = mapped.code || '';
-    if (code.includes(DataResolver.encodeMarker(step.dataRef))) return; // runtime marker
+    // Runtime marker — in both spellings: templates that embed the value into a regex
+    // literal run it through the escapeRegex helper, which escapes the marker's `$`
+    // delimiters, so the code may carry `__SUNGEN_TD\$key\$__` instead of the plain form.
+    const marker = DataResolver.encodeMarker(step.dataRef);
+    if (code.includes(marker) || code.includes(marker.replace(/\$/g, '\\$'))) return;
     if (code.includes(`\${${step.dataRef}}`)) return;                    // unresolved fallback
     if (code.includes(step.dataRef)) return;                             // testData.set('ref'), comments
     try {

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

@@ -277,8 +277,8 @@ export class TemplateEngine {
     this.baseContext = { ...this.persistentContext };
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
-    return this.render('imports', { runtimeData: options?.runtimeData, basePath: options?.basePath || '..', isParallel: options?.isParallel, needsCleanupImport: options?.needsCleanupImport, needsDb: options?.needsDb, needsApi: options?.needsApi });
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean; urlAssertImports?: string }): 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 });
   }
 
   renderTestFile(data: {

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

@@ -64,6 +64,25 @@ export class DataResolver {
     return this.resolveValue(dataRef, featureName);
   }
 
+  /**
+   * The value as the BASE test-data file spells it, whatever the mode — for compile-time
+   * diagnostics that must judge the value itself, not the `__SUNGEN_TD$…$__` marker that
+   * `resolveData` returns in runtime mode.
+   *
+   * Returns undefined rather than throwing when the ref cannot be read (unknown path, or a
+   * captured var that only exists at runtime): a diagnostic must never break generation. Callers
+   * must treat the result as the base value only — an env overlay can change it at run time, so
+   * 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;
+    try {
+      return this.resolveValue(dataRef, featureName);
+    } catch {
+      return undefined;
+    }
+  }
+
   private resolveValue(dataRef: string, featureName?: string): string {
     const { fileName, valuePath } = this.parseDataRef(dataRef, featureName);
     const data = this.loadDataFile(fileName);
@@ -112,12 +131,15 @@ export class DataResolver {
     return { fileName: parts[0], valuePath: parts.slice(1) };
   }
 
+  /**
+   * Encode a test-data ref as an opaque wire marker: `__SUNGEN_TD$<key>$__`,
+   * dots escaped to `_D_`. `$` delimiters keep the key boundary unambiguous
+   * when the surrounding text continues with underscores (`{{code}}_SUFFIX`)
+   * while the marker stays a single JS-identifier-safe token. This is the ONLY
+   * producer; the only decoder lives in runtime-data-transformer.ts.
+   */
   static encodeMarker(ref: string): string {
-    return `__SUNGEN_TD_${ref.replace(/\./g, '_D_')}__`;
-  }
-
-  static decodeMarker(encoded: string): string {
-    return encoded.replace(/^__SUNGEN_TD_/, '').replace(/__$/, '').replace(/_D_/g, '.');
+    return `__SUNGEN_TD$${ref.replace(/\./g, '_D_')}$__`;
   }
 
   /**

package/src/generators/test-generator/utils/runtime-data-transformer.ts

@@ -1,8 +1,54 @@
-const MARKER_PATTERN = /__SUNGEN_TD_([A-Za-z0-9_]+)__/;
+/**
+ * Wire format of a runtime test-data marker: `__SUNGEN_TD$<key>$__`.
+ *
+ * `$` delimits the encoded key on both sides. The key alphabet is [A-Za-z0-9_]
+ * (dots in refs are escaped to `_D_` by DataResolver.encodeMarker), so a `$`
+ * can never occur INSIDE a key — the `$__` terminator stays unambiguous even
+ * when the surrounding literal continues with underscore text. The previous
+ * `__SUNGEN_TD_<key>__` format could not tell its `__` terminator apart from a
+ * `_`-leading suffix: in `'{{code}}_ACCESS_TOKEN'` the greedy key class
+ * swallowed one `_` of the `___` run and decoding produced `get('code_')` plus
+ * a detached `ACCESS_TOKEN`. `$` is also identifier-safe — the whole marker
+ * still parses as ONE bare JS token, so it survives the bare-identifier
+ * (numeric) positions Pass 3 handles.
+ *
+ * Single source of truth: every pass and every whole-literal probe below is
+ * built from these constants. Invariant: every marker producer goes through
+ * DataResolver.encodeMarker and every consumer through this module — a
+ * drifting hand-copied char class is what let the suffix bug hide.
+ */
+const MARKER_KEY = '[A-Za-z0-9_]+';
+// Templates that embed a value into a regex literal run it through the escapeRegex
+// Handlebars helper first (template-engine.ts), which escapes `$` — so a marker can
+// arrive here spelled `__SUNGEN_TD\$key\$__`. `\\\\?` accepts that optional backslash
+// before each delimiter; the replacement consumes it, so no escape leaks to output.
+const DELIM = '\\\\?\\$';
+/** Marker with no capture group — for "contains a marker" positions inside bigger regexes. */
+const MARKER = `__SUNGEN_TD${DELIM}${MARKER_KEY}${DELIM}__`;
+/** Marker capturing the encoded key. */
+const MARKER_CAP = `__SUNGEN_TD${DELIM}(${MARKER_KEY})${DELIM}__`;
+
+const MARKER_PATTERN = new RegExp(MARKER);
+// Pass 0: full-line // comments carrying a marker (anchored — see pass comment).
+const RE_COMMENT_LINE = new RegExp(`^(\\s*)\\/\\/(.*)${MARKER_CAP}(.*)$`, 'gm');
+// Pass 1: a quoted string literal containing at least one marker. Covers ', " and
+// backtick containers; `\\.` lets an ESCAPED quote (`'it\'s {{x}}'`) sit inside the
+// body instead of terminating the literal early. The single-char branch excludes `\`
+// so every backslash is consumed by exactly ONE branch — an ambiguous `(?!\1).`
+// alternative enumerates 2^n segmentations when a marker-less escape-heavy literal
+// (escapeQuotes output: multi-line Flutter content-desc) fails to match, hanging
+// the generate run. `\n` exclusion just makes the dot's no-newline behavior explicit.
+const RE_STRING_LITERAL = new RegExp('([\'"`])((?:\\\\.|(?!\\1)[^\\\\\\n])*?' + MARKER + '(?:\\\\.|(?!\\1)[^\\\\\\n])*)\\1', 'g');
+// Pass 2: a single-line regex literal containing at least one marker.
+const RE_REGEX_LITERAL = new RegExp(`\\/((?:[^/\\\\\\n]|\\\\.)*?${MARKER}(?:[^/\\\\\\n]|\\\\.)*)\\/([gimsuy]*)`, 'g');
+// Whole-literal probe: the body is EXACTLY one marker (bare accessor call, no template).
+const RE_WHOLE_MARKER = new RegExp(`^${MARKER_CAP}$`);
+// Every marker occurrence, capturing the key (Pass 3 + interpolation).
+const RE_MARKER_G = new RegExp(MARKER_CAP, 'g');
 
 /**
- * Replace __SUNGEN_TD_ markers with testData.get() calls in generated code.
- * Three passes: comments, string literals, then regex literals.
+ * Replace __SUNGEN_TD$…$__ markers with testData.get() calls in generated code.
+ * Four passes: comments, string literals, regex literals, then bare identifiers.
  */
 export function transformToRuntimeData(code: string, accessor: string = 'testData'): string {
   // Pass 0: Comments — replace markers in // comments with decoded key name.
@@ -14,7 +60,7 @@ export function transformToRuntimeData(code: string, accessor: string = 'testDat
   // testData.get() (silent: `toHaveAttribute('href', 'official_site_url')`). Generated
   // comments are always full-line, so anchoring loses nothing.
   code = code.replace(
-    /^(\s*)\/\/(.*)__SUNGEN_TD_([A-Za-z0-9_]+)__(.*)$/gm,
+    RE_COMMENT_LINE,
     (_, indent, before, enc, after) => `${indent}//${before}${decodeKey(enc)}${after}`
   );
 
@@ -30,22 +76,22 @@ export function transformToRuntimeData(code: string, accessor: string = 'testDat
   // 'marker'          → testData.get('key')
   // 'a__m1__b__m2__c' → `a${testData.get('k1')}b${testData.get('k2')}c`
   code = code.replace(
-    /(['"])((?:(?!\1).)*?__SUNGEN_TD_[A-Za-z0-9_]+__(?:(?!\1).)*)\1/g,
+    RE_STRING_LITERAL,
     (_, _quote, body) => {
-      const whole = /^__SUNGEN_TD_([A-Za-z0-9_]+)__$/.exec(body);
+      const whole = RE_WHOLE_MARKER.exec(body);
       if (whole) return `${accessor}.get('${decodeKey(whole[1])}')`;
       return `\`${interpolateMarkers(body, accessor)}\``;
     }
   );
 
-  // Pass 2: Regex literal context — /…__marker__…/ → new RegExp(`…`). Same
+  // Pass 2: Regex literal context — /…$marker$…/ → new RegExp(`…`). Same
   // several-markers-per-literal rule as Pass 1 (/{{min}}-{{max}} items/).
   // Only matches within a single line (no newlines in the body).
   code = code.replace(
-    /\/((?:[^/\\\n]|\\.)*?__SUNGEN_TD_[A-Za-z0-9_]+__(?:[^/\\\n]|\\.)*)\/([gimsuy]*)/g,
+    RE_REGEX_LITERAL,
     (_, body, flags) => {
       const flagStr = flags ? `, '${flags}'` : '';
-      const whole = /^__SUNGEN_TD_([A-Za-z0-9_]+)__$/.exec(body);
+      const whole = RE_WHOLE_MARKER.exec(body);
       if (whole) return `new RegExp(${accessor}.get('${decodeKey(whole[1])}')${flagStr})`;
       return `new RegExp(\`${interpolateMarkers(body, accessor)}\`${flagStr})`;
     }
@@ -55,7 +101,7 @@ export function transformToRuntimeData(code: string, accessor: string = 'testDat
   // sits as a bare token in a numeric position (e.g. `toHaveCount(__marker__)` from the
   // table/list count templates). testData.get() returns a string, so coerce with Number().
   code = code.replace(
-    /__SUNGEN_TD_([A-Za-z0-9_]+)__/g,
+    RE_MARKER_G,
     (_, enc) => `Number(${accessor}.get('${decodeKey(enc)}'))`
   );
 
@@ -72,5 +118,5 @@ function decodeKey(encoded: string): string {
 
 /** Replace every marker in a literal's body with a `${accessor.get('key')}` interpolation. */
 function interpolateMarkers(body: string, accessor: string): string {
-  return body.replace(/__SUNGEN_TD_([A-Za-z0-9_]+)__/g, (_, enc) => `\${${accessor}.get('${decodeKey(enc)}')}`);
+  return body.replace(RE_MARKER_G, (_, enc) => `\${${accessor}.get('${decodeKey(enc)}')}`);
 }