@sun-asterisk/sungen 3.2.18 → 3.2.19

package/src/exporters/scenario-merger.ts

@@ -56,27 +56,34 @@ export interface MergedScenario {
   spec: SpecTest | null;
 
   /**
-   * When/Then/Given steps with any `@extend:<name>` chain pre-resolved
-   * against the matching `@steps:<name>` base scenario (its steps are
-   * prepended). Use these for surfaces that show the test case text
-   * (dashboard Steps section) so we get the canonical feature wording
-   * without re-parsing compiled spec.ts comments.
+   * Feature Background steps, kept separate from `resolvedSteps` so the
+   * exporters render them in the Pre-condition column. Inlining them into
+   * Steps shifted the step numbering against the .feature source, which made
+   * QA's Gherkin-vs-export review a manual re-mapping exercise.
    */
-  resolvedWhenSteps:  string[];
-  resolvedThenSteps:  string[];
-  resolvedGivenSteps: string[];
+  resolvedBackgroundSteps: OrderedStep[];
   /**
    * Steps section for display, in chronological order:
-   *   Background (all) → @extend base (all incl. its Then) → own up to the
-   *   first `Then`. Base's `Then` stays here because it's mid-flow setup,
-   *   not the scenario's final assertion.
+   *   @extend base (all incl. its Then) → own given/when-bucket steps.
+   *   Base's `Then` stays here because it's mid-flow setup, not the
+   *   scenario's final assertion. Background is NOT included — it renders
+   *   as Pre-condition (see `resolvedBackgroundSteps`).
    */
   resolvedSteps: OrderedStep[];
   /**
-   * Expected results — own scenario's first `Then` onwards. Empty when the
-   * scenario has no `Then`.
+   * Expected results — own scenario's then-bucket steps (a `When` after a
+   * `Then` starts a new action and goes back to Steps; an `And` follows its
+   * preceding explicit keyword). Empty when the scenario has no `Then`.
    */
   resolvedExpected: OrderedStep[];
+  /**
+   * Count of anchor-eligible action lines (@extend base + own given/when
+   * steps). This — NOT the rendered Steps length — is the reference for the
+   * "is any assertion mid-flow?" check in groupExpectedByAnchor: manual-comment
+   * steps are appended to resolvedSteps but never participate in anchoring,
+   * so counting them would falsely mark @manual scenarios as interleaved.
+   */
+  resolvedAnchorActionCount: number;
 }
 
 /**
@@ -98,20 +105,40 @@ export function mergeFeatureAndSpec(
     if (isStepsBaseScenario(scenario)) continue;       // skip @steps base scenarios
     if (isSampleScaffoldScenario(scenario)) continue;  // skip default sample
 
-    const specTest = findMatchingSpecTest(scenario, spec.tests);
+    const specTest = findMatchingSpecTest(scenario, spec.tests, feature.scenarios);
     const base = scenario.extendsName ? stepsBaseByName.get(scenario.extendsName) : undefined;
 
     // Order of execution for a runnable scenario:
-    //   1. Feature Background (once) — all buckets are setup, stay in Steps.
+    //   1. Feature Background (once) — setup state, rendered as Pre-condition
+    //      so Steps numbering stays aligned with the .feature scenario.
     //   2. @extend base scenario's own steps (if any) — *including* its Then,
     //      because the base's Then is a mid-flow assertion, not the scenario's
     //      final verification.
-    //   3. This scenario's own steps in original sequence, split at the
-    //      first `Then`: pre-Then → Steps, Then-onwards → Expected results.
+    //   3. This scenario's own steps, partitioned by BUCKET (not by position):
+    //      given/when → Steps, then → Expected results. A positional split at
+    //      the first `Then` broke interleaved scenarios (When → Then → When →
+    //      Then …): every later `When` action was exported as an "expected
+    //      result". classifySteps already resolves `And` to its preceding
+    //      explicit keyword, so an `And` after `Then` stays an assertion and
+    //      an `And` after `When` stays an action. Relative order is preserved
+    //      within each column.
+    //      Each assertion also records its ANCHOR — the 1-based index of the
+    //      last action before it in the rendered Steps column (@extend base
+    //      steps count toward the numbering; Background does not, it renders
+    //      as Pre-condition). The exporters use anchors to append
+    //      "— after step N" when a scenario interleaves actions and
+    //      assertions, restoring the correspondence the 2-column layout loses.
     const ownOrdered = scenario.orderedSteps;
-    const firstThenIdx = ownOrdered.findIndex((s) => s.bucket === 'then');
-    const ownPreThen = firstThenIdx >= 0 ? ownOrdered.slice(0, firstThenIdx) : ownOrdered;
-    const ownPostThen = firstThenIdx >= 0 ? ownOrdered.slice(firstThenIdx) : [];
+    const baseLen = base?.orderedSteps.length ?? 0;
+    const ownActions: OrderedStep[] = [];
+    const ownAssertions: OrderedStep[] = [];
+    for (const s of ownOrdered) {
+      if (s.bucket === 'then') {
+        ownAssertions.push({ ...s, anchorStep: baseLen + ownActions.length });
+      } else {
+        ownActions.push(s);
+      }
+    }
 
     // A @manual scenario carries no Gherkin steps — its tester procedure lives in the
     // `# Tester verifies:` comment block. Parse it into Steps (Setup/Action) + Expected
@@ -125,49 +152,60 @@ export function mergeFeatureAndSpec(
     result.push({
       feature: scenario,
       spec: specTest,
-      resolvedWhenSteps: [
-        ...feature.backgroundWhenSteps,
-        ...(base?.rawWhenSteps ?? []),
-        ...scenario.rawWhenSteps,
-      ],
-      resolvedThenSteps: [
-        ...feature.backgroundThenSteps,
-        ...(base?.rawThenSteps ?? []),
-        ...scenario.rawThenSteps,
-      ],
-      resolvedGivenSteps: [
-        ...feature.backgroundGivenSteps,
-        ...(base?.rawGivenSteps ?? []),
-        ...scenario.rawGivenSteps,
-      ],
+      resolvedBackgroundSteps: feature.backgroundOrderedSteps,
       resolvedSteps: [
-        ...feature.backgroundOrderedSteps,
         ...(base?.orderedSteps ?? []),
-        ...ownPreThen,
+        ...ownActions,
         ...manualParsed.steps,
       ],
-      resolvedExpected: [...ownPostThen, ...manualParsed.expected],
+      resolvedExpected: [...ownAssertions, ...manualParsed.expected],
+      resolvedAnchorActionCount: baseLen + ownActions.length,
     });
   }
 
   return result;
 }
 
+/** `@manual` / `@manual:<reason>` — a manual scenario has no automated test by definition. */
+function isManualScenario(scenario: ScenarioMetadata): boolean {
+  return scenario.tags.some((t) => t === '@manual' || t.startsWith('@manual:'));
+}
+
 /**
  * Find the spec test that corresponds to a given feature scenario.
  * Match by scenario title (exact match on the scenario name).
+ *
+ * The VP-ID fallback exists only to survive small TITLE drift between compile
+ * and export — it must never RE-ASSIGN a result to a different scenario. Field
+ * report: a feature carried the same VP id on many scenarios (VP-NAV-001 ×14,
+ * mixing @manual and automated); the old first-match fallback attached an
+ * automated sibling's executed result to every @manual sibling, so 7 testcases
+ * nobody ever ran shipped as "Passed" in the client deliverable. Two guards:
+ *   1. a @manual scenario never matches ANY test;
+ *   2. the fallback applies only when the vpId is UNIQUE on both sides —
+ *      exactly one test AND exactly one automatable scenario carry it.
+ * Ambiguity → null → the row reports an honest "Pending".
  */
