@sun-asterisk/sungen 3.2.18 → 3.2.20

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/test-data-resolver.ts

@@ -141,10 +141,43 @@ function truncate(s: string, max: number): string {
  * test-data map (or resolving to empty) is left as the literal `{{var}}` — never blanked.
  */
 export function substituteTestDataVars(text: string, testData: Record<string, string>): string {
-  return text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (m, key: string) => {
+  const out = text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (m, key: string) => {
     const v = testData[key];
     return v === undefined || v === null || v === '' ? m : String(v);
   });
+  // A substituted value may itself carry a dynamic token ("Award-{{$timestamp}}").
+  // String.replace never re-scans its own replacement, so name them afterwards.
+  return renderDynamicTokens(out);
+}
+
+/**
+ * Give the documented dynamic vars (`{{$timestamp}}`, `{{$uuid}}`,
+ * `{{$random:min:max}}`, `{{$date}}`, `{{$datetime}}`) a form a tester can act on.
+ *
+ * These are resolved by TestDataLoader at execution time, never from
+ * test-data.yaml — so at export time they have no static value, exactly like a
+ * value the run captures (`remember … as {{v}}` → `the captured v`). Left raw,
+ * the token ships into the deliverable and the matrix's Gate D rejects the
+ * whole export. Named, the tester reads what to type: any value of that shape,
+ * uniqueness being the whole point.
+ *
+ * An UNKNOWN `{{$foo}}` stays literal on purpose — the runtime resolver also
+ * leaves it raw, so it is an authoring typo and must keep failing Gate D.
+ */
+export function renderDynamicTokens(text: string): string {
+  return text.replace(/\{\{\s*\$(\w+)(?::([^}]*))?\s*\}\}/g, (m, name: string, args?: string) => {
+    switch (name) {
+      case 'timestamp': return '<unique timestamp>';
+      case 'uuid': return '<unique id>';
+      case 'random': {
+        const [min, max] = (args || '1:9999').split(':');
+        return `<random ${min}-${max}>`;
+      }
+      case 'date': return "<today's date>";
+      case 'datetime': return '<current date-time>';
+      default: return m;
+    }
+  });
 }
 
 /**

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; urlAssertImports?: string }): 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; urlAssertImports?: string }): 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; urlAssertImports?: string }): string {
     return this.templateEngine.renderImports(options);
   }
 

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

@@ -9,6 +9,12 @@ import { db } from '{{basePath}}/db';
 {{#if needsApi}}
 import { api } from '{{basePath}}/api';
 {{/if}}
+{{#if needsMock}}
+import { mock } from '{{basePath}}/mock';
+{{/if}}
+{{#if urlAssertImports}}
+import { {{urlAssertImports}} } from '{{basePath}}/url-assert';
+{{/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/navigation.hbs

@@ -1,2 +1,6 @@
+{{#if query}}
+await page.goto(joinPath('{{#if baseURL}}{{baseURL}}{{/if}}', '{{path}}', '{{escapeQuotes query}}'), { waitUntil: 'load' });
+{{else}}
 await page.goto('{{#if baseURL}}{{baseURL}}{{/if}}{{path}}', { waitUntil: 'load' });
+{{/if}}
 await page.waitForLoadState('domcontentloaded');

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,15 @@
+{{!-- 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.
+
+      The predicate itself lives in specs/url-assert.ts (template: specs-url-assert.ts) — read it
+      for the semantics. It is a runtime helper rather than an inline lambda so that correcting
+      what "the URL matches" MEANS is a runtime patch, not a regenerate-the-world breaking change
+      for every suite in the field.
+
+      Only `pathRegex` is the generator's business: it alone knows the page selector's value and
+      its `:id` wildcards, and it is pre-escaped by pathToRegexSource. `\/?$` normalises a
+      trailing slash so `/vi/search/` does not read as a different page. The declared value stays
+      a plain string literal so the runtime-data marker pass can rewrite it to testData.get(…). --}}
+await expect(page).toHaveURL(urlMatches({ pathname: /^{{pathRegex}}\/?$/{{#if query}}, dataRef: '{{escapeQuotes dataRef}}', declared: '{{escapeQuotes query}}'{{/if}} }));