@sun-asterisk/sungen 3.2.22-beta.1 → 3.2.22

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/row-scoped-column-assertion.hbs

@@ -0,0 +1 @@
+{{!-- Column assertion scoped to the current row (`tableRow`, bound by the row-in-table entry step that ran before this one). columnIndex uses `isDefined` rather than a bare truthy check: column 0 is a valid index. --}}{{#if (isDefined columnIndex)}}await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth({{columnIndex}})).toHaveText('{{escapeQuotes cellValue}}');{{else if isGiven}}await tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '{{escapeQuotes cellValue}}' }).filter({ visible: true }).waitFor();{{else}}await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '{{escapeQuotes cellValue}}' }).filter({ visible: true })).toBeVisible();{{/if}}

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

@@ -72,23 +72,34 @@ function extractCleanupFlags(tags: string[]): { overlay?: boolean; forms?: boole
 }
 
 /**
- * Extract pass-through tags (non-functional) for Playwright { tag: [...] }.
- * Any tag not recognized by sungen as functional → pass through.
+ * Extract pass-through tags (non-functional) — the unique, unformatted tag tokens (e.g. `@smoke`).
+ * Any tag not recognized by sungen as functional → pass through. Formatting is adapter-specific
+ * (Playwright wants a quoted `{ tag: [...] }` array; Appium/mocha has no such option and instead
+ * appends the tags to the `it()` title — see `formatPassThroughTags`).
  */
 const FUNCTIONAL_TAG_PREFIXES = [
   '@parallel', '@serial', '@cleanup:', '@auth:', '@manual', '@no-auth',
   '@steps:', '@extend:', '@screenshot:', '@beforeAll', '@afterEach', '@afterAll',
-  '@flow', '@cases:', '@deferred:', '@owned-by:',
+  '@flow', '@cases:', '@deferred:', '@owned-by:', '@platform:',
 ];
 
-function extractPassThroughTags(scenarioTags: string[], featureTags: string[]): string | undefined {
+function extractPassThroughTags(scenarioTags: string[], featureTags: string[]): string[] {
   const allTags = [...featureTags, ...scenarioTags];
   const passThrough = allTags.filter(tag =>
     !FUNCTIONAL_TAG_PREFIXES.some(prefix => tag.startsWith(prefix))
   );
-  const unique = [...new Set(passThrough)];
-  if (unique.length === 0) return undefined;
-  return unique.map(t => `'${t}'`).join(', ');
+  return [...new Set(passThrough)];
+}
+
+/**
+ * Format the unique pass-through tags for the active adapter's `ScenarioData.tags` field:
+ *   - Playwright: `'@smoke', '@high'` — spliced verbatim into `{ tag: [...] }` (see scenario.hbs).
+ *   - Appium: `@smoke @high` — appended to the mocha `it()` title (D5) so `--grep` still filters,
+ *     since mocha has no per-test tag/annotation option like Playwright's.
+ */
+function formatPassThroughTags(tags: string[], frameworkName: string): string | undefined {
+  if (tags.length === 0) return undefined;
+  return frameworkName === 'appium' ? tags.join(' ') : tags.map(t => `'${t}'`).join(', ');
 }
 
 /**
@@ -712,6 +723,19 @@ export class CodeGenerator {
     // - Multiple groups: nested describes per auth role
     const needsGrouping = authGroups.length > 1;
 
+    // D6 — the Appium test-file template has no per-group before-hook (only `singleAuthRole` runs
+    // `__ensureAuth`); >1 auth group would render every group's scenarios with NO authentication at
+    // all, silently. Mirrors the web `@parallel` guard below, but unconditional (isParallel has no
+    // per-group meaning on mobile — the template never branches on it).
+    if (needsGrouping && this.adapter.frameworkName === 'appium') {
+      const roles = groupOrder.map(k => k || '(no @auth)').join(', ');
+      throw new Error(
+        `Feature "${feature.name}" has multiple auth groups (${roles}) but the Appium adapter only ` +
+        `supports a single shared auth role per feature — the other groups would run unauthenticated.\n` +
+        `Fix: split "${feature.name}" into one feature file per @auth role.`
+      );
+    }
+
     if (needsGrouping && !isParallel) {
       throw new Error(
         `Feature "${feature.name}" has multiple auth groups but no @parallel tag.\n` +
@@ -968,8 +992,9 @@ export class CodeGenerator {
       }
     }
 
-    // Extract pass-through tags (feature + scenario, excluding functional tags)
-    const tags = extractPassThroughTags(scenario.tags, featureTags);
+    // Extract pass-through tags (feature + scenario, excluding functional tags), formatted for
+    // the active adapter (Playwright `{ tag: [...] }` vs. Appium's mocha-title suffix — D5).
+    const tags = formatPassThroughTags(extractPassThroughTags(scenario.tags, featureTags), this.adapter.frameworkName);
 
     // Use adapter to render scenario
     const rendered = this.adapter.renderScenario({

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

@@ -40,12 +40,31 @@
  *             "3 cards are shown" gets an assertion that can only pass if the card's text
  *             IS the digit. Count semantics exist on row/table ("see [T] table with {{n}}",
  *             "see [Ref] row with {{n}}") and lists ("should have count") only
+ *   SG-E020 — the step matched a pattern whose template the ACTIVE adapter does not ship. Before
+ *             the platform SPI this was an unhandled `Template not found` that killed the WHOLE
+ *             feature file and named neither the step nor the adapter. The step now compiles to a
+ *             loud `throw`, the rest of the file still generates, and the message names the step,
+ *             the feature, the pattern, the template and the adapter
+ *   SG-W020 — the step matched a pattern that DECLARES its platforms (`platforms: ['web']`) and the
+ *             active platform is not among them — e.g. `@mock` route interception on mobile. Caught
+ *             before any template lookup, so it reports as a vocabulary mismatch rather than as a
+ *             confusing missing file, and names the native alternative
+ *   SG-W021 — `use dialog` (or `User is on [X] dialog`) under the mobile adapter: the scope is
+ *             recorded in the template base context, but NO Appium template reads `inDialog`, so
+ *             every following step resolves page-wide as if the scope had never been written.
+ *             Silently-ignored scope is the exact defect class this channel exists for — the step
+ *             LOOKS like it narrows the search and does not
+ *   SG-W022 — a `page` assertion on the mobile adapter that emitted NO executable code. A native app
+ *             has no URL, so `Then User see [X] page` compiles to a bare comment: the step reads as
+ *             an assertion, checks nothing, and the scenario PASSES regardless. Worse than the
+ *             crash class this plan closed — a crash is visible, a false pass is not. Its `is on`
+ *             twin routes to `route-assertion`, which throws; this half was silent
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015' | 'SG-E020' | 'SG-W020' | 'SG-W021' | 'SG-W022';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/patterns/index.ts

@@ -1,6 +1,6 @@
 import { ParsedStep } from '../../gherkin-parser';
 import { MappedStep } from '../step-mapper';
-import { StepPattern, PatternContext } from './types';
+import { StepPattern, PatternContext, Platform } from './types';
 import { capabilityRegistry } from '../../../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../../../capabilities/discover';
 
@@ -21,6 +21,78 @@ export function maskRefsForMatching(text: string): string {
     .replace(/\[[^\]]*\]/g, '[~]');
 }
 
+/**
+ * Gesture forms that OWN the word "tap" — each has its own pattern keyed on it (`mobile-double-tap`
+ * at priority 17, `tap-top-of-element` at 18) and means MORE than a click. They are the one
+ * carve-out from the synonym rule below: leave their text exactly as written.
+ */
+const TAP_GESTURE_FORMS = /\bdouble[-\s]?tap|\btap(?:s)?\b[^.]*\b(?:top of|at the top|at top)\b/i;
+
+/**
+ * `tap` is a synonym of `click` — for MATCHING only.
+ *
+ * The vocabulary was split: exactly three patterns in `@sungen/driver-mobile` key on "tap", while
+ * every other pattern in the shared vocabulary keys on "click". So a mobile-phrased step SILENTLY
+ * LOST meaning instead of failing — `User tap [Sign In] button and accept [OK] alert` matched the
+ * plain-tap pattern and the alert clause simply vanished, leaving a test that passed having checked
+ * less than it claimed. Green tests that assert nothing are the worst outcome in this whole class,
+ * which is why this is a synonym rather than 40 duplicated matchers.
+ *
+ * The rewrite is ADDITIVE — `tap` becomes `tap click`, it does not become `click`. Two reasons, and
+ * the first one cost a full golden run to learn:
+ *
+ *   1. `@sungen/driver-mobile` is registered on WEB projects too (same non-opt-in bundling as
+ *      driver-ui). Substituting the verb re-keys `mobile-tap` onto "click", where its priority 15
+ *      outranks the generic `click-element` (10) — so it captured every plain click on every WEB
+ *      feature and relabelled it a tap. 8 golden fixtures caught it. Adding a verb instead of
+ *      swapping one means text with no "tap" in it is returned untouched, so web output cannot
+ *      change here BY CONSTRUCTION rather than by our vigilance.
+ *   2. Both vocabularies then see their own verb, and ordinary PRIORITY decides the winner —
+ *      no matcher has to learn about the other. `tap … and accept alert` reaches
+ *      `click-with-alert` (21); `tap … in [T] table row 2` reaches `table-action-in-row-nth` (19);
+ *      a plain `tap` still lands on `mobile-tap` (15) ahead of `click-element` (10).
+ *
+ * Safe because every click-keyed matcher in the vocabulary is a word-boundary test (`\bclick(s)?\b`
+ * / `includes('click')`) — none depends on the verb's neighbours, and none tests for the ABSENCE of
+ * "click". Verified across driver-ui, driver-db, driver-mock and driver-mobile before relying on it.
+ *
+ * Resolvers and generators always receive the ORIGINAL `step.text`, so comments and value
+ * extraction never see this string.
+ *
+ * ORDER IS LOAD-BEARING: this runs AFTER `maskRefsForMatching`, so a selector or variable NAME
+ * containing "tap" (a `[Tap Water]` field) has already been blanked and cannot be rewritten into a
+ * verb. Reversing the two would reclassify that step as a click. The unit test asserts the order.
+ */
+export function normalizeVerbs(text: string): string {
+  if (TAP_GESTURE_FORMS.test(text)) return text;
+  return text.replace(/\btap(s|ped)?\b/gi, (m) => `${m} click`);
+}
+
+/**
+ * `TemplateEngine.loadStepTemplate` signals an absent `.hbs` with this exact message
+ * (`template-engine.ts`). Matching on it is what separates "this adapter cannot express the step"
+ * — a reviewable compile diagnostic — from a genuine bug inside a template, which must keep
+ * propagating untouched.
+ */
+const TEMPLATE_NOT_FOUND = /^Template not found: (.+)\.hbs in any subfolder$/;
+
+/**
+ * The step body emitted in place of code the active adapter cannot produce. A comment alone would
+ * let the test go GREEN having asserted nothing — the silent-loss class this SPI exists to close —
+ * so the step throws at run time as well as reporting at compile time.
+ *
+ * `JSON.stringify` does the quoting, NOT a hand-rolled `replace(/'/g, …)`. The reason string embeds
+ * arbitrary author text (the step sentence), and hand-escaping only the quote character is wrong for
+ * any input containing a backslash or a raw newline: a step ending `…\` would emit `'…\\'`, whose
+ * trailing escaped-backslash-then-quote breaks the literal and takes the WHOLE generated spec down
+ * with a syntax error — reopening, one level deeper, the exact "one bad step kills the file" failure
+ * this function exists to prevent. Step text here is routinely non-ASCII (Vietnamese, Japanese),
+ * which JSON.stringify also handles correctly.
+ */
+function unsupportedStepCode(reason: string): string {
+  return `throw new Error(${JSON.stringify(`[sungen] ${reason}`)});`;
+}
+
 /**
  * Pattern Registry - manages all step patterns
  */
@@ -59,7 +131,10 @@ export class PatternRegistry {
   findPattern(step: ParsedStep): StepPattern | null {
     // Match against text with ref CONTENTS masked, so a verb substring inside a selector/data name
     // (e.g. "click" in `{{double_click_guard_account.email}}`) can't hijack the verb classification.
-    const matchStep: ParsedStep = { ...step, text: maskRefsForMatching(step.text) };
+    // THEN normalise `tap` → `click`, so the mobile phrasing reaches the whole shared vocabulary
+    // instead of only the three patterns that happen to key on "tap". Masking first is what keeps a
+    // `[Tap Water]` ref from being read as a verb.
+    const matchStep: ParsedStep = { ...step, text: normalizeVerbs(maskRefsForMatching(step.text)) };
     for (const pattern of this.patterns) {
       if (this.matchesPattern(matchStep, pattern.matcher)) {
         return pattern;
@@ -77,39 +152,105 @@ export class PatternRegistry {
     // test-data value, e.g. row-count's numeric check). A resolver may therefore return
     // null to say "not mine after all" — the search continues with the next matching
     // pattern in priority order instead of crashing or silently dropping the step.
-    const matchStep: ParsedStep = { ...step, text: maskRefsForMatching(step.text) };
+    // Matching mirrors findPattern exactly: refs masked FIRST (so `[Tap Water]` is not a
+    // verb), then `tap` → `click` normalisation for the mobile vocabulary.
+    const matchStep: ParsedStep = { ...step, text: normalizeVerbs(maskRefsForMatching(step.text)) };
     for (const pattern of this.patterns) {
       if (!this.matchesPattern(matchStep, pattern.matcher)) continue;
 
-      // Prefer resolver (framework-agnostic) over generator (legacy)
-      if (pattern.resolver) {
-        const resolved = pattern.resolver(step, context);
-        if (!resolved) continue; // resolver declined — fall through
-
-        // Auto-inject parent scoping if step has parentRef
-        // Skip for table-* patterns — they resolve the table name internally from step text
-        if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
-          resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
-            step.parentRef, step.parentType, context
-          );
+      // Platform gate — BEFORE any template lookup. A pattern that declares its platforms and is
+      // matched on another one is a vocabulary mismatch, not a missing file: report it in its own
+      // terms (SG-W020) rather than letting it fail later as a confusing absent template.
+      const platformMiss = PatternRegistry.platformMiss(pattern, context, step);
+      if (platformMiss) return platformMiss;
+
+      try {
+        // Prefer resolver (framework-agnostic) over generator (legacy)
+        if (pattern.resolver) {
+          const resolved = pattern.resolver(step, context);
+          if (!resolved) continue; // resolver declined — fall through
+
+          // Auto-inject parent scoping if step has parentRef
+          // Skip for table-* patterns — they resolve the table name internally from step text
+          if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
+            resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
+              step.parentRef, step.parentType, context
+            );
+          }
+
+          const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
+          return {
+            code,
+            comment: resolved.comment,
+          };
         }
 
-        const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
-        return {
-          code,
-          comment: resolved.comment,
-        };
-      }
+        if (pattern.generator) {
+          return pattern.generator(step, context);
+        }
 
-      if (pattern.generator) {
-        return pattern.generator(step, context);
+        return null;
+      } catch (err: any) {
+        // The step matched a pattern the ACTIVE adapter has no template for. Before this guard the
+        // unhandled throw killed the ENTIRE feature file and named neither the step nor the adapter.
+        const missing = TEMPLATE_NOT_FOUND.exec(String(err?.message ?? ''));
+        if (!missing) throw err;
+        return PatternRegistry.unsupportedTemplate(missing[1], pattern, context, step);
       }
-
-      return null;
     }
     return null;
   }
 
+  /**
+   * SG-W020 — the matched pattern declares `platforms` and the active one is not among them.
+   */
+  private static platformMiss(
+    pattern: StepPattern, context: PatternContext, step: ParsedStep
+  ): MappedStep | null {
+    const platform: Platform = context.platform ?? 'web';
+    if (!pattern.platforms || pattern.platforms.includes(platform)) return null;
+
+    const adapter = context.adapterName ?? platform;
+    const supported = pattern.platforms.join('/');
+    const alternative = pattern.platformAlternative
+      ?? 'use a supported step form, or tag the scenario @manual';
+    const reason =
+      `step "${step.text}" uses pattern "${pattern.name}", which is ${supported}-only — ` +
+      `the ${adapter} adapter cannot express it. Instead: ${alternative}.`;
+
+    context.diagnostics?.add('SG-W020', reason, {
+      feature: context.featureName,
+      step: step.text,
+    });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `${supported}-only step on the ${adapter} adapter — see SG-W020`,
+    };
+  }
+
+  /**
+   * SG-E020 — the pattern is in-platform but the active adapter ships no template for it. A gap in
+   * the adapter, not in the authored Gherkin: name every coordinate a reader needs to act on it.
+   */
+  private static unsupportedTemplate(
+    templateName: string, pattern: StepPattern, context: PatternContext, step: ParsedStep
+  ): MappedStep {
+    const adapter = context.adapterName ?? context.platform ?? 'web';
+    const reason =
+      `step "${step.text}" needs template "${templateName}.hbs", which the ${adapter} adapter ` +
+      `does not ship (pattern "${pattern.name}"). Rephrase with a supported step form, or tag ` +
+      `the scenario @manual.`;
+
+    context.diagnostics?.add('SG-E020', reason, {
+      feature: context.featureName,
+      step: step.text,
+    });
+    return {
+      code: unsupportedStepCode(reason),
+      comment: `no ${adapter} template for "${templateName}" — see SG-E020`,
+    };
+  }
+
   /**
    * Resolve parent scoping to a Playwright locator string.
    * Tries YAML lookup first, falls back to auto-infer from parentType.

package/src/generators/test-generator/patterns/types.ts

@@ -3,6 +3,22 @@ import { MappedStep } from '../step-mapper';
 import { SelectorResolver } from '../utils/selector-resolver';
 import { DataResolver } from '../utils/data-resolver';
 
+/**
+ * The subset of DiagnosticsCollector the pattern layer needs. Structural, not a class import,
+ * so the framework-agnostic pattern SPI keeps depending on nothing concrete.
+ */
+export interface DiagnosticsSink {
+  add(code: any, message: string, context?: { feature?: string; step?: string }): void;
+}
+
+/**
+ * The platform a pattern (and its templates) can compile for. Drawn from the ACTIVE adapter:
+ * `appium` → 'mobile', everything else → 'web'. A pattern that omits `platforms` is assumed to
+ * work on BOTH — the historical assumption, kept as the default so no existing pattern changes
+ * behaviour.
+ */
+export type Platform = 'web' | 'mobile';
+
 /**
  * Pattern matcher function or regex
  */
@@ -44,6 +60,12 @@ export interface PatternContext {
   scenarioSteps?: ParsedStep[];
   /** Effective Gherkin keyword (Given/When/Then), resolved from And/But */
   effectiveKeyword?: string;
+  /** The platform the ACTIVE adapter compiles for. Absent = 'web' (back-compat default). */
+  platform?: Platform;
+  /** The adapter's own name ('playwright' | 'appium' | …) — quoted verbatim in SG-E020/SG-W020. */
+  adapterName?: string;
+  /** Compile-diagnostics channel, so the pattern layer can report instead of throwing. */
+  diagnostics?: DiagnosticsSink;
   /** App profile (qa/app.yaml merged over presets/defaults) — widget variants, recipes,
    *  loading indicator, table row conventions. Typed loosely to keep the SPI decoupled;
    *  the concrete shape is ResolvedAppProfile. */
@@ -69,4 +91,17 @@ export interface StepPattern {
   resolver?: PatternResolver;
   generator?: PatternGenerator;
   priority?: number;
+  /**
+   * Platforms this pattern can compile for. ABSENT = both (the default — every pattern that
+   * predates the platform SPI). Declaring it narrows the pattern: matching it on any other
+   * platform emits SG-W020 and compiles to a loud runtime `throw` instead of silently
+   * producing code that references a driver the platform does not have.
+   */
+  platforms?: ReadonlyArray<Platform>;
+  /**
+   * Free-text alternative named in the SG-W020 message when this pattern is used off-platform
+   * (e.g. "`@api` / `@query`, or tag the scenario @manual"). Optional — a generic pointer is
+   * emitted when absent.
+   */
+  platformAlternative?: string;
 }

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

@@ -1,7 +1,7 @@
 import { ParsedStep } from '../gherkin-parser';
 import { TemplateEngine } from './template-engine';
 import { adapterRegistry } from './adapters';
-import { PatternRegistry, PatternContext } from './patterns';
+import { PatternRegistry, PatternContext, Platform } from './patterns';
 import { SelectorResolver } from './utils/selector-resolver';
 import { DataResolver } from './utils/data-resolver';
 import { DiagnosticsCollector } from './diagnostics';
@@ -49,6 +49,10 @@ export class StepMapper {
   private diagnostics?: DiagnosticsCollector;
   /** App profile (qa/app.yaml merged over presets/defaults) — the per-project BEHAVIOR layer */
   private appProfile: ResolvedAppProfile;
+  /** The platform the ACTIVE adapter compiles for — drives the pattern-layer platform gate */
+  private platform: Platform;
+  /** The active adapter's own name ('playwright' | 'appium') — quoted in SG-E020/SG-W020 */
+  private adapterName: string;
 
   constructor(options: { verbose?: boolean; baseURL?: string; featureName?: string; screenName?: string; featurePath?: string; runtimeData?: boolean; framework?: string } = {}) {
     this.verbose = options.verbose ?? false;
@@ -60,7 +64,13 @@ export class StepMapper {
     // mobile→Appium). The adapter owns its templatesDir; resolving it here keeps step
     // rendering and the file skeleton (code-generator) on the same framework.
     const framework = options.framework || 'web';
-    const templatesDir = adapterRegistry.getAdapter(framework).templatesDir;
+    const adapter = adapterRegistry.getAdapter(framework);
+    const templatesDir = adapter.templatesDir;
+    // The platform gate keys on the ADAPTER, not on the requested framework name: 'mobile' and
+    // 'appium' are aliases of the same adapter, so asking the adapter itself keeps one source of
+    // truth as more aliases appear.
+    this.adapterName = adapter.frameworkName;
+    this.platform = adapter.frameworkName === 'appium' ? 'mobile' : 'web';
     this.templateEngine = new TemplateEngine(templatesDir);
     this.patternRegistry = new PatternRegistry();
     this.selectorResolver = new SelectorResolver(undefined, options.screenName);
@@ -234,10 +244,12 @@ export class StepMapper {
       const selectorRef = step.selectorRef || '';
 
       if (selectorRef.toLowerCase() === 'main') {
-        // Exit frame scope
+        // Exit frame scope — routed through the adapter (C1): the Appium twin performs the
+        // real webview→native context switch; a bare comment here would silently no-op on mobile.
         this.inFrameScope = false;
         this.templateEngine.setBaseContext({ inFrame: false });
-        return { code: '// Back to main page context', comment: 'Exit frame scope' };
+        const code = this.templateEngine.renderStep('frame-exit-action', {});
+        return { code, comment: 'Exit frame scope' };
       }
 
       // Enter frame scope
@@ -250,7 +262,9 @@ export class StepMapper {
         // Use selectorRef as-is
       }
       this.templateEngine.setBaseContext({ inFrame: true, frameSelector });
-      const code = `const frame = page.frameLocator('${frameSelector}');`;
+      // C1 — routed through the adapter instead of building `page.frameLocator(...)` inline:
+      // the Appium adapter's own template performs its webview-context switch instead.
+      const code = this.templateEngine.renderStep('frame-enter-action', { frameSelector });
       return { code, comment: `Switch to ${selectorRef} frame` };
     }
 
@@ -258,6 +272,7 @@ export class StepMapper {
     if (/\buse dialog\b/i.test(step.text)) {
       this.inDialogScope = true;
       this.templateEngine.setBaseContext({ inDialog: true });
+      this.warnDialogScopeIgnoredOnMobile(step);
       return { code: '', comment: 'Enter dialog scope' };
     }
     if (/\b(?:close|dismiss|exit)\s+dialog\b/i.test(step.text)) {
@@ -268,6 +283,7 @@ export class StepMapper {
     // Given User is on [...] dialog — set dialog scope (3 cases)
     if (step.text.includes('is on') && step.elementType === 'dialog') {
       this.inDialogScope = true;
+      this.warnDialogScopeIgnoredOnMobile(step);
       // setBaseContext MERGES — clear every root key so a previous dialog scope in the
       // same scenario cannot leak its root into this one.
       const contextVars: Record<string, any> = {
@@ -355,6 +371,7 @@ export class StepMapper {
         console.log(`  ✓ Pattern matched: ${step.text.substring(0, 50)}...`);
       }
       this.checkDataRefConsumed(step, mappedStep);
+      this.checkPageAssertionNoOpOnMobile(step, mappedStep);
       this.checkPageAssertionFallback(step, mappedStep);
       this.checkDeclaredUrlHasNoQuery(step, mappedStep);
       return mappedStep;
@@ -515,6 +532,11 @@ export class StepMapper {
    * includeHidden + visible filter: when a modal (e.g. Radix Dialog) is open the
    * background gets aria-hidden="true", which empties plain getByRole() even though
    * the cells are still rendered — measure what the user SEES, not the a11y tree.
+   *
+   * C2 — this method used to build the Playwright code string itself (referencing `tableRow`,
+   * a binding that only exists in the Playwright output). It now only gathers data and routes
+   * through the adapter template; the Appium twin throws (HTML table roles), matching the
+   * `table-*` house style.
    */
   private generateRowScopedColumnAssertion(step: ParsedStep): MappedStep {
     const columnRef = step.selectorRef || '';
@@ -537,24 +559,9 @@ export class StepMapper {
     }
 
     const isGiven = this.lastPrimaryKeyword === 'Given';
-    const escapedValue = cellValue.replace(/'/g, "\\'");
-
-    let code: string;
-    if (columnIndex !== undefined) {
-      // Exact cell: nth(index) + toHaveText
-      if (isGiven) {
-        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth(${columnIndex})).toHaveText('${escapedValue}');`;
-      } else {
-        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ visible: true }).nth(${columnIndex})).toHaveText('${escapedValue}');`;
-      }
-    } else {
-      // Fallback: filter by text
-      if (isGiven) {
-        code = `await tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '${escapedValue}' }).filter({ visible: true }).waitFor();`;
-      } else {
-        code = `await expect(tableRow.getByRole('cell', { includeHidden: true }).filter({ hasText: '${escapedValue}' }).filter({ visible: true })).toBeVisible();`;
-      }
-    }
+    const code = this.templateEngine.renderStep('row-scoped-column-assertion', {
+      columnIndex, cellValue, isGiven,
+    });
 
     return {
       code,
@@ -565,6 +572,57 @@ export class StepMapper {
   /**
    * Create pattern context for generators
    */
+  /**
+   * SG-W022 — a `page` assertion that emitted no executable code on mobile.
+   *
+   * A native app has no URL, so the Appium `page-assertion` template is a bare comment. The step
+   * therefore READS as an assertion and checks nothing: the scenario passes whatever the app is
+   * showing. That is strictly worse than the missing-template crashes this pass closed — a crash is
+   * visible on the first run, a false pass hides until someone trusts it. (Its `is on [X] page` twin
+   * routes to `route-assertion`, which throws loudly; only this half was silent.)
+   *
+   * Keyed on the EMITTED CODE rather than on a template name, so any future page-assertion path
+   * that degrades to a comment is caught by the same check without being enumerated here. Scoped to
+   * the `see` form: the `is on` twin is mobile's app-launch directive, whose empty output is right.
+   */
+  private checkPageAssertionNoOpOnMobile(step: ParsedStep, mapped: MappedStep): void {
+    if (this.platform !== 'mobile' || !this.diagnostics) return;
+    if (step.elementType !== 'page') return;
+    // Only the ASSERTION form. `Given User is on [X] page` is the app-LAUNCH directive on mobile —
+    // it emits a comment because wdio capabilities already launched the app, which is correct and
+    // must not be warned about. `Then User see [X] page` is the one that claims to check something.
+    if (!/\bsees?\b/i.test(step.text)) return;
+    // Strip comments; whatever remains is what actually runs. Block comments are handled as well as
+    // line ones: a template written with `/* … */` would otherwise read as executable code and
+    // silently defeat this check — the diagnostic would go quiet exactly when it was needed.
+    const executable = (mapped.code || '')
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .split('\n')
+      .map((l) => l.replace(/\/\/.*$/, '').trim())
+      .filter(Boolean)
+      .join('');
+    if (executable) return;
+    this.diagnostics.add('SG-W022',
+      'a native app has no URL, so this page assertion compiled to a COMMENT — it asserts nothing and the scenario passes regardless. Assert a marker that is actually on the screen instead (`Then User see [Some Element] ...`), or tag the scenario @manual',
+      { feature: this.featureName, step: step.text });
+  }
+
+  /**
+   * SG-W021 — dialog scope is a no-op on the Appium adapter.
+   *
+   * `setBaseContext({ inDialog: true })` records the scope faithfully, and every Playwright locator
+   * partial consults it. No Appium template does. So on mobile the step reads as "narrow everything
+   * that follows to this dialog" and in fact narrows nothing — the following steps search the whole
+   * screen. Scope that is silently discarded is what produced this entire defect class, so it is
+   * reported rather than left to be discovered from a passing test.
+   */
+  private warnDialogScopeIgnoredOnMobile(step: ParsedStep): void {
+    if (this.platform !== 'mobile') return;
+    this.diagnostics?.add('SG-W021',
+      'dialog scope has no effect on the mobile adapter — no Appium template reads `inDialog`, so the following steps resolve against the whole screen, not the dialog. Scope the elements themselves instead (a `scope: dialog` entry, or accessibility-ids unique to the dialog)',
+      { feature: this.featureName, step: step.text });
+  }
+
   private createPatternContext(): PatternContext {
     return {
       stepCounter: this.stepCounter,
@@ -577,6 +635,9 @@ export class StepMapper {
       dataResolver: this.dataResolver,
       renderLocator: (resolved) => this.templateEngine.renderStep('locator', resolved),
       appProfile: this.appProfile,
+      platform: this.platform,
+      adapterName: this.adapterName,
+      diagnostics: this.diagnostics,
       baseURL: this.baseURL,
       featureName: this.featureName,
       screenName: this.screenName,

package/src/orchestrator/templates/ai-src/skills/sungen-api-design/SKILL.md

@@ -79,10 +79,10 @@ A flow (`create → login → delete`) is a **Functional integration** test, **n
         - ":gift_image_1"    # test-data: gift_image_1 → fixtures/a.png
         - ":gift_image_2"    # test-data: gift_image_2 → fixtures/b.png
     ```
-    Each element binds its own `:param` from test-data. Use this for endpoints that accept a list of files under the same field — a single object value can only hold one file. **Automate multi-file uploads with `@api`; don't defer to `@manual`.** (File uploads use Playwright's `FormData` multipart, which requires **`@playwright/test` ≥ 1.44** — the version sungen installs by default; only projects pinned to an older Playwright need to upgrade.)
+    Each element binds its own `:param` from test-data. Use this for endpoints that accept a list of files under the same field — a single object value can only hold one file. **Automate multi-file uploads with `@api`; don't defer to `@manual`.** (File uploads are sent as `multipart/form-data` built on Node's global `FormData`/`Blob` — **Node 18+, no Playwright dependency**, so the same upload runs in mobile specs too.)
 - **`bodyFile:`** → raw binary body (the whole body IS the file's bytes, e.g. `application/octet-stream`): `bodyFile: { path: ":image", mimeType: application/octet-stream }`.
 
-Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (drop sample files there, reference by name from `test-data`). An empty resolved file param omits the part → use for missing-file `@cases` error rows. `files:`/`bodyFile:` are mutually exclusive. **Automate the upload success case with `@api`** — don't defer it to `@manual`.
+Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (drop sample files there, reference by name from `test-data`). An empty resolved file param omits the part → use for missing-file `@cases` error rows. `files:`/`bodyFile:` are mutually exclusive. A **`GET`/`HEAD` entry may carry no body at all** (no `body:`/`files:`/`bodyFile:`) — HTTP forbids it and the catalog lint refuses it; put the inputs in the path or `query`, or use `POST`. **Automate the upload success case with `@api`** — don't defer it to `@manual`.
 
 ## Per-endpoint knobs & auth patterns
 - **Timeout** — a slow endpoint can override the datasource default (15s) with `timeout_ms: 30000` on its catalog entry (else the datasource `timeout_ms` applies).

package/src/orchestrator/templates/ai-src/skills/sungen-error-mapping/SKILL.md

@@ -99,6 +99,10 @@ needs any of these, it is a **finding for QA** — surface it in the run summary
 | `SG-W012` | A mock-install step written AFTER a navigation step in the same block — `page.route()` registered after `goto()` misses every request fired during page load | Move the mock-install step before the navigation, or into `Background` |
 | `SG-W013` | A page assertion (`see [X] page` / `is on [X] page`) whose `[Ref]` has no `type: page` selector entry (or collides with a non-page entry) — the step falls back to the feature's own path (or `/<ref>/`) instead of `X`'s real URL, so the anchored assertion can never pass | Declare a `type: page` entry for `[Ref]` with its real URL; if the key collides with another type, disambiguate with a `--type` suffix (`sungen-selector-keys` § Collision rule) |
 | `SG-W014` | `[X] page with {{v}}` where `{{v}}`'s base test-data value carries no query and no fragment — the step checks the PATH only, asserting less than it reads as | Informational — pass a value like `?q=…` if you meant to assert a query, or drop `with {{v}}` for a bare page |
+| `SG-E020` | A step matched a pattern, but the **active adapter ships no template** for it (e.g. a web-only step compiled under `platform: mobile`). The feature file still generates — that one step compiles to `throw new Error("[sungen] …")` naming the step, feature, pattern, template and adapter, so the failure is loud and traceable rather than a crashed build | Rephrase to a step the target adapter actually ships (see `sungen-gherkin-syntax` Platform Support section / `sungen-mobile-gestures`), or tag the scenario `@manual` with the platform reason |
+| `SG-W020` | The matched pattern **declares `platforms`** (today: `@mock`) and the active platform isn't among them. Caught before template lookup, so the diagnostic can name the native alternative directly | Drop `@mock` from a mobile unit (there is no Mock Driver on Appium) — use `@api`/`@query` or a `@manual` note instead |
+| `SG-W021` | `use dialog` / `User is on [X] dialog` scope under the **mobile** adapter — the scope is recorded but no Appium template reads `inDialog`, so every following step resolves against the whole screen, not just the dialog | Don't rely on `scope: dialog`/`use dialog` for disambiguation on mobile — give the element inside the dialog its own unique accessibility-id/testid instead |
+| `SG-W022` | `Then User see [X] page` under the **mobile** adapter — a native app has no URL, so the step compiles to a bare COMMENT: it reads as an assertion, checks nothing, and the scenario passes whatever is on screen. Worse than a hard failure, because nothing ever goes red. (Its `is on [X] page` twin throws via `route-assertion`; `Given User is on [X] page` is the app-LAUNCH directive and correctly emits nothing) | Assert something actually on the screen — `Then User see [Some Header] text` / a screen-marker accessibility-id — instead of a page/URL check, or tag the scenario `@manual` |
 
 ### Runtime error → `Test data "<key>" references ${QA_*} but the environment variable is not set`