@sun-asterisk/sungen 3.2.0 → 3.2.2-beta.1

package/src/exporters/feature-parser.ts

@@ -164,6 +164,9 @@ export function splitVpAndName(scenarioName: string): { vpId?: string; category1
  * Map VP prefix to Category 2.
  * XSS/Injection security tests are input-validation tests → Function.
  * All other VP-SEC tests (auth, RBAC, access control) → Accessing.
+ * API auth viewpoints (missing/invalid/insufficient credentials) are access-control
+ * tests → Accessing; every other API viewpoint (contract, error, idempotency, flow,
+ * async, and the numbered baseline ids) is functional → Function.
  */
 export function mapVpToCategory2(vpId: string | undefined, scenarioName?: string): string {
   if (!vpId) return 'Function';
@@ -171,12 +174,66 @@ export function mapVpToCategory2(vpId: string | undefined, scenarioName?: string
     if (scenarioName && /xss|injection/i.test(scenarioName)) return 'Function';
     return 'Accessing';
   }
+  if (vpId.startsWith('VP-API-')) {
+    if (vpId.startsWith('VP-API-AUTH')) return 'Accessing';
+    return 'Function';
+  }
   if (vpId.startsWith('VP-UI-')) return 'GUI';
   if (vpId.startsWith('VP-VAL-')) return 'Function';
   if (vpId.startsWith('VP-LOGIC-')) return 'Function';
   return 'Function';
 }
 
+// ---------------------------------------------------------------------------
+// API annotation helpers
+// Used by the XLSX API-detail sheet only — no effect on CSV/BM-2-901-13 path.
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract ordered @api:<name> call sequence from feature-level or scenario tags.
+ * Tags may contain call arguments: @api:register(name={{x}},email={{y}}) — we strip
+ * the argument parens and keep only the endpoint name.
+ *
+ * Example: ["@api:register(name={{n}})", "@api:count_users(email={{e}})"]
+ *       → ["register", "count_users"]
+ */
+export function extractApiCallOrder(tags: string[]): string[] {
+  return tags
+    .filter((t) => t.startsWith('@api:'))
+    .map((t) => {
+      const body = t.slice('@api:'.length);
+      const parenIdx = body.indexOf('(');
+      return parenIdx >= 0 ? body.slice(0, parenIdx) : body;
+    });
+}
+
+/**
+ * Extract the @cases:<dataset> name from tags (returns the first one found, or null).
+ * Used to label the "cases" annotation so the detail sheet can note which scenarios
+ * exercise a given endpoint with a matrix of input/status pairs.
+ */
+export function extractCasesDataset(tags: string[]): string | null {
+  const tag = tags.find((t) => t.startsWith('@cases:'));
+  return tag ? tag.slice('@cases:'.length) : null;
+}
+
+/**
+ * Extract the concurrency invariant text from @concurrent:<N> and @query:<oracle> tags.
+ * N is the number of parallel fires; the invariant the band proves is exactly-one success
+ * (regardless of N), cross-checked by the @query DB oracle. Returns e.g.
+ * "2× parallel → exactly-one; @query user_count", or '' when absent.
+ */
+export function extractConcurrencyInvariant(tags: string[]): string {
+  const concurrentTag = tags.find((t) => t.startsWith('@concurrent:'));
+  if (!concurrentTag) return '';
+  const n = concurrentTag.slice('@concurrent:'.length);
+  const queryTag = tags.find((t) => t.startsWith('@query:'));
+  const oracle = queryTag ? queryTag.slice('@query:'.length).split('(')[0] : '';
+  const parts = [`${n}× parallel → exactly-one`];
+  if (oracle) parts.push(`@query ${oracle}`);
+  return parts.join('; ');
+}
+
 /**
  * Generate TC ID, namespaced by screen/flow so it is globally unique across the
  * whole project. This matters because the dashboard tracks each test case by its

package/src/exporters/types.ts

@@ -128,3 +128,41 @@ export interface EnvironmentInfo {
   projectName: string;
   executor: string;
 }
+
+/**
+ * One row in the "API detail" worksheet — one row per catalog endpoint.
+ * Populated from the apis.yaml catalog + scenario annotations (@cases, @api, @concurrent).
+ * Only emitted for api-kind units; never touches the BM-2-901-13 Testcases sheet.
+ */
+export interface ApiDetailRow {
+  /** Endpoint path from catalog (e.g. /register, /users/count?email=:email) */
+  endpoint: string;
+  /** HTTP method (GET, POST, …) */
+  method: string;
+  /** Auth / datasource string composed from catalog datasource + any @auth tag */
+  authDatasource: string;
+  /** Request shape: body fields / params / encoding from the catalog entry */
+  requestShape: string;
+  /** Expected-status matrix: the catalog expect.status plus a pointer to any @cases dataset
+   *  that drives this endpoint, e.g. "201; @cases:register_cases". */
+  expectedStatusMatrix: string;
+  /** Ordered @api:<name> call sequence for flow scenarios referencing this endpoint */
+  flowSteps: string;
+  /** Concurrency invariant for @concurrent scenarios, e.g. "2× parallel → exactly-one; @query <oracle>" */
+  concurrencyInvariant: string;
+}
+
+/**
+ * Catalog entry as parsed from apis.yaml.
+ * All fields are typed loosely (unknown) because the yaml structure may vary — callers
+ * must guard before use.
+ */
+export interface ApiCatalogEntry {
+  method?: string;
+  path?: string;
+  datasource?: string;
+  description?: string;
+  body?: unknown;
+  params?: unknown;
+  expect?: { status?: number | string };
+}

package/src/exporters/xlsx-exporter.ts

@@ -13,10 +13,15 @@ import * as fs from 'fs';
 import * as path from 'path';
 import ExcelJS from 'exceljs';
 import JSZip from 'jszip';
-import { ScreenSummary, TestCaseRow } from './types';
+import { ApiCatalogEntry, ApiDetailRow, ScreenSummary, TestCaseRow } from './types';
 import { getPackageVersion } from './package-info';
 import { SUN_LOGO_PNG_BASE64 } from './sun-logo';
 import { deliverableBasename } from './csv-exporter';
+import {
+  extractApiCallOrder,
+  extractCasesDataset,
+  extractConcurrencyInvariant,
+} from './feature-parser';
 
 const COL_COUNT = 16;
 const HEADER_FILL = 'FFD9D2E9'; // lavender — matches the summary-header band on row 6
@@ -37,15 +42,31 @@ function applyBorder(cell: AnyCell): void {
   };
 }
 
+/**
+ * Optional context for the supplementary "API detail" worksheet.
+ * Passed only when the unit is kind:api. When omitted, only the standard
+ * Testcases sheet is emitted (non-api delivery stays byte-identical).
+ */
+export interface ApiDetailContext {
+  /** Parsed apis.yaml catalog keyed by endpoint name */
+  catalog: Record<string, ApiCatalogEntry>;
+  /** Pre-built detail rows (one per catalog endpoint) */
+  rows: ApiDetailRow[];
+}
+
 export function renderXlsx(
   summary: ScreenSummary,
   rows: TestCaseRow[],
-  specLink: string
+  specLink: string,
+  apiDetail?: ApiDetailContext,
 ): ExcelJS.Workbook {
   const wb = new ExcelJS.Workbook();
   wb.creator = 'sungen delivery';
   wb.created = new Date();
   addTestcaseSheet(wb, 'Testcases', summary, rows, specLink);
+  if (apiDetail) {
+    addApiDetailSheet(wb, apiDetail.rows);
+  }
   return wb;
 }
 
@@ -410,6 +431,159 @@ function addTestcaseSheet(
   };
 }
 
+// ---------------------------------------------------------------------------
+// API detail sheet (api-kind units only)
+// Second worksheet appended after Testcases — never alters the Testcases sheet.
+// ---------------------------------------------------------------------------
+
+const API_DETAIL_HEADER_FILL = 'FF2E5984'; // dark blue header for differentiation
+const API_DETAIL_HEADER_FONT = 'FFFFFFFF'; // white text on dark header
+
+/**
+ * Build ApiDetailRow[] from the apis.yaml catalog + feature-level annotations.
+ * Called once per feature file for api-kind units in the delivery pipeline.
+ *
+ * @param catalog   Parsed apis.yaml keyed by endpoint name
+ * @param scenarios Scenario-level tag arrays from parseFeatureMetadata().scenarios
+ */
+export function buildApiDetailRows(
+  catalog: Record<string, ApiCatalogEntry>,
+  scenarios: Array<{ tags: string[] }>,
+): ApiDetailRow[] {
+  const rows: ApiDetailRow[] = [];
+
+  for (const [endpointName, entry] of Object.entries(catalog)) {
+    const method = (entry.method ?? '').toUpperCase();
+    const endpoint = entry.path ?? endpointName;
+    const datasource = entry.datasource ?? '';
+
+    // Auth: look for @auth: tag in any scenario that calls this endpoint.
+    const authTags = scenarios.flatMap((s) => {
+      const calls = extractApiCallOrder(s.tags);
+      if (!calls.includes(endpointName)) return [];
+      return s.tags.filter((t) => t.startsWith('@auth:'));
+    });
+    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)}`
+      : '';
+    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('; ') || '—';
+
+    // Expected-status matrix: aggregate @cases dataset labels + expected status
+    // from scenarios that call this endpoint. Fall back to catalog expect.status.
+    const statusEntries: string[] = [];
+    for (const sc of scenarios) {
+      const calls = extractApiCallOrder(sc.tags);
+      if (!calls.includes(endpointName)) continue;
+      const dataset = extractCasesDataset(sc.tags);
+      if (dataset) {
+        // @cases dataset name as label — actual per-row statuses live in test-data.yaml
+        statusEntries.push(`@cases:${dataset}`);
+      }
+    }
+    // Show the catalog baseline status plus a pointer to any @cases matrix dataset (the per-row
+    // statuses live in test-data; resolving them into this cell is a later enrichment).
+    const catalogStatus = entry.expect?.status != null ? String(entry.expect.status) : '';
+    const expectedStatusMatrix =
+      [catalogStatus, ...new Set(statusEntries)].filter(Boolean).join('; ') || '—';
+
+    // Flow steps: ordered @api names from flow-tagged scenarios referencing this endpoint.
+    const flowStepsSet = new Set<string>();
+    for (const sc of scenarios) {
+      const calls = extractApiCallOrder(sc.tags);
+      if (!calls.includes(endpointName)) continue;
+      // All scenarios show their call order; flow scenarios show multi-step chains.
+      if (calls.length > 1) {
+        flowStepsSet.add(calls.join(' → '));
+      }
+    }
+    const flowSteps = [...flowStepsSet].join('; ') || '—';
+
+    // Concurrency invariant: from @concurrent scenarios calling this endpoint.
+    const concurrencyParts: string[] = [];
+    for (const sc of scenarios) {
+      const calls = extractApiCallOrder(sc.tags);
+      if (!calls.includes(endpointName)) continue;
+      const inv = extractConcurrencyInvariant(sc.tags);
+      if (inv) concurrencyParts.push(inv);
+    }
+    const concurrencyInvariant = concurrencyParts.join('; ') || '—';
+
+    rows.push({
+      endpoint,
+      method,
+      authDatasource,
+      requestShape,
+      expectedStatusMatrix,
+      flowSteps,
+      concurrencyInvariant,
+    });
+  }
+
+  return rows;
+}
+
+/**
+ * Append a second "API detail" worksheet to the workbook.
+ * Called only for api-kind units; no effect on the Testcases sheet or other sheets.
+ *
+ * Columns: Endpoint · Method · Auth/Datasource · Request shape ·
+ *          Expected-status matrix · Flow steps · Concurrency invariant
+ */
+export function addApiDetailSheet(wb: ExcelJS.Workbook, detailRows: ApiDetailRow[]): void {
+  const ws = wb.addWorksheet('API detail');
+  const ARIAL_FONT = 'Arial';
+
+  ws.columns = [
+    { header: 'Endpoint',                width: 35 },
+    { header: 'Method',                  width: 10 },
+    { header: 'Auth / Datasource',       width: 22 },
+    { header: 'Request shape',           width: 40 },
+    { header: 'Expected-status matrix',  width: 30 },
+    { header: 'Flow steps',              width: 40 },
+    { header: 'Concurrency invariant',   width: 35 },
+  ];
+
+  // Style the auto-generated header row (row 1).
+  const headerRow = ws.getRow(1);
+  headerRow.height = 30;
+  headerRow.eachCell((cell) => {
+    cell.font = { bold: true, color: { argb: API_DETAIL_HEADER_FONT }, name: ARIAL_FONT };
+    cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: API_DETAIL_HEADER_FILL } };
+    cell.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
+    applyBorder(cell);
+  });
+
+  ws.views = [{ state: 'frozen', ySplit: 1 }];
+
+  for (const r of detailRows) {
+    const row = ws.addRow([
+      r.endpoint,
+      r.method,
+      r.authDatasource,
+      r.requestShape,
+      r.expectedStatusMatrix,
+      r.flowSteps,
+      r.concurrencyInvariant,
+    ]);
+    row.alignment = { vertical: 'top', wrapText: true };
+    row.eachCell({ includeEmpty: true }, (cell) => {
+      applyBorder(cell);
+      cell.font = { name: ARIAL_FONT };
+    });
+  }
+
+  ws.autoFilter = {
+    from: { row: 1, column: 1 },
+    to: { row: ws.rowCount, column: 7 },
+  };
+}
+
 /**
  * Write the workbook to `qa/deliverables/<screen>-testcases[.env].xlsx`.
  * When `SUNGEN_ENV` is set, the env name is appended so locale exports don't

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

@@ -0,0 +1,57 @@
+import path from 'path';
+import { TestGeneratorAdapter, TestFileData, ScenarioData } from '../adapter-interface';
+import { TemplateEngine } from '../../template-engine';
+
+/**
+ * AppiumAdapter
+ * Generates WebdriverIO + Appium (Mocha) test code using Handlebars templates.
+ *
+ * Mirrors PlaywrightAdapter: the adapter only renders the file skeleton (imports,
+ * describe/it, before/after hooks). Per-step code is produced by StepMapper +
+ * PatternRegistry driving this adapter's templates/ directory — the templates here
+ * carry the same names the patterns request (click-action, fill-action,
+ * visible-assertion, the `locator` partial, …) but emit WebdriverIO instead of Playwright.
+ */
+export class AppiumAdapter implements TestGeneratorAdapter {
+  readonly frameworkName = 'appium';
+  readonly fileExtension = '.spec.ts';
+  readonly templatesDir: string;
+  private templateEngine: TemplateEngine;
+
+  constructor() {
+    this.templatesDir = path.join(__dirname, 'templates');
+    this.templateEngine = new TemplateEngine(this.templatesDir);
+  }
+
+  renderTestFile(data: TestFileData): string {
+    return this.templateEngine.renderTestFile(data);
+  }
+
+  renderScenario(data: ScenarioData): string {
+    return this.templateEngine.renderScenario(data);
+  }
+
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean; needsDb?: boolean; needsApi?: boolean }): string {
+    return this.templateEngine.renderImports(options);
+  }
+
+  renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderBeforeEach(data);
+  }
+
+  renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderBeforeAll(data);
+  }
+
+  renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderAfterEach(data);
+  }
+
+  renderAfterAll(data: { steps: Array<{ comment?: string; code: string }> }): string {
+    return this.templateEngine.renderAfterAll(data);
+  }
+
+  renderStep(templateName: string, data: any): string {
+    return this.templateEngine.renderStep(templateName, data);
+  }
+}

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

@@ -0,0 +1,8 @@
+  after(async () => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

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

@@ -0,0 +1,8 @@
+  afterEach(async () => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

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

@@ -0,0 +1,8 @@
+  before(async () => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

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

@@ -0,0 +1,8 @@
+  beforeEach(async () => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

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

@@ -0,0 +1,8 @@
+import { $, $$, expect, driver, browser } from '@wdio/globals';
+{{#if runtimeData}}
+import { TestDataLoader } from '{{basePath}}/test-data';
+{{/if}}
+
+// This file is auto-generated from Gherkin feature files
+// DO NOT EDIT MANUALLY - changes will be overwritten
+// To modify tests, edit the corresponding .feature file and regenerate

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

@@ -0,0 +1,8 @@
+  it('{{scenarioName}}', async () => {
+{{#each steps}}
+{{#if comment}}
+    // {{comment}}
+{{/if}}
+{{code}}
+{{/each}}
+  });

package/src/generators/test-generator/adapters/appium/templates/steps/actions/alert-accept-action.hbs

@@ -0,0 +1,4 @@
+{{!-- Accept a native alert. Unlike web (handler set before the trigger), mobile alerts are handled
+      AFTER they appear; for launch-time permission dialogs prefer the `appium:autoAcceptAlerts` cap.
+      Best-effort: ignore if no alert is present. --}}
+try { await driver.acceptAlert(); } catch { /* no native alert present */ }

package/src/generators/test-generator/adapters/appium/templates/steps/actions/alert-dismiss-action.hbs

@@ -0,0 +1,2 @@
+{{!-- Dismiss a native alert (best-effort; ignore if none present). --}}
+try { await driver.dismissAlert(); } catch { /* no native alert present */ }

package/src/generators/test-generator/adapters/appium/templates/steps/actions/alert-fill-action.hbs

@@ -0,0 +1,2 @@
+{{!-- Filling a native prompt is iOS-specific and app-dependent; Android rarely has fillable alerts.
+      Requested value: '{{fillValue}}'. Handle manually if your alert has a text field. --}}

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

@@ -0,0 +1,10 @@
+{{!-- WebdriverIO/Appium has no .check(). Read the current state and tap only if it's not already
+      on, so the step is idempotent (re-running a passing test won't flip it back off). Falls through
+      to a plain tap if the state can't be read. --}}
+{
+  const __cb = await {{> locator}};
+  let __on = false;
+  try { __on = await __cb.isSelected(); }
+  catch { try { __on = (await __cb.getAttribute('checked')) === 'true'; } catch { /* state unreadable — tap anyway */ } }
+  if (!__on) await __cb.click();
+}

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

@@ -0,0 +1 @@
+await {{> locator}}.clearValue();

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

@@ -0,0 +1 @@
+await {{> locator}}.click();

package/src/generators/test-generator/adapters/appium/templates/steps/actions/click-element-with-text.hbs

@@ -0,0 +1,2 @@
+{{!-- Tap an element by its visible text / content-desc (dynamic text match). --}}
+{{#if nth}}await $$('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]')[{{nth}}].click();{{else}}await $('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]').click();{{/if}}

package/src/generators/test-generator/adapters/appium/templates/steps/actions/click-select-action.hbs

@@ -0,0 +1,4 @@
+{{!-- Custom (non-native) select: open the control, then tap the option by accessibility-id /
+      content-desc (= the option value). Same two-tap shape as select-action on mobile. --}}
+await {{> locator}}.click();
+await $('~{{escapeQuotes selectValue}}').click();

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

@@ -0,0 +1,3 @@
+// Best-effort dismiss (launch interstitial / promo / ad): tap if it shows within a short grace,
+// otherwise skip — never fails the step.
+try { const __d = await {{> locator}}; if (await __d.waitForDisplayed({ timeout: 2500 }).then(() => true).catch(() => false)) await __d.click(); } catch { /* not present — skip */ }

package/src/generators/test-generator/adapters/appium/templates/steps/actions/double-click-action.hbs

@@ -0,0 +1,6 @@
+{{!-- Double-tap. Use the platform gesture (element.doubleClick is web-oriented). --}}
+{
+  const __el = await {{> locator}};
+  if (driver.isIOS) await driver.execute('mobile: doubleTap', { elementId: __el.elementId });
+  else await driver.execute('mobile: doubleClickGesture', { elementId: __el.elementId });
+}

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

@@ -0,0 +1,2 @@
+{{!-- Drag the source element onto the target. WebdriverIO dragAndDrop drives W3C touch actions. --}}
+await (await {{> locator}}).dragAndDrop(await $('{{#switch targetStrategy}}{{#case 'accessibility-id'}}~{{escapeQuotes targetValue}}{{/case}}{{#case 'testid'}}~{{escapeQuotes targetValue}}{{/case}}{{#case 'xpath'}}{{escapeQuotes targetValue}}{{/case}}{{#case 'android-uiautomator'}}android={{escapeQuotes targetValue}}{{/case}}{{#case 'id'}}id={{escapeQuotes targetValue}}{{/case}}{{#default}}~{{#if targetValue}}{{escapeQuotes targetValue}}{{else}}{{escapeQuotes targetName}}{{/if}}{{/default}}{{/switch}}'));

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

@@ -0,0 +1,2 @@
+{{!-- Mobile has no aria-expanded to verify; expanding/collapsing a row or accordion is just a tap. --}}
+await {{> locator}}.click();

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

@@ -0,0 +1,14 @@
+{{!-- Robust mobile fill: Flutter often ignores a bare setValue (the field never registers, so a
+      dependent submit button stays disabled). Explicitly focus, clear, setValue, then if the field
+      still reads empty, retype with addValue. Best-effort read-back never fails the step. --}}
+{
+  const __fill = await {{> locator}};
+  await __fill.click();
+  try { await __fill.clearValue(); } catch { /* not clearable */ }
+  await __fill.setValue('{{escapeQuotes fillValue}}');
+  try {
+    const __got = (await __fill.getText()) || (await __fill.getAttribute('text')) || '';
+    const __masked = /[•●*]/.test(__got);
+    if (!__masked && __got.trim() === '') await __fill.addValue('{{escapeQuotes fillValue}}');
+  } catch { /* read-back unsupported — trust setValue */ }
+}

package/src/generators/test-generator/adapters/appium/templates/steps/actions/fill-editor-action.hbs

@@ -0,0 +1,12 @@
+{{!-- Rich-text/contenteditable editors don't exist as such on native mobile — treat as a normal field
+      with the robust fill (focus, clear, setValue, read-back, retry). --}}
+{
+  const __fill = await {{> locator}};
+  await __fill.click();
+  try { await __fill.clearValue(); } catch { /* not clearable */ }
+  await __fill.setValue('{{escapeQuotes fillValue}}');
+  try {
+    const __got = (await __fill.getText()) || (await __fill.getAttribute('text')) || '';
+    if (!/[•●*]/.test(__got) && __got.trim() === '') await __fill.addValue('{{escapeQuotes fillValue}}');
+  } catch { /* read-back unsupported — trust setValue */ }
+}

package/src/generators/test-generator/adapters/appium/templates/steps/actions/frame-enter-action.hbs

@@ -0,0 +1,6 @@
+{{!-- Hybrid app: switch into the webview context (mobile equivalent of entering an iframe). --}}
+{
+  const __ctxs = await driver.getContexts();
+  const __web = __ctxs.find(c => /WEBVIEW|CHROMIUM/i.test(typeof c === 'string' ? c : c.id));
+  if (__web) await driver.switchContext(typeof __web === 'string' ? __web : __web.id);
+}

package/src/generators/test-generator/adapters/appium/templates/steps/actions/frame-exit-action.hbs

@@ -0,0 +1,2 @@
+{{!-- Back to the native context. --}}
+await driver.switchContext('NATIVE_APP');

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

@@ -0,0 +1,4 @@
+// Hide the soft keyboard (best-effort — never fails if no keyboard is shown).
+// iOS XCUITest cannot dismiss the keyboard generically (WDA throws + retries, ~12s wasted),
+// and XCUITest taps/asserts work with the keyboard up — so the dismiss is Android-only.
+try { if (!driver.isIOS && await driver.isKeyboardShown()) await driver.hideKeyboard(); } catch { /* no keyboard / not supported */ }

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

@@ -0,0 +1,2 @@
+{{!-- No hover on touch devices — no-op. (Hover-revealed content is normally already visible on mobile;
+      if a tap is actually required, use `User tap [X]` instead.) --}}

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

@@ -0,0 +1,2 @@
+{{!-- 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}}

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

@@ -0,0 +1,4 @@
+{{!-- Press a key on a field (e.g. Enter after filling a search box). Focus the field, then send the
+      W3C key event — UiAutomator2/XCUITest translate it to a real key press. --}}
+await {{> locator}}.click();
+await driver.keys('{{key}}');

package/src/generators/test-generator/adapters/appium/templates/steps/actions/radio-select-action.hbs

@@ -0,0 +1,4 @@
+{{!-- Mobile radios have no ARIA "radio" role to query by name, so tap the option by its
+      accessibility-id / content-desc (= the option value). If the visible label differs from the
+      element's accessibility-id, add an explicit selector for the option and reference it instead. --}}
+await $('~{{escapeQuotes selectValue}}').click();

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

@@ -0,0 +1,19 @@
+if (driver.isIOS) {
+  // iOS (XCUITest) has no UiScrollable. Swipe the screen up in bounded steps until the target is on
+  // screen (a below-fold element isn't in the XCUITest tree until scrolled, so getElementRect/tap on
+  // it would otherwise fail). Bounded so a missing target can't loop forever.
+  const __t = $({{> appium-selector-expr}});
+  for (let __i = 0; __i < 12 && !(await __t.isDisplayed().catch(() => false)); __i++) {
+    await driver.execute('mobile: swipe', { direction: 'up' });
+  }
+} else {
+{{#if (eq strategy 'accessibility-id')}}
+  // Android UiScrollable scrolls until the target's content-desc is on screen, then stops — no
+  // overshoot (which would drop a virtualized Flutter item from the a11y tree). Robust on Flutter/RN.
+  await $('android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().descriptionContains("{{escapeQuotes value}}"))');
+{{else}}
+  // Generic fallback: framework-agnostic moderate scroll gesture (wdio .scrollIntoView() can't always
+  // find a native ScrollView on Flutter/RN). Modest percent avoids over-scrolling a virtualized list.
+  await driver.execute('mobile: scrollGesture', { left: 60, top: 420, width: 960, height: 1320, direction: 'down', percent: 0.6 });
+{{/if}}
+}

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

@@ -0,0 +1,5 @@
+{{!-- Native dropdown/picker: open the control, then tap the option by accessibility-id /
+      content-desc (= the option value). Two taps because there is no native <select>.selectOption
+      on mobile. If the option's accessibility-id differs from its label, add an explicit selector. --}}
+await {{> locator}}.click();
+await $('~{{escapeQuotes selectValue}}').click();

package/src/generators/test-generator/adapters/appium/templates/steps/actions/table-action-in-row.hbs

@@ -0,0 +1,2 @@
+{{!-- Table row actions target HTML <table> roles — not available on native mobile. --}}
+throw new Error("[sungen] 'table action in row' targets HTML table roles and is not supported on the appium adapter. Use list / accessibility-id steps, or tag this scenario @manual.");

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

@@ -0,0 +1,3 @@
+{{!-- A switch/toggle flips state on tap (mirrors the web toggle pattern: unconditional click).
+      Use `check`/`uncheck` instead when you need to drive it to a specific on/off state idempotently. --}}
+await {{> locator}}.click();

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

@@ -0,0 +1,8 @@
+{{!-- WebdriverIO/Appium has no .uncheck(). Tap only if currently on, so the step is idempotent. --}}
+{
+  const __cb = await {{> locator}};
+  let __on = false;
+  try { __on = await __cb.isSelected(); }
+  catch { try { __on = (await __cb.getAttribute('checked')) === 'true'; } catch { /* state unreadable — leave as-is */ } }
+  if (__on) await __cb.click();
+}

package/src/generators/test-generator/adapters/appium/templates/steps/actions/unknown-element-action.hbs

@@ -0,0 +1,2 @@
+{{!-- Fallback for an unrecognized action: tap an element by text / content-desc. --}}
+await $('//*[contains(@content-desc,"{{escapeQuotes dataValue}}") or contains(@text,"{{escapeQuotes dataValue}}")]').click();

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

@@ -0,0 +1,3 @@
+{{!-- File upload is not auto-generatable on native mobile (no <input type=file>): it needs app-specific
+      handling (driver.pushFile + the app's own picker, or a deep link). Fail loud so it isn't a silent skip. --}}
+throw new Error("[sungen] upload step ('{{fileName}}') is not supported on the appium adapter — handle the file picker app-specifically (driver.pushFile + picker) or tag this scenario @manual.");

package/src/generators/test-generator/adapters/appium/templates/steps/actions/wait-for-page.hbs

@@ -0,0 +1,3 @@
+{{!-- No URL/page concept on mobile. Pause briefly to let the screen settle; prefer a screen-marker
+      assertion (`Then User see [X] ...`) over waiting for a "page". --}}
+await driver.pause(500);