@sun-asterisk/sungen 3.2.24 → 3.2.26

package/src/exporters/selector-key-resolver.ts

@@ -18,6 +18,10 @@
  *   • `value` for `type: 'role'` (role name like 'button', not display)
  *   • Entries with no `name` and no usable `value`
  *   • Composite templates with 2+ vars (ambiguous which to use)
+ *   • Locators whose single var is SCOPE text — inside `:has(...)`/`:not(...)`,
+ *     in a non-final segment, or in an XPath nested predicate / pre-step
+ *     position (see locatorVarIsScopeText) — substituting those renames the
+ *     ref to text of a DIFFERENT element (a column header naming a table)
  */
 
 import * as fs from 'fs';
@@ -90,13 +94,89 @@ function resolveField(value: string, isLocator: boolean): SelectorResolution | n
   }
   if (vars.length === 1) {
     // Sole `{{var}}` or composite like `has-text("{{var}}")`. Both resolve
-    // to the same var's locale-specific display text.
+    // to the same var's locale-specific display text — but ONLY when the var
+    // is the target element's OWN text. A var inside a `:has(...)` argument
+    // or in an ancestor segment names a DIFFERENT element (a column header
+    // scoping a table), and substituting it renames the ref to unrelated text.
+    if (isLocator && locatorVarIsScopeText(value)) return null;
     return { varName: vars[0] };
   }
   // 2+ vars in one template — ambiguous which to use; skip rather than guess.
   return null;
 }
 