-function findMatchingSpecTest(scenario: ScenarioMetadata, tests: SpecTest[]): SpecTest | null {
+function findMatchingSpecTest(
+  scenario: ScenarioMetadata,
+  tests: SpecTest[],
+  allScenarios: ScenarioMetadata[],
+): SpecTest | null {
+  if (isManualScenario(scenario)) return null;
+
   // Exact title match
   const exact = tests.find((t) => t.scenarioName === scenario.name);
   if (exact) return exact;
 
-  // Fallback: match by VP-ID prefix (ignore trailing text differences)
+  // Fallback: match by VP-ID prefix — only when unique both ways (see above).
   const vpMatch = scenario.name.match(SCENARIO_ID);
   if (vpMatch) {
     const vpId = vpMatch[1];
-    const byVp = tests.find((t) => t.vpId === vpId);
-    if (byVp) return byVp;
+    const testsWithVp = tests.filter((t) => t.vpId === vpId);
+    const scenariosWithVp = allScenarios.filter(
+      (s) => !isManualScenario(s) && s.name.match(SCENARIO_ID)?.[1] === vpId,
+    );
+    if (testsWithVp.length === 1 && scenariosWithVp.length === 1) return testsWithVp[0];
   }
 
   return null;

package/src/exporters/step-formatter.ts

@@ -1,25 +1,10 @@
 /**
- * Convert raw Gherkin step text OR generated .spec.ts comment lines into
- * concise, numbered natural language for the CSV Steps/Expected columns.
+ * Convert raw Gherkin step text into concise natural language for the
+ * CSV Steps/Expected columns.
  *
  * Deterministic — no AI calls.
  */
 
-/**
- * Format a list of raw step lines for the Steps / Expected Results columns.
- *
- * - 0 lines → empty string
- * - 1 line  → the line verbatim (no "1. " prefix — avoids Google Sheets clutter)
- * - ≥ 2     → each line on its own row, "1. ", "2. ", … prefixes, newline-joined
- *             so spreadsheet cells auto-wrap one step per visual line.
- */
-export function formatNumberedSteps(lines: string[]): string {
-  const cleaned = lines.map(cleanStepLine).filter((l) => l.length > 0);
-  if (cleaned.length === 0) return '';
-  if (cleaned.length === 1) return cleaned[0];
-  return cleaned.map((line, idx) => `${idx + 1}. ${line}`).join('\n');
-}
-
 /**
  * Strip the leading actor (`User `) from a raw Gherkin step and capitalise
  * the first letter. Brackets `[ref]`, `{{var}}` placeholders and element
@@ -42,64 +27,80 @@ export function keepActor(raw: string): string {
 }
 
 /**
- * Number a list of raw feature steps. Mirrors `formatNumberedSteps` but
- * preserves the original Gherkin punctuation (no bracket-to-quote conversion).
- * The mapper picks between `stripActor` (When/Then) and `keepActor`
- * (Given) so the actor word matches the step's grammatical role.
- * Use this for feature-direct rendering (dashboard + delivery).
- */
-export function formatFeatureSteps(lines: string[], mapper: (s: string) => string = stripActor): string {
-  const cleaned = lines.map(mapper).filter((l) => l.length > 0);
-  if (cleaned.length === 0) return '';
-  if (cleaned.length === 1) return cleaned[0];
-  return cleaned.map((line, idx) => `${idx + 1}. ${line}`).join('\n');
-}
-
-/**
- * Clean a raw step line (either Gherkin text or .spec.ts comment).
+ * Group formatted Expected-results lines by their anchor step.
  *
- * Handles patterns like:
- *   "User click [login] button"              → "Click 'login' button"
- *   "User fill [Email] field with {{email}}" → "Fill 'Email' field with {{email}}"
- *   "Click Signature 2025 Creator"           → "Click 'Signature 2025 Creator'"
- *   "Assert title error has text err_xxx"    → "Title error has text err_xxx"
- *   "Open awards page"                       → "Open awards page"
+ * Single source of truth for the anchor rendering (used by csv-exporter AND
+ * json-exporter so the delivery sheet and the dashboard cannot drift). Final
+ * format per user review 2026-08-06:
+ *
+ *   - When assertions verify DIFFERENT moments (more than one distinct
+ *     anchor, or the single anchor is not the final action), the cell is
+ *     rendered as groups — a "— after step N" header line (anchor 0 →
+ *     "— before step 1") followed by that group's assertions. Within a
+ *     group, lines are numbered 1..k only when the group has more than one
+ *     assertion; a lone assertion stays bare.
+ *   - When ALL assertions verify the final action (the common shape — every
+ *     Then after the last When), no headers appear and the caller renders
+ *     the plain 1..M checklist exactly as before the anchor feature.
+ *   - Pure-assertion scenarios (actionCount 0) and manual-comment entries
+ *     (no anchor) never produce headers; unanchored entries trail as their
+ *     own headerless group.
+ *
+ * `grouped` tells the caller headers were emitted, so it can force-number
+ * the Steps cell even when it has a single line (headers reference step
+ * numbers QA must be able to see) and must join the lines verbatim instead
+ * of applying checklist numbering.
+ *
+ * Anchors are computed against the merger's action list; formatted gherkin
+ * lines are never empty (keepActor/stripActor on non-empty text), so the
+ * rendered numbering cannot drift from the anchor indices.
  */
-export function cleanStepLine(raw: string): string {
-  let s = raw.trim();
-
-  // Strip leading "User " actor
-  s = s.replace(/^User\s+/i, '');
-
-  // Strip Gherkin-style element decoration "[Ref] type" → "'Ref' type"
-  // e.g., "click [Login] button" → "click 'Login' button"
-  s = s.replace(/\[([^\]]+)\]/g, "'$1'");
-
-  // Collapse multiple spaces
-  s = s.replace(/\s+/g, ' ');
-
-  // For .spec.ts comments that start with "Assert ..." keep as-is (they read naturally)
-  // For action comments like "Click X", "Fill X with Y" keep as-is.
-
-  // Capitalize first letter
-  if (s.length > 0) s = s.charAt(0).toUpperCase() + s.slice(1);
+export function groupExpectedByAnchor(
+  entries: Array<{ text: string; anchorStep?: number }>,
+  actionCount: number
+): { lines: string[]; grouped: boolean } {
+  const anchors = entries
+    .filter((e) => e.anchorStep !== undefined)
+    .map((e) => e.anchorStep as number);
+  const distinct = new Set(anchors);
+  const grouped =
+    distinct.size > 1 || (distinct.size === 1 && anchors[0] !== actionCount);
+  if (!grouped) return { lines: entries.map((e) => e.text), grouped };
 
-  return s;
+  const lines: string[] = [];
+  let i = 0;
+  while (i < entries.length) {
+    const anchor = entries[i].anchorStep;
+    const group: string[] = [];
+    while (i < entries.length && entries[i].anchorStep === anchor) {
+      group.push(entries[i].text);
+      i++;
+    }
+    if (anchor !== undefined) {
+      lines.push(anchor === 0 ? '— before step 1' : `— after step ${anchor}`);
+    }
+    if (group.length === 1) lines.push(group[0]);
+    else group.forEach((t, k) => lines.push(`${k + 1}. ${t}`));
+  }
+  return { lines, grouped };
 }
 
 /**
- * Pre-condition — login/auth context only.
+ * Pre-condition — login/auth context + feature Background steps.
  *
  *   `@auth:user`   → `Logged in as user`
  *   `@no-auth`     → `Not authenticated`
- *   (no auth tag)  → empty string
+ *   (no auth tag)  → no auth line
  *
- * Background and Given steps are no longer echoed here — they're rendered as
- * the first entries in the Steps list so the chain of actions reads as one
- * uninterrupted sequence.
+ * `backgroundLines` (formatted feature Background steps) follow the auth
+ * line, one per line. Background belongs here rather than in Steps: inlining
+ * it shifted the Steps numbering against the .feature scenario, forcing QA
+ * to re-map step numbers between Gherkin and the exported sheet.
  */
-export function formatPrecondition(authRole: string | null, _givenLines: string[] = []): string {
-  if (authRole === 'no-auth') return 'Not authenticated';
-  if (authRole)               return `Logged in as ${authRole}`;
-  return '';
+export function formatPrecondition(authRole: string | null, backgroundLines: string[] = []): string {
+  const lines: string[] = [];
+  if (authRole === 'no-auth') lines.push('Not authenticated');
+  else if (authRole)          lines.push(`Logged in as ${authRole}`);
+  lines.push(...backgroundLines.filter((l) => l.length > 0));
+  return lines.join('\n');
 }

package/src/exporters/types.ts

@@ -59,11 +59,8 @@ export interface FeatureMetadata {
   featureName: string;                    // e.g., "Create Kudo Modal"
   featurePath?: string;                   // e.g., "/kudos"
   featureTags: string[];                  // Feature-level tags
-  /** Background block classified by bucket. Shared across all runnable
-   *  scenarios — the merger is responsible for prepending these.  */
-  backgroundGivenSteps: string[];
-  backgroundWhenSteps:  string[];
-  backgroundThenSteps:  string[];
+  /** Background block in chronological order. Shared across all runnable
+   *  scenarios — the merger surfaces it as `resolvedBackgroundSteps`.  */
   backgroundOrderedSteps: OrderedStep[];
   scenarios: ScenarioMetadata[];
 }
@@ -71,6 +68,13 @@ export interface FeatureMetadata {
 export interface OrderedStep {
   text: string;
   bucket: 'given' | 'when' | 'then';
+  /**
+   * For then-bucket entries in `MergedScenario.resolvedExpected`: 1-based index
+   * of the last action line (in the rendered Steps column) this assertion
+   * verifies; 0 when the assertion precedes any action. Set by
+   * mergeFeatureAndSpec — absent on action steps and manual-comment entries.
+   */
+  anchorStep?: number;
 }
 
 export interface ScenarioMetadata {
@@ -79,9 +83,6 @@ export interface ScenarioMetadata {
   stepsName?: string;                     // @steps:<name>
   extendsName?: string;                   // @extend:<name>
   referencedVars: string[];               // Variables {{var}} used in this scenario
-  rawGivenSteps: string[];                // Raw Given/And-after-Given step text
-  rawWhenSteps: string[];                 // Raw When/And-after-When step text
-  rawThenSteps: string[];                 // Raw Then/And-after-Then step text
   /**
    * Steps in original chronological order with each step labelled by its
    * effective bucket (And/But inherits from the prior explicit keyword).

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -67,7 +67,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/appium/appium-adapter.ts

@@ -31,7 +31,7 @@ export class AppiumAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean; needsDb?: boolean; needsApi?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/appium/templates/steps/actions/keyboard-global-action.hbs

@@ -1,2 +1,4 @@
 {{!-- Global key event (no target). On Android, Escape maps to the system Back button. --}}
-{{#if (eq key 'Escape')}}await driver.back();{{else}}await driver.keys('{{key}}');{{/if}}
+{{#if repeat}}for (let i = 0; i < {{repeat}}; i++) {
+  {{#if (eq key 'Escape')}}await driver.back();{{else}}await driver.keys('{{key}}');{{/if}}
+}{{else}}{{#if (eq key 'Escape')}}await driver.back();{{else}}await driver.keys('{{key}}');{{/if}}{{/if}}

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean; needsMock?: boolean }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -9,6 +9,9 @@ import { db } from '{{basePath}}/db';
 {{#if needsApi}}
 import { api } from '{{basePath}}/api';
 {{/if}}
+{{#if needsMock}}
+import { mock } from '{{basePath}}/mock';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/keyboard-global-action.hbs

@@ -1 +1,3 @@
-await page.keyboard.press('{{key}}');
+{{#if repeat}}for (let i = 0; i < {{repeat}}; i++) {
+  await page.keyboard.press('{{key}}');
+}{{else}}await page.keyboard.press('{{key}}');{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/page-assertion.hbs

@@ -1 +1 @@
-await expect(page).toHaveURL(/{{pathRegex}}/);
+{{> url-assertion}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/storage-key-assertion.hbs

@@ -0,0 +1,4 @@
+{
+  const ok = await page.evaluate(({ k, arg }) => {{{checkExpr}}}, { k: {{{keyExpr}}}, arg: {{{argExpr}}} });
+  expect(ok, {{{messageExpr}}}).toBe(true);
+}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/tab-order-assertion.hbs

@@ -0,0 +1,30 @@
+{
+  const __stops_{{stepCounter}} = [
+{{#each cells}}
+    { label: '{{escapeQuotes label}}', loc: {{> locator}} },
+{{/each}}
+  ];
+  const __focusReport_{{stepCounter}} = () => page.evaluate(() => {
+    let el = document.activeElement;
+    while (el && el.shadowRoot && el.shadowRoot.activeElement) el = el.shadowRoot.activeElement;
+    if (!el || el === document.body) return 'document.body (focus left the page content)';
+    const role = el.getAttribute('role') ? `[role=${el.getAttribute('role')}]` : '';
+    const name = el.getAttribute('aria-label') || el.getAttribute('name') || el.id || '';
+    return `${el.tagName.toLowerCase()}${role}${name ? ` (${name})` : ''}`;
+  });
+  const __firstLine_{{stepCounter}} = (e: unknown) => (e instanceof Error ? ` (${e.message.split('\n')[0]})` : '');
+  await __stops_{{stepCounter}}[0].loc.focus();
+  try {
+    await expect(__stops_{{stepCounter}}[0].loc, `tab order origin: expected [${__stops_{{stepCounter}}[0].label}] to hold focus`).toBeFocused({ timeout: 2000 });
+  } catch (err) {
+    throw new Error(`Tab order origin not focused: [${__stops_{{stepCounter}}[0].label}] did not take focus (is it focusable?), actual focus: ${await __focusReport_{{stepCounter}}()}${__firstLine_{{stepCounter}}(err)}`);
+  }
+  for (let i = 1; i < __stops_{{stepCounter}}.length; i++) {
+    await page.keyboard.press('Tab');
+    try {
+      await expect(__stops_{{stepCounter}}[i].loc, `tab order position ${i + 1}: expected [${__stops_{{stepCounter}}[i].label}]`).toBeFocused({ timeout: 2000 });
+    } catch (err) {
+      throw new Error(`Tab order mismatch at position ${i + 1}: expected [${__stops_{{stepCounter}}[i].label}], actual focus: ${await __focusReport_{{stepCounter}}()}${__firstLine_{{stepCounter}}(err)}`);
+    }
+  }
+}

package/src/generators/test-generator/adapters/playwright/templates/steps/navigation/route-assertion.hbs

@@ -1,4 +1 @@
-await expect(page).toHaveURL(/{{escapeRegex path}}/);
-{{#if query}}
-expect(page.url()).toContain('{{escapeQuotes query}}');
-{{/if}}
+{{> url-assertion}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/dialog-root.hbs

@@ -1 +1 @@
-{{#if dialogRoleName}}page.getByRole('dialog', { name: '{{escapeQuotes dialogRoleName}}' }){{else if dialogFilterText}}page.getByRole('dialog').filter({ hasText: '{{escapeQuotes dialogFilterText}}' }){{else}}page.getByRole('dialog'){{/if}}
+{{#if dialogRootExpr}}{{{dialogRootExpr}}}{{#if dialogFilterText}}.filter({ hasText: '{{escapeQuotes dialogFilterText}}' }){{/if}}{{else if dialogRoleName}}page.getByRole('dialog', { name: '{{escapeQuotes dialogRoleName}}' }){{else if dialogFilterText}}page.getByRole('dialog').filter({ hasText: '{{escapeQuotes dialogFilterText}}' }){{else}}page.getByRole('dialog'){{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/partials/url-assertion.hbs

@@ -0,0 +1,10 @@
+{{!-- The ONE shape for every Then-side URL assertion (page-assertion + route-assertion).
+      Both used to carry their own copy and drifted apart: `see [X] page` wildcarded a dynamic
+      `:id` segment but silently dropped `with {{v}}`, while `is on [X] page` asserted the query
+      but escaped `:id` literally into a regex that can never match. One partial, one behaviour.
+      `pathRegex` is pre-escaped by pathToRegexSource (`:id` → `[^/]+`); the query is asserted
+      separately because its value is runtime data full of regex-special characters. --}}
+await expect(page).toHaveURL(/{{pathRegex}}/);
+{{#if query}}
+expect(page.url()).toContain('{{escapeQuotes query}}');
+{{/if}}

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

@@ -311,11 +311,12 @@ 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 });
+    const imports = this.adapter.renderImports({ runtimeData: this.options.runtimeData, basePath, needsCleanupImport, needsDb, needsApi, needsMock });
 
     // Generate test code (async now to support AI mapping)
     const testCode = await this.generateTestCode(feature);
@@ -324,7 +325,7 @@ export class CodeGenerator {
     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 +383,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 +551,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 +785,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 +937,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);