+/**
+ * True when a locator's single `{{var}}` (FIRST occurrence — repeats of the
+ * same var judge by that one, erring toward fidelity) belongs to a SCOPE
+ * rather than the target element's own display text.
+ *
+ * CSS / Playwright engines:
+ *   - inside a `:has(...)` or `:not(...)` argument at any depth — that text
+ *     describes ANOTHER element (or the text this one must NOT contain);
+ *     `:has-text(...)` / `:text(...)` ARE the element's own text and pass;
+ *   - in a non-final segment — a combinator (space, `>`, `>>`, `+`, `~`) at
+ *     top level (outside parens, brackets and quotes) follows the var with a
+ *     real selector after it. A bare trailing match flag (`"{{x}}" i`) or an
+ *     attribute-internal space (`[name="{{x}}" i]`) is NOT a combinator.
+ *
+ * XPath (`xpath=` / `//…`):
+ *   - the var sits in a NESTED predicate (bracket depth ≥ 2, e.g.
+ *     `//table[.//th[text()="{{col}}"]]` — the th labels the table); or
+ *   - a location step (`/`) follows the var at top level
+ *     (`//th[text()="{{col}}"]/ancestor::table`).
+ *
+ * One left-to-right scan tracking quote state (with backslash-run counting so
+ * a literal trailing `\\` can't wedge the scanner in "quoted"), paren frames,
+ * and bracket depth.
+ */
+function locatorVarIsScopeText(locator: string): boolean {
+  const m = varPattern().exec(locator);
+  if (!m) return false;
+  const varIndex = m.index;
+  const isXpath = /^\s*(?:xpath=|\(*\/\/)/i.test(locator);
+  let quote: string | null = null;
+  const scopeFrames: boolean[] = []; // one entry per open paren: is it a :has(/:not( frame?
+  let bracketDepth = 0;
+  let passedVar = false;
+  const escaped = (i: number): boolean => {
+    let n = 0;
+    for (let j = i - 1; j >= 0 && locator[j] === '\\'; j--) n++;
+    return n % 2 === 1;
+  };
+  for (let i = 0; i < locator.length; i++) {
+    if (i === varIndex) {
+      passedVar = true;
+      if (!isXpath && scopeFrames.some(Boolean)) return true;
+      if (isXpath && bracketDepth >= 2) return true;
+    }
+    const c = locator[i];
+    if (quote) {
+      if (c === quote && !escaped(i)) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") { quote = c; continue; }
+    if (c === '(') {
+      const pseudo = locator.slice(Math.max(0, i - 4), i).toLowerCase();
+      scopeFrames.push(!isXpath && (pseudo === ':has' || pseudo === ':not'));
+      continue;
+    }
+    if (c === ')') { scopeFrames.pop(); continue; }
+    if (c === '[') { bracketDepth++; continue; }
+    if (c === ']') { bracketDepth = Math.max(0, bracketDepth - 1); continue; }
+    if (!passedVar || scopeFrames.length > 0 || bracketDepth > 0) continue;
+    if (isXpath) {
+      if (c === '/') return true; // a location step after the var → the target comes later
+      continue;
+    }
+    if (c === ' ' || c === '>' || c === '+' || c === '~') {
+      const rest = locator.slice(i).replace(/^[\s>+~]+/, '');
+      // Bare Playwright match flags after a quoted value are not a new segment.
+      if (rest.length > 0 && !/^[is](?:\s|$)/.test(rest)) return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Build the SelectorKey → resolution map from a selectors YAML file.
  * Returns an empty map when the file is missing or malformed.

package/src/exporters/types.ts

@@ -125,6 +125,13 @@ export interface PlaywrightResult {
   duration?: number;
   startTime?: string;
   error?: string;
+  /**
+   * Every distinct failure message of the final attempt (ANSI/stack stripped).
+   * Playwright's top-level `error` is only the FIRST error — when a timeout
+   * wraps an assertion, the assertion detail (Locator/Expected/Received) lives
+   * in `results[].errors[1+]` and would otherwise never reach the deliverable.
+   */
+  errorMessages?: string[];
   tracePath?: string;
   projectName?: string;
 }
@@ -179,7 +186,7 @@ export interface ApiCatalogEntry {
   /** Request-body wire format — decides the Content-Type the request sends.
    *  Absent/`json` → application/json, `form` → application/x-www-form-urlencoded,
    *  `multipart` → multipart/form-data. */
-  encoding?: 'json' | 'form' | 'multipart';
+  encoding?: 'json' | 'form' | 'multipart' | 'xml';
   /** Multipart file parts (multipart/form-data). A field value may be a single file spec, its string
    *  shorthand, or an array of specs (multiple files under one field name). Typed loosely — guard before use. */
   files?: Record<string, unknown>;

package/src/exporters/xlsx-report-builder.ts

@@ -640,10 +640,11 @@ export function buildApiDetailRows(
     const uniqueAuth = [...new Set(authTags.map((t) => t.slice('@auth:'.length)))];
     const authDatasource = [datasource, ...uniqueAuth].filter(Boolean).join('; ');
 
-    // Request shape: compose from body + params + encoding.
-    const bodyStr = entry.body
-      ? `body: ${typeof entry.body === 'string' ? entry.body : JSON.stringify(entry.body)}`
-      : '';
+    // Request shape: compose from body + params + encoding. A raw XML template can
+    // run long — cap the cell so one entry can't blow up the sheet's row height.
+    const rawBody = entry.body ? (typeof entry.body === 'string' ? entry.body : JSON.stringify(entry.body)) : '';
+    const cappedBody = rawBody.length > 500 ? `${rawBody.slice(0, 499)}…` : rawBody;
+    const bodyStr = cappedBody ? `body: ${cappedBody}` : '';
     const paramsArr = Array.isArray(entry.params) ? entry.params as string[] : [];
     const paramsStr = paramsArr.length > 0 ? `params: [${paramsArr.join(', ')}]` : '';
     const requestShape = [bodyStr, paramsStr].filter(Boolean).join('; ') || '—';

package/src/generators/gherkin-parser/index.ts

@@ -4,6 +4,51 @@ import * as Messages from '@cucumber/messages';
 import fs from 'fs';
 import path from 'path';
 import { SelectorResolver } from '../test-generator/utils/selector-resolver';
+import { maskRefsForMatching } from '../test-generator/utils/mask-refs-for-matching';
+import type { StateClause } from '../test-generator/patterns/types';
+
+/**
+ * Canonical state clauses, longest-first. Order is load-bearing twice over: `sorted ascending` must
+ * be tried before any bare word so it is not split, and `unchecked` before `checked` so the
+ * substring never misclassifies — the same hazard, and the same fix, as `qualifiedState()` in
+ * driver-ui's assertion-patterns.
+ */
+const STATE_CLAUSES: ReadonlyArray<StateClause> = [
+  'sorted ascending', 'sorted descending',
+  'unchecked', 'checked',
+  'hidden', 'visible', 'disabled', 'enabled', 'focused', 'empty', 'loading', 'selected',
+];
+
+/**
+ * Lift a trailing state clause out of a step sentence so the pattern layer can tell whether the
+ * pattern that won actually asserts it (SG-E021). Before this the clause lived ONLY inside
+ * `step.text`, every pattern re-regexed it privately, and a clause swallowed by a higher-priority
+ * pattern was undetectable by construction.
+ *
+ * Narrow on purpose — everything this rejects is a step that must keep compiling exactly as it does
+ * today:
+ *   - requires the literal `is` — `wait for [X] to be hidden` is a wait, not a state assertion;
+ *   - requires TRAILING position — `… is hidden after the modal closes` is prose, not a clause;
+ *   - rejects `is not <state>` — `in local storage is not empty` is a real storage grammar (D5);
+ *   - masks `[Ref]` and `{{data}}` CONTENT first, so `[Sorted Ascending]` (a button) and
+ *     `{{is_empty}}` (a variable) are not read as states.
+ */
+function extractStateClause(text: string): StateClause | undefined {
+  // Collapse runs of whitespace and drop a trailing period, so `… is  hidden .` reads the same as
+  // `… is hidden`. Compared as a plain string tail rather than a built regex: the clause list holds
+  // a two-word member (`sorted ascending`), and interpolating it into a RegExp means escaping the
+  // separator, which is exactly the kind of quiet breakage `\b`-in-a-template-literal already is.
+  const tail = maskRefsForMatching(text)
+    .replace(/\s+/g, ' ')
+    .replace(/ ?\.$/, '')
+    .toLowerCase();
+  // ` is ` must sit IMMEDIATELY before the clause. That single space is what excludes `is not empty`
+  // — the storage grammar — without a negative lookbehind.
+  for (const state of STATE_CLAUSES) {
+    if (tail.endsWith(` is ${state}`)) return state;
+  }
+  return undefined;
+}
 
 export interface DataTableRow {
   cells: string[]; // Cell values in order
@@ -28,6 +73,7 @@ export interface ParsedStep {
   parentRef?: string; // Parent scope reference: "in [Parent Name] parentType" → parentRef = "Parent Name"
   parentType?: string; // Parent scope type: table, list, section, dialog, form
   dataTable?: ParsedDataTable; // Inline data table (Cucumber DataTable syntax)
+  state?: StateClause; // Trailing canonical state clause, e.g. "hidden" from "… is hidden" (drives SG-E021)
 }
 
 export interface ParsedScenario {
@@ -204,7 +250,14 @@ export class GherkinParser {
     const selectorRef = selectorMatch ? selectorMatch[1] : undefined;
 
     // Extract data reference: {{login.email.valid}} or <valid_user.email> (legacy)
-    const dataMatch = text.match(/\{\{([a-z0-9\-\.\_]+)\}\}|<([^>]+)>/i);
+    // A `{{var}}` inside a [Reference] is NEVER the step's data ref: a bracket carries a
+    // selectors.yaml key or a browser-storage key, both matched verbatim. Blank the brackets
+    // out first — the match is un-anchored and takes the FIRST hit, so a step with braces on
+    // both sides (`see [{{code}}_TOKEN] in session storage has length {{n}}`, or
+    // `remember [X] text as {{v}}` written with a bracket var) would otherwise bind the
+    // bracket's variable and silently lose the real ref.
+    const textOutsideRefs = text.replace(/\[[^\]]*\]/g, '');
+    const dataMatch = textOutsideRefs.match(/\{\{([a-z0-9\-\.\_]+)\}\}|<([^>]+)>/i);
     const dataRef = dataMatch ? (dataMatch[1] || dataMatch[2]) : undefined;
 
     // Extract quoted value: "Hello, how are you?"
@@ -269,6 +322,7 @@ export class GherkinParser {
       parentRef,
       parentType,
       dataTable,
+      state: extractStateClause(step.text),
     };
   }
 

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

@@ -31,6 +31,13 @@ export interface TestFileData {
   singleAuthRole?: string;  // Auth role when all scenarios share the same role
   appPackage?: string;      // Mobile (appium): Android package from the feature `Path:` → drives the per-scenario relaunch reset (beforeEach terminate+activate)
   iosBundleId?: string;     // Mobile (appium): iOS bundle id from a dual-id `Path: <pkg>/<activity> | <bundleId>`
+  resetTier?: string;       // Mobile (appium): `@reset:none|soft|data|full` — how much state each scenario starts from. Default 'soft' = the terminate+activate relaunch this adapter always did, so an untagged feature is unchanged. See generators/test-generator/reset-tier.ts
+  // Mobile (appium): per-scenario `@reset:` overrides, keyed by the scenario's BASE name (not the
+  // rendered it() title — a @cases scenario builds its title at runtime from the row label). An
+  // ordered array rather than a map so duplicate names stay visible instead of silently collapsing.
+  // `cases` = the scenario's it() title is built at RUNTIME from a row label, so it is the only shape
+  // whose title may legitimately carry a ` — <label>` suffix the lookup has to strip.
+  scenarioResetTiers?: Array<{ name: string; tier: string; cases: boolean }>;
 }
 
 export interface ScenarioData {
@@ -40,6 +47,7 @@ export interface ScenarioData {
   isParallel?: boolean; // @parallel: use fresh page from fixture
   tags?: string; // Pass-through tags for Playwright { tag: [...] }, e.g. "'@smoke', '@high'"
   casesDataset?: string; // @cases:<dataset> — emit one test() per row of the runtime dataset
+  resetTier?: string; // Mobile (appium): scenario-level `@reset:` override; raises (never lowers) the feature tier for this scenario only
 }
 
 export interface StepTemplateData {
@@ -59,6 +67,20 @@ export interface LocatorExpression {
  * TestGeneratorAdapter
  * Framework-specific code generation using template engine
  */
+
+/** Options for the imports block — one shape shared by every adapter and the template engine. */
+export interface RenderImportsOptions {
+  runtimeData?: boolean;
+  basePath?: string;
+  isParallel?: boolean;
+  needsCleanupImport?: boolean;
+  needsDb?: boolean;
+  needsApi?: boolean;
+  needsMock?: boolean;
+  urlAssertImports?: string;
+  regexEscapeImport?: boolean;
+}
+
 export interface TestGeneratorAdapter {
   readonly frameworkName: string;
   readonly fileExtension: string;
@@ -67,7 +89,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; needsMock?: boolean; urlAssertImports?: string }): string;
+  renderImports(options?: RenderImportsOptions): 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

@@ -1,5 +1,5 @@
 import path from 'path';
-import { TestGeneratorAdapter, TestFileData, ScenarioData } from '../adapter-interface';
+import { TestGeneratorAdapter, TestFileData, ScenarioData, RenderImportsOptions } from '../adapter-interface';
 import { TemplateEngine } from '../../template-engine';
 
 /**
@@ -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; needsMock?: boolean; urlAssertImports?: string }): string {
+  renderImports(options?: RenderImportsOptions): string {
     return this.templateEngine.renderImports(options);
   }
 

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

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

package/src/generators/test-generator/adapters/appium/templates/steps/actions/date-picker-unsupported.hbs

@@ -0,0 +1,4 @@
+{{!-- A date-picker on native mobile is a DIALOG (spinner/calendar), not a text field: the generic
+      fill would click the trigger and setValue into it, selecting nothing while reporting success.
+      Same treatment as the upload step — fail loud, and name both ways forward. --}}
+throw new Error("[sungen] {{escapeQuotes reason}}");

package/src/generators/test-generator/adapters/appium/templates/steps/actions/lifecycle-missing-app-id.hbs

@@ -0,0 +1,5 @@
+{{!-- A lifecycle step (restart / reinstall) in a feature with no `Path:` app id. The lifecycle
+      templates resolve the app through a helper the test-file emits only when that id is present,
+      so without it the spec used to compile clean and die at runtime with a ReferenceError —
+      taking the whole spec down, not the step. Fail at the step, naming the missing line. --}}
+throw new Error("[sungen] {{escapeQuotes reason}}");

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/matches-format-assertion.hbs

@@ -0,0 +1,15 @@
+{{!-- Format assertion (mobile): same multi-source read as have-text/contain-text
+      (@text / @content-desc on Android, label/value on iOS), matched against the shape the spec
+      states. The error quotes the FORMAT and the actual string — the compiled regex is noise to
+      the person who wrote the requirement. --}}
+{
+  const __el = await {{> locator}};
+  await __el.waitForDisplayed();
+  const __sources = driver.isIOS
+    ? [await __el.getAttribute('label'), await __el.getAttribute('value')]
+    : [await __el.getText(), await __el.getAttribute('content-desc')];
+  const __actual = String(__sources.find(s => s && String(s).trim() !== '') ?? '').trim();
+  if (!{{{formatRegex}}}.test(__actual)) {
+    throw new Error(`[sungen] Expected [{{escapeQuotes selectorRef}}] to match the format "{{escapeQuotes format}}" but it reads "${__actual}"`);
+  }
+}

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/visible-filtered-assertion.hbs

@@ -1,9 +1,12 @@
 {{!-- Filtered visible (mobile): $$ over the base selector, per-OS text read matched against
       dataValue — no CSS filter() combinator exists on Appium, so the match is hand-rolled
       (covers both the locator- and role-strategy call sites, since both resolve through
-      appium-selector-expr). Assert at least one match is displayed. --}}
+      appium-selector-expr). Assert at least one match is displayed. Substring match by
+      default, matching the web hasText string contract: case-insensitive with collapsed
+      whitespace; `exact` opts into full case-sensitive equality (the anchored-regex twin). --}}
 {
   const __expected = String('{{escapeQuotes dataValue}}').trim();
+  const __norm = (s: string) => s.replace(/\s+/g, ' ').trim().toLowerCase();
   const __items = await $$({{> appium-selector-expr}});
   let __found = false;
   for (const __el of __items) {
@@ -11,7 +14,7 @@
       ? [await __el.getAttribute('label'), await __el.getAttribute('value')]
       : [await __el.getText(), await __el.getAttribute('content-desc')];
     const __actual = String(__sources.find(s => s && String(s).trim() !== '') ?? '').trim();
-    if (__actual === __expected && await __el.isDisplayed()) { __found = true; break; }
+    if ({{#if exact}}__actual === __expected{{else}}__norm(__actual).includes(__norm(__expected)){{/if}} && await __el.isDisplayed()) { __found = true; break; }
   }
   if (!__found) throw new Error(`[sungen] Expected a visible match with text "${__expected}"`);
 }

package/src/generators/test-generator/adapters/appium/templates/test-file.hbs

@@ -366,31 +366,117 @@ describe('{{featureName}}', () => {
     }
     return __APP_PKG_DEFAULT__;
   }
-  beforeEach(async () => {
-    const __APP_PKG__ = __resolveAppId();
-    try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
-    // Let the termination fully land before relaunching — activateApp racing a still-dying
-    // process can RESUME the old instance (prior scenario's scroll position and all) instead
-    // of cold-starting, which strands top-of-screen elements above the viewport.
-    await driver.pause(500);
-    await driver.activateApp(__APP_PKG__);
-    // Restore the NATIVE context — a prior scenario that entered a WebView (`switch to [X] frame`)
-    // without switching back would otherwise poison every following native find.
-    try { await driver.switchContext('NATIVE_APP'); } catch { /* single-context session */ }
-    // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
-    // app relaunch above resets in-app state, but device orientation is OS-level and persists.
-    try { await driver.setOrientation('PORTRAIT'); } catch { /* orientation control not supported */ }
-    // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
-    // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
-    // So require rendered content — at least one non-empty content-desc/text — on two consecutive
-    // reads before proceeding. A generous timeout covers slow cold renders on a stressed emulator.
-    // Best-effort: a timeout never fails the scenario, it just falls through to the step's own
-    // auto-wait.
-    // "Settled" = rendered content present on TWO consecutive reads. Deliberately NOT full source
-    // equality: a UI with any looping animation (a rotating promo carousel is enough) never yields
-    // two identical snapshots, so an equality oracle starves and burns the whole timeout on every
-    // scenario. Two content-bearing reads still reject the blank first-frame skeleton (no
-    // content-desc/text at all) that a single read could false-positive on.
+  // ── Reset tier ────────────────────────────────────────────────────────────────────────────────
+  // How much state each scenario starts from (`@reset:` on the Feature; default `soft`):
+  //   none — nothing reset; state carries over BY DESIGN (a cart accumulating across scenarios)
+  //   soft — terminate + activate: in-memory state and the nav stack
+  //   data — soft + wipe the app's data layer (local DB, cache, prefs, keychain)
+  //   full — remove + reinstall: also permissions and install-time state
+  // Unlike web, no cheap "reload the URL" exists here, and a cold start is 5–30s — hence a ladder
+  // rather than one all-or-nothing switch.
+  const __DECLARED_TIER = '{{resetTier}}';
+  const __TIER_ORDER = ['none', 'soft', 'data', 'full'];
+  // SUNGEN_RESET_TIER RAISES the floor for a whole run — CI at `data`, local dev at `soft` — without
+  // regenerating a single spec (same runtime-resolution model as the test-data overlays). It never
+  // LOWERS a declared tier: a feature that asked for `full` needs it. Resolved once, so an
+  // unrecognized value warns once rather than per scenario — a silently ignored typo here would
+  // reintroduce exactly the false-confidence this tier system exists to remove.
+  const __RUN_TIER: string = (() => {
+    // Defensive only — the compiler validates the tag — but fall back to `soft`, NOT to index 0
+    // (`none`). A safety net that silently drops to "reset nothing" points the wrong way.
+    const declaredIdx = __TIER_ORDER.indexOf(__DECLARED_TIER);
+    const declared = declaredIdx < 0 ? __TIER_ORDER.indexOf('soft') : declaredIdx;
+    const raw = (process.env.SUNGEN_RESET_TIER || '').trim().toLowerCase();
+    if (!raw) return __TIER_ORDER[declared];
+    const floor = __TIER_ORDER.indexOf(raw);
+    if (floor < 0) {
+      console.warn(`  ! SUNGEN_RESET_TIER='${raw}' is not a tier (${__TIER_ORDER.join(', ')}) — ignored`);
+      return __TIER_ORDER[declared];
+    }
+    return __TIER_ORDER[Math.max(declared, floor)];
+  })();
+
+  // A scenario that FAILED left unknown state behind — a half-written local DB, an open modal — that a
+  // plain process relaunch does not undo. So the NEXT scenario resets one rung harder than it asked
+  // for: this is the "A fails mid-flow, B fails for A's reasons" case that no amount of relaunching
+  // fixes. One rung, one scenario, never sticky — otherwise a single flake would silently promote the
+  // whole run to `full` and put 30s on every remaining scenario.
+  // `none` is a FIXED POINT by design: it is an explicit state-carryover contract (a cart built up
+  // across scenarios), and escalating would silently break the very thing it was asked for. The chain
+  // is dead once one link fails anyway, so a relaunch would change only how the rest fail.
+  // Mirrors escalateResetTier() in the compiler; a test asserts the two ladders agree.
+  const __ESCALATE: Record<string, string> = { none: 'none', soft: 'data', data: 'full', full: 'full' };
+  // Holds the TITLE of the scenario that failed, not a boolean — because escalation must reach the next
+  // DIFFERENT scenario and must NOT reach a RETRY of the failed one.
+  //
+  // `mochaOpts.retries` re-runs a failed scenario, and the retry is also "the next run". Escalating it
+  // would make attempt 2 reset harder than attempt 1, which breaks the guarantee this config is built
+  // on: race victims recover on attempt 2 while REAL failures fail both attempts. A dirty-state failure
+  // is a real failure — if the retry silently got a wiped data layer it would pass, the reporter takes
+  // the last attempt, and a scenario that only works after a wipe would be delivered as a clean
+  // `Passed` under a feature file still reading its weaker declared tier. That false pass is worse than
+  // the flakiness escalation was added to fix, so the retry keeps attempt 1's tier and fails honestly.
+  //
+  // Comparing titles rather than reading mocha's retry counter keeps this independent of the runner's
+  // API, and it fails in the SAFE direction: if a title is unavailable both sides compare equal, so no
+  // escalation happens and the invariant above still holds. (Two scenarios sharing one title in a file
+  // lose the escalation between them — SG-W024 already reports that shape when tiers are involved.)
+  let __escalateAfter: string | null = null;
+
+  // Registered BEFORE any user @afterEach block so a throwing user hook cannot skip the bookkeeping.
+  afterEach(async function () {
+    __escalateAfter = this.currentTest?.state === 'failed' ? (this.currentTest?.title ?? '') : null;
+  });
+
+{{#if scenarioResetTiers}}
+  // Per-scenario `@reset:` overrides, keyed on the scenario's BASE name. Not on the rendered title:
+  // a @cases scenario builds its title at runtime (`name + ' — ' + row.__label`) and appium appends
+  // pass-through tags as a `[…]` suffix, so no compile-time key could match what mocha reports.
+  // __tierFor therefore strips those two suffixes back off — and MEMBERSHIP-TESTS at every step, so a
+  // name it cannot resolve returns 'none' (inherit the feature tier) instead of guessing a wrong one.
+  // Silently applying the wrong tier is the failure this whole feature exists to remove.
+  const __SCENARIO_TIERS: Record<string, string> = {
+{{#each scenarioResetTiers}}
+    '{{escapeQuotes name}}': '{{tier}}',
+{{/each}}
+  };
+  // Only a @cases scenario builds its it() title at RUNTIME (`name + ' \u2014 ' + row.__label`), so only
+  // these names may shed a trailing ` \u2014 <label>` during lookup. Stripping that from EVERY title let a
+  // scenario merely NAMED `<something> \u2014 <something>` resolve to a different scenario's tier.
+  const __CASES_NAMES = new Set<string>([{{#each scenarioResetTiers}}{{#if cases}}'{{escapeQuotes name}}', {{/if}}{{/each}}]);
+  function __tierFor(title: string): string {
+    if (Object.prototype.hasOwnProperty.call(__SCENARIO_TIERS, title)) return __SCENARIO_TIERS[title];
+    // `\[@` — must be a TAG group, not a trailing selector ref. Without the `@`, a scenario named
+    // `VP-001 tap [Save]` would reduce to `VP-001 tap` and could pick up a DIFFERENT scenario's tier.
+    const noTags = title.replace(/ \[@[^\]]*\]$/, '');
+    if (Object.prototype.hasOwnProperty.call(__SCENARIO_TIERS, noTags)) return __SCENARIO_TIERS[noTags];
+    // Shed row-label segments from the RIGHT, one at a time, accepting only a @cases name. Right-to-left
+    // and iterative so an em dash inside the scenario NAME or inside the row LABEL still resolves; every
+    // step is membership-tested against __CASES_NAMES, so this narrows toward a declared name and never
+    // guesses at one.
+    let base = noTags;
+    for (let i = base.lastIndexOf(' \u2014 '); i >= 0; i = base.lastIndexOf(' \u2014 ')) {
+      base = base.slice(0, i);
+      if (__CASES_NAMES.has(base)) return __SCENARIO_TIERS[base];
+    }
+    // Unresolvable ⟹ inherit the feature tier. Never a guess: a wrong tier applied silently is the
+    // failure this whole lookup exists to avoid.
+    return 'none';
+  }
+{{/if}}
+
+  // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
+  // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
+  // So require rendered content — at least one non-empty content-desc/text — on two consecutive
+  // reads before proceeding. A generous timeout covers slow cold renders on a stressed emulator.
+  // Best-effort: a timeout never fails the scenario, it just falls through to the step's own
+  // auto-wait.
+  // "Settled" = rendered content present on TWO consecutive reads. Deliberately NOT full source
+  // equality: a UI with any looping animation (a rotating promo carousel is enough) never yields
+  // two identical snapshots, so an equality oracle starves and burns the whole timeout on every
+  // scenario. Two content-bearing reads still reject the blank first-frame skeleton (no
+  // content-desc/text at all) that a single read could false-positive on.
+  async function __settleUi(timeout: number): Promise<void> {
     let __prevHadContent = false;
     await driver
       .waitUntil(
@@ -401,9 +487,82 @@ describe('{{featureName}}', () => {
           __prevHadContent = hasContent;
           return settled;
         },
-        { timeout: 30000, interval: 400, timeoutMsg: 'UI did not settle (no rendered content)' },
+        { timeout, interval: 400, timeoutMsg: 'UI did not settle (no rendered content)' },
       )
       .catch(() => { /* best-effort — fall through to per-step auto-wait */ });
+  }
+
+  // Wipe the app's data layer. `mobile: clearApp` is a UiAutomator2 (Android) command — it maps to
+  // `pm clear`, which drops the local DB, cache, SharedPreferences and keychain entries in one call
+  // for ~2–5s. XCUITest has NO equivalent, so iOS degrades to a reinstall: slower, but the only way
+  // to reach the same layers. That needs a build to install from, hence the named throw.
+  async function __clearAppData(pkg: string): Promise<void> {
+    if (driver.isIOS) {
+      await __reinstallApp(pkg);
+      return;
+    }
+    await driver.execute('mobile: clearApp', { appId: pkg });
+  }
+
+  async function __reinstallApp(pkg: string): Promise<void> {
+    const caps = (driver.requestedCapabilities || {}) as Record<string, string>;
+    const appPath = caps['appium:app'] || caps['app'];
+    if (!appPath) {
+      throw new Error(
+        `reset tier needs the app's build file to reinstall — set APP_APK (Android) / IOS_APP (iOS) so the appium:app capability is present, or drop to @reset:soft.`,
+      );
+    }
+    try { await driver.removeApp(pkg); } catch { /* not installed */ }
+    await driver.installApp(appPath);
+  }
+
+  // One reset, at the given tier. `none` still restores the NATIVE context and portrait: both leak at
+  // OS/session level rather than app level, so skipping them alongside the relaunch would make `none`
+  // outright buggy instead of merely stateful. It skips the settle wait, though — nothing relaunched,
+  // so there is no blank first frame to wait through, and burning up to 30s per scenario would defeat
+  // the whole point of asking for `none`.
+  async function __resetApp(tier: string): Promise<void> {
+    const __APP_PKG__ = __resolveAppId();
+    if (tier !== 'none') {
+      if (tier === 'full') {
+        try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
+        await __reinstallApp(__APP_PKG__);
+      } else {
+        try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
+        if (tier === 'data') await __clearAppData(__APP_PKG__);
+      }
+      // Let the termination fully land before relaunching — activateApp racing a still-dying
+      // process can RESUME the old instance (prior scenario's scroll position and all) instead
+      // of cold-starting, which strands top-of-screen elements above the viewport.
+      await driver.pause(500);
+      await driver.activateApp(__APP_PKG__);
+    }
+    // Restore the NATIVE context — a prior scenario that entered a WebView (`switch to [X] frame`)
+    // without switching back would otherwise poison every following native find.
+    try { await driver.switchContext('NATIVE_APP'); } catch { /* single-context session */ }
+    // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
+    // app relaunch above resets in-app state, but device orientation is OS-level and persists.
+    try { await driver.setOrientation('PORTRAIT'); } catch { /* orientation control not supported */ }
+    // A fresh install paints its first frame slower than a plain relaunch — same oracle, more rope.
+    if (tier !== 'none') await __settleUi(tier === 'full' || tier === 'data' ? 45000 : 30000);
+  }
+  beforeEach(async function () {
+{{#if scenarioResetTiers}}
+    // A scenario tier RAISES the feature tier, never lowers it: a @reset:full feature must not be
+    // weakened by one scenario asking for less. Use a separate feature when you genuinely need that.
+    const __scenarioTier = __tierFor(this.currentTest?.title ?? '');
+    const __base = __TIER_ORDER.indexOf(__scenarioTier) > __TIER_ORDER.indexOf(__RUN_TIER) ? __scenarioTier : __RUN_TIER;
+{{else}}
+    const __base = __RUN_TIER;
+{{/if}}
+    // Same title ⟹ this is a retry of the scenario that just failed: keep its declared tier so a real
+    // failure fails both attempts (see __escalateAfter above).
+    const __escalate = __escalateAfter !== null && __escalateAfter !== (this.currentTest?.title ?? '');
+    const __tier = __escalate ? __ESCALATE[__base] : __base;
+    if (__tier !== __base) {
+      console.log(`  \u2191 reset escalated ${__base} \u2192 ${__tier} (previous scenario failed: "${__escalateAfter}")`);
+    }
+    await __resetApp(__tier);
 {{#if backgroundSteps}}
     // Background runs here (inside beforeEach) — the app resets to its launch screen every scenario,
     // so Background setup (nav, dismiss launch promos…) must re-run after each relaunch, not once.

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

@@ -1,5 +1,5 @@
 import path from 'path';
-import { TestGeneratorAdapter, TestFileData, ScenarioData } from '../adapter-interface';
+import { TestGeneratorAdapter, TestFileData, ScenarioData, RenderImportsOptions } from '../adapter-interface';
 import { TemplateEngine } from '../../template-engine';
 
 /**
@@ -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; needsMock?: boolean; urlAssertImports?: string }): string {
+  renderImports(options?: RenderImportsOptions): string {
     return this.templateEngine.renderImports(options);
   }
 

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

@@ -15,6 +15,9 @@ import { mock } from '{{basePath}}/mock';
 {{#if urlAssertImports}}
 import { {{urlAssertImports}} } from '{{basePath}}/url-assert';
 {{/if}}
+{{#if regexEscapeImport}}
+import { escapeRegExp } from '{{basePath}}/regex-escape';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten