@sun-asterisk/sungen 3.2.3 → 3.2.5

package/src/exporters/scenario-merger.ts

@@ -9,7 +9,43 @@
  */
 
 import { FeatureMetadata, OrderedStep, ScenarioMetadata, SpecFileData, SpecTest } from './types';
-import { isStepsBaseScenario, isSampleScaffoldScenario } from './feature-parser';
+import { isStepsBaseScenario, isSampleScaffoldScenario, extractTestcaseType } from './feature-parser';
+
+/**
+ * Parse a @manual scenario's `# Tester verifies:` comment block into procedure vs
+ * expected. Each item is a numbered line, optionally prefixed with a label:
+ *   1. Setup: …   2. Action: …        → procedure (Steps column)
+ *   3. Observable: …  4. Oracle: …    → expected (Expected Results column)
+ * A label matching observ|oracle|expect|result|then|assert → Expected; anything else
+ * (Setup/Action/Precondition/unlabelled) → Steps. A non-numbered line following a
+ * numbered item is a continuation (e.g. a wrapped URL) and is appended to it. Pre-amble
+ * lines (the `MANUAL:` rationale, the `Tester verifies:` header, separators) are ignored.
+ */
+function parseManualComments(comments: string[]): { steps: OrderedStep[]; expected: OrderedStep[] } {
+  const steps: OrderedStep[] = [];
+  const expected: OrderedStep[] = [];
+  let last: OrderedStep | null = null;
+  const isExpectedLabel = (l: string) => /observ|oracle|expect|result|then|assert/i.test(l);
+  for (const raw of comments) {
+    const line = raw.trim();
+    if (!line) continue;
+    // Section divider — all divider chars (`-----`) OR a titled rule (`--- Foo ---`).
+    // A run of 2+ leading divider chars is never a step or a continuation.
+    if (/^[-=*_]{2,}/.test(line)) { last = null; continue; }
+    const m = line.match(/^\d+[.)]\s*(?:([A-Za-z][A-Za-z /]*?):\s*)?(.+)$/);
+    if (m) {
+      const label = (m[1] || '').trim();
+      const text = label ? `${label}: ${m[2].trim()}` : m[2].trim();
+      const step: OrderedStep = { text, bucket: isExpectedLabel(label) ? 'then' : 'when' };
+      (step.bucket === 'then' ? expected : steps).push(step);
+      last = step;
+    } else if (last) {
+      last.text += ' ' + line; // continuation of the previous numbered item
+    }
+    // else: pre-amble before any numbered item (rationale / header) → skip
+  }
+  return { steps, expected };
+}
 
 export interface MergedScenario {
   /** Scenario metadata from .feature */
@@ -76,6 +112,15 @@ export function mergeFeatureAndSpec(
     const ownPreThen = firstThenIdx >= 0 ? ownOrdered.slice(0, firstThenIdx) : ownOrdered;
     const ownPostThen = firstThenIdx >= 0 ? ownOrdered.slice(firstThenIdx) : [];
 
+    // A @manual scenario carries no Gherkin steps — its tester procedure lives in the
+    // `# Tester verifies:` comment block. Parse it into Steps (Setup/Action) + Expected
+    // (Observable/Oracle) so the delivery report shows the real manual procedure, not
+    // just the Background nav. No-op for automated scenarios (comments stay notes).
+    const manualParsed =
+      extractTestcaseType(scenario.tags) === 'Manual' && scenario.comments?.length
+        ? parseManualComments(scenario.comments)
+        : { steps: [] as OrderedStep[], expected: [] as OrderedStep[] };
+
     result.push({
       feature: scenario,
       spec: specTest,
@@ -98,8 +143,9 @@ export function mergeFeatureAndSpec(
         ...feature.backgroundOrderedSteps,
         ...(base?.orderedSteps ?? []),
         ...ownPreThen,
+        ...manualParsed.steps,
       ],
-      resolvedExpected: ownPostThen,
+      resolvedExpected: [...ownPostThen, ...manualParsed.expected],
     });
   }
 
@@ -116,7 +162,7 @@ function findMatchingSpecTest(scenario: ScenarioMetadata, tests: SpecTest[]): Sp
   if (exact) return exact;
 
   // Fallback: match by VP-ID prefix (ignore trailing text differences)
-  const vpMatch = scenario.name.match(/^(VP-[A-Z]+-\d+[a-zA-Z]?)/);
+  const vpMatch = scenario.name.match(/^(VP-[A-Z][A-Z0-9]*-\d+[a-zA-Z]?)/);
   if (vpMatch) {
     const vpId = vpMatch[1];
     const byVp = tests.find((t) => t.vpId === vpId);

package/src/exporters/spec-parser.ts

@@ -146,7 +146,7 @@ function classifyBlock(block: CodeBlock): 'precondition' | 'step' | 'expectation
  * Try to extract VP ID (e.g., VP-UI-001) from the start of a scenario title.
  */
 function extractVpId(title: string): string | undefined {
-  const match = title.match(/^(VP-[A-Z]+-\d+[a-zA-Z]?)\b/);
+  const match = title.match(/^(VP-[A-Z][A-Z0-9]*-\d+[a-zA-Z]?)\b/);
   return match ? match[1] : undefined;
 }
 

package/src/exporters/test-data-resolver.ts

@@ -133,6 +133,19 @@ function truncate(s: string, max: number): string {
   return s.substring(0, max - 1) + '…';
 }
 
+/**
+ * Resolve `{{var}}` test-data placeholders in a step / expected-result line to their concrete values,
+ * so the delivery report shows what QA actually verifies (e.g. `text contains {{app_version}}` →
+ * `text contains Version 1.0.0`). Dotted keys (`{{a.b}}`) are supported. A key absent from the
+ * test-data map (or resolving to empty) is left as the literal `{{var}}` — never blanked.
+ */
+export function substituteTestDataVars(text: string, testData: Record<string, string>): string {
+  return text.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (m, key: string) => {
+    const v = testData[key];
+    return v === undefined || v === null || v === '' ? m : String(v);
+  });
+}
+
 /**
  * Resolve the test-data file path for a given screen.
  */

package/src/exporters/types.ts

@@ -88,6 +88,12 @@ export interface ScenarioMetadata {
    * Use this when ordering matters — e.g. mid-scenario `Given` after `When`.
    */
   orderedSteps: OrderedStep[];
+  /**
+   * Comment lines inside the scenario body (leading `# ` stripped). For a @manual
+   * scenario the tester procedure lives here (as `# Tester verifies:` comments), not
+   * as Gherkin steps — the merger parses these into Steps/Expected for the report.
+   */
+  comments?: string[];
 }
 
 /**
@@ -164,5 +170,12 @@ export interface ApiCatalogEntry {
   description?: string;
   body?: unknown;
   params?: unknown;
+  /** Per-endpoint header templates (e.g. authorization: "Bearer :token"); `:param` tokens
+   *  bind at runtime from the same args as the body/path. */
+  headers?: Record<string, string>;
+  /** 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';
   expect?: { status?: number | string };
 }

package/src/exporters/xlsx-exporter.ts

@@ -30,6 +30,15 @@ const META_FILL = 'FFDCE6F1'; // soft blue for meta rows
 const CATEGORY_FILL = 'FFD9D2E9'; // same lavender for group dividers (Accessing / GUI / Function)
 const BORDER_COLOR = 'FFBFBFBF';
 
+// Shared masthead + table styling (BM-2-901-13 header band, summary band, Overview table).
+const TIMES = 'Times New Roman';
+const ARIAL_FONT = 'Arial';
+const BLACK = { argb: 'FF000000' };
+const WHITE = { argb: 'FFFFFFFF' };
+const LAVENDER = { argb: 'FFD9D2E9' };
+const thinBlack = { style: 'thin' as const, color: BLACK };
+const allBordersBlack = { top: thinBlack, left: thinBlack, bottom: thinBlack, right: thinBlack };
+
 type AnyCell = ExcelJS.Cell;
 type AnyRow = ExcelJS.Row;
 
@@ -96,6 +105,9 @@ export function renderXlsxMultiSheet(sheets: LocaleSheet[]): ExcelJS.Workbook {
   const wb = new ExcelJS.Workbook();
   wb.creator = 'sungen delivery';
   wb.created = new Date();
+  // Overview first — a per-sheet roll-up (Passed/Failed/Pending/N/A/Remain/Total)
+  // plus a grand-total row, so QA sees the whole picture before the detail sheets.
+  addOverviewSheet(wb, sheets);
   for (const s of sheets) {
     addTestcaseSheet(wb, s.sheetName, s.summary, s.rows, s.specLink);
   }
@@ -103,57 +115,23 @@ export function renderXlsxMultiSheet(sheets: LocaleSheet[]): ExcelJS.Workbook {
 }
 
 /**
- * Append one BM-2-901-13 testcase sheet to the given workbook. Sheet content
- * (layout, summary band, data rows, auto-filter, protection) is identical to
- * the single-sheet `renderXlsx` output — only the sheet name differs.
+ * Render the shared BM-2-901-13 masthead (rows 1-4) onto a worksheet:
+ * Sun* logo (A1:C3), TESTCASE title (D1:F3), No/Version/Issue-Date block
+ * (G1:H3), company line (A4:F4), ISO line (G4:H4). Every sheet in a delivery
+ * workbook — Overview, Auto, Manual — carries this same header band.
  */
-function addTestcaseSheet(
+function renderReportHeaderBand(
   wb: ExcelJS.Workbook,
-  sheetName: string,
-  summary: ScreenSummary,
-  rows: TestCaseRow[],
-  specLink: string,
+  ws: ExcelJS.Worksheet,
+  titleLabel: string,
 ): void {
-  const ws = wb.addWorksheet(sheetName, {
-    views: [{ state: 'frozen', ySplit: 0, xSplit: 0 }],
-  });
-
   const issueDate = (() => {
     const d = new Date();
     return `${String(d.getDate()).padStart(2, '0')}/${String(d.getMonth() + 1).padStart(2, '0')}/${d.getFullYear()}`;
   })();
 
-  // -- Column widths matching template_report.xlsx (Sample sheet) --
-  ws.columns = [
-    { width: 20 },    // A — TC ID (wider to fit long flow IDs like FLOW-KUDO-…)
-    { width: 12.5 },  // B — Screen/Function
-    { width: 15.38 }, // C — Big item
-    { width: 16.25 }, // D — Medium item
-    { width: 17 },    // E — Test Object
-    { width: 25.5 },  // F — Pre-condition
-    { width: 24.88 }, // G — Test Data
-    { width: 24.88 }, // H — Steps
-    { width: 41 },    // I — Expected results
-    { width: 12 },    // J — Priority
-    { width: 13.5 },  // K — Testcase type
-    { width: 15.88 }, // L — Test Result
-    { width: 13.5 },  // M — Executed Date
-    { width: 16.5 },  // N — Test Executor
-    { width: 23 },    // O — Test Environment
-    { width: 29 },    // P — Note
-  ];
-
-  // -- Top metadata band (rows 1-4) — 1:1 with template_report.xlsx --
-  const TIMES = 'Times New Roman';
-  const ARIAL_FONT = 'Arial';
-  const BLACK = { argb: 'FF000000' };
-  const WHITE = { argb: 'FFFFFFFF' };
-  const LAVENDER = { argb: 'FFD9D2E9' };
-  const thinBlack = { style: 'thin' as const, color: BLACK };
-  const allBordersBlack = { top: thinBlack, left: thinBlack, bottom: thinBlack, right: thinBlack };
-
-  // Ensure rows 1..8 exist before merging.
-  for (let r = 1; r <= 8; r++) ws.getRow(r);
+  // Ensure rows 1..4 exist before merging.
+  for (let r = 1; r <= 4; r++) ws.getRow(r);
 
   ws.mergeCells('A1:C3');
   ws.mergeCells('D1:F3');
@@ -174,10 +152,6 @@ function addTestcaseSheet(
       extension: 'png',
     });
     // Centre a fixed-size 90×51 logo inside A1:C3 using absolute EMU offsets.
-    // Col widths (A=20, B=12.5, C=15.38) → pixels via Excel's `w*7+5` rule:
-    //   A=145, B=92.5, C=112.66  ⇒  A1:C3 ≈ 350 px wide.
-    // Left padding for a 90-px image = (350−90)/2 ≈ 130 px = 1,237,500 EMU.
-    // 3 default rows × 20 px = 60 px; top padding ≈ 4.5 px ≈ 42,862 EMU.
     ws.addImage(imageId, {
       tl: { nativeCol: 0, nativeColOff: 1237500, nativeRow: 0, nativeRowOff: 42862 } as unknown as ExcelJS.Anchor,
       ext: { width: 90, height: 51 },
@@ -186,7 +160,6 @@ function addTestcaseSheet(
   } catch { /* logo is decorative — never block export */ }
 
   // D1 (TESTCASE title)
-  const titleLabel = `${summary.screen.toUpperCase()} TESTCASE`;
   const d1 = ws.getCell('D1');
   d1.value = titleLabel;
   d1.font = { bold: true, size: 18, name: TIMES };
@@ -227,6 +200,134 @@ function addTestcaseSheet(
   g4.font = { bold: true, size: 10, name: TIMES };
   g4.alignment = { horizontal: 'right', vertical: 'middle', wrapText: true };
   g4.border = allBordersBlack;
+}
+
+// ---------------------------------------------------------------------------
+// Overview sheet — the first tab in every multi-sheet delivery workbook.
+// Rolls up each testcase sheet's Passed/Failed/Pending/N/A/Remain/Total into
+// one summary table (+ a grand-total row) under the shared masthead. Reads
+// only each sheet's summary — never touches the detail sheets themselves.
+// ---------------------------------------------------------------------------
+
+/** Column headers for the Overview roll-up table (cols A..H). */
+const OVERVIEW_HEADERS = ['#', 'Sheet name', 'Passed', 'Failed', 'Pending', 'N/A', 'Remain', 'Total'];
+
+/**
+ * Prepend an "Overview" worksheet summarizing every sheet in `sheets`.
+ *
+ * `Remain = Total − Passed − N/A` (i.e. Failed + Pending) so the number
+ * reconciles with the "Remaining" cell in each detail sheet's summary band.
+ */
+function addOverviewSheet(wb: ExcelJS.Workbook, sheets: LocaleSheet[]): void {
+  const ws = wb.addWorksheet('Overview');
+
+  // Table starts at column B row 7 (A is a thin left margin). Widths keep the
+  // A..H masthead readable AND the count columns tidy.
+  ws.columns = [
+    { width: 4 },   // A — left margin
+    { width: 6 },   // B — #
+    { width: 26 },  // C — Sheet name
+    { width: 13 },  // D — Passed
+    { width: 13 },  // E — Failed
+    { width: 13 },  // F — Pending
+    { width: 13 },  // G — N/A
+    { width: 13 },  // H — Remain
+    { width: 13 },  // I — Total
+  ];
+
+  const titleScreen = sheets[0]?.summary.screen ?? '';
+  renderReportHeaderBand(wb, ws, `${titleScreen.toUpperCase()} TESTCASE`);
+
+  // Roll-up table: header on row 7, first column B (index 2).
+  const HEADER_ROW = 7;
+  const FIRST_COL = 2; // column B
+  const headerRow = ws.getRow(HEADER_ROW);
+  headerRow.height = 20;
+  OVERVIEW_HEADERS.forEach((label, i) => {
+    const c = headerRow.getCell(FIRST_COL + i);
+    c.value = label;
+    c.font = { bold: true, size: 10, color: BLACK, name: ARIAL_FONT };
+    c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
+    c.alignment = { horizontal: 'center', vertical: 'middle', wrapText: true };
+    c.border = allBordersBlack;
+  });
+
+  const totals = { passed: 0, failed: 0, pending: 0, na: 0, remain: 0, total: 0 };
+
+  const writeDataRow = (rowIdx: number, values: ExcelJS.CellValue[], isTotal: boolean): void => {
+    const row = ws.getRow(rowIdx);
+    values.forEach((v, i) => {
+      const c = row.getCell(FIRST_COL + i);
+      c.value = v;
+      c.font = { bold: isTotal, size: 10, color: BLACK, name: ARIAL_FONT };
+      // The '#' + 'Sheet name' columns read left; the counts centre like the band.
+      c.alignment = { horizontal: i <= 1 ? 'left' : 'center', vertical: 'middle' };
+      c.border = allBordersBlack;
+      if (isTotal) c.fill = { type: 'pattern', pattern: 'solid', fgColor: LAVENDER };
+    });
+  };
+
+  let rowIdx = HEADER_ROW + 1;
+  sheets.forEach((s, i) => {
+    const su = s.summary;
+    const remain = Math.max(0, su.total - su.passed - su.na);
+    writeDataRow(rowIdx, [i + 1, s.sheetName, su.passed, su.failed, su.pending, su.na, remain, su.total], false);
+    totals.passed += su.passed;
+    totals.failed += su.failed;
+    totals.pending += su.pending;
+    totals.na += su.na;
+    totals.remain += remain;
+    totals.total += su.total;
+    rowIdx += 1;
+  });
+
+  writeDataRow(
+    rowIdx,
+    ['', 'Total', totals.passed, totals.failed, totals.pending, totals.na, totals.remain, totals.total],
+    true,
+  );
+}
+
+/**
+ * Append one BM-2-901-13 testcase sheet to the given workbook. Sheet content
+ * (layout, summary band, data rows, auto-filter, protection) is identical to
+ * the single-sheet `renderXlsx` output — only the sheet name differs.
+ */
+function addTestcaseSheet(
+  wb: ExcelJS.Workbook,
+  sheetName: string,
+  summary: ScreenSummary,
+  rows: TestCaseRow[],
+  specLink: string,
+): void {
+  const ws = wb.addWorksheet(sheetName, {
+    views: [{ state: 'frozen', ySplit: 0, xSplit: 0 }],
+  });
+
+  // -- Column widths matching template_report.xlsx (Sample sheet) --
+  ws.columns = [
+    { width: 20 },    // A — TC ID (wider to fit long flow IDs like FLOW-KUDO-…)
+    { width: 12.5 },  // B — Screen/Function
+    { width: 15.38 }, // C — Big item
+    { width: 16.25 }, // D — Medium item
+    { width: 17 },    // E — Test Object
+    { width: 25.5 },  // F — Pre-condition
+    { width: 24.88 }, // G — Test Data
+    { width: 24.88 }, // H — Steps
+    { width: 41 },    // I — Expected results
+    { width: 12 },    // J — Priority
+    { width: 13.5 },  // K — Testcase type
+    { width: 15.88 }, // L — Test Result
+    { width: 13.5 },  // M — Executed Date
+    { width: 16.5 },  // N — Test Executor
+    { width: 23 },    // O — Test Environment
+    { width: 29 },    // P — Note
+  ];
+
+  // -- Top metadata band (rows 1-4) — shared BM-2-901-13 masthead --
+  renderReportHeaderBand(wb, ws, `${summary.screen.toUpperCase()} TESTCASE`);
+  // Materialize rows 5..8 so the summary band + row-9 spacer land at the right offsets.
+  for (let r = 5; r <= 8; r++) ws.getRow(r);
 
   // -- Row 5: spacer (height auto-fit). --
 
@@ -348,7 +449,12 @@ function addTestcaseSheet(
   const emittedGroups = new Set<string>();
 
   function emitGroup(groupName: string, groupRows: TestCaseRow[]): void {
-    const divider = ws.addRow(['', groupName]);
+    // Column A (TC ID) must stay TRULY blank on a divider — never write '' here. COUNTA counts
+    // empty-string cells, so an '' in A made the generated total (=COUNTA(A15:A…)) over-count by
+    // one per group divider when recalculated (e.g. in Google Sheets). Set only the group name in B;
+    // the lavender band still spans every column via the fill loop below (style only, no value).
+    const divider = ws.addRow([]);
+    divider.getCell(2).value = groupName;
     divider.getCell(2).font = { bold: true };
     divider.eachCell({ includeEmpty: false }, (cell) => {
       cell.fill = { type: 'pattern', pattern: 'solid', fgColor: { argb: CATEGORY_FILL } };

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

@@ -37,6 +37,13 @@ export interface ParsedScenario {
   stepsName?: string;   // set when scenario has @steps:<name> — marks it as a reusable block
   extendsName?: string; // set when scenario has @extend:<name> — merges base steps inline
   hookType?: 'beforeAll' | 'afterEach' | 'afterAll'; // set when scenario has @beforeAll/@afterEach/@afterAll
+  /**
+   * Comment lines inside the scenario body (between its `Scenario:` line and the next
+   * scenario), leading `# ` stripped. `@cucumber/gherkin` keeps comments in a separate
+   * top-level array; we range-attach them here so the exporter can surface a @manual
+   * scenario's `# Tester verifies:` procedure (its only "steps") in the delivery report.
+   */
+  comments?: string[];
 }
 
 export interface ParsedFeature {
@@ -82,17 +89,53 @@ export class GherkinParser {
     const pathMatch = description.match(/^\s*Path:\s*(.+)$/m);
     const path = pathMatch ? pathMatch[1].trim() : undefined;
 
+    const scenarios = this.parseScenarios(feature);
+    this.attachScenarioComments(gherkinDocument, feature, scenarios);
+
     return {
       name: feature.name,
       description,
       path,
       tags,
       background: this.parseBackground(feature),
-      scenarios: this.parseScenarios(feature),
+      scenarios,
       sourceFile: filePath,
     };
   }
 
+  /**
+   * Range-attach top-level Gherkin comments to the scenario whose body contains them.
+   * A comment belongs to scenario i when its line is after scenario i's `Scenario:` line
+   * and before scenario i+1's header (its first tag line, or its `Scenario:` line). The
+   * leading `# ` is stripped. Used to surface a @manual scenario's tester-procedure comments
+   * (its only "steps") in the delivery report.
+   */
+  private attachScenarioComments(
+    doc: Messages.GherkinDocument,
+    feature: Messages.Feature,
+    scenarios: ParsedScenario[]
+  ): void {
+    const comments = doc.comments || [];
+    if (!comments.length) return;
+    const scenChildren = feature.children
+      .filter((c) => c.scenario)
+      .map((c) => c.scenario!);
+    // Same filter/order as parseScenarios → indices line up with `scenarios`.
+    for (let i = 0; i < scenChildren.length && i < scenarios.length; i++) {
+      const startLine = scenChildren[i].location.line;
+      const next = scenChildren[i + 1];
+      let endLine = Number.POSITIVE_INFINITY;
+      if (next) {
+        const tagLines = (next.tags || []).map((t) => t.location.line);
+        endLine = Math.min(next.location.line, ...(tagLines.length ? tagLines : [next.location.line]));
+      }
+      const body = comments
+        .filter((cm) => cm.location.line > startLine && cm.location.line < endLine)
+        .map((cm) => cm.text.replace(/^\s*#\s?/, '').replace(/\s+$/, ''));
+      if (body.length) scenarios[i].comments = body;
+    }
+  }
+
   /**
    * Parse background steps
    */

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

@@ -1,10 +1,31 @@
-{{!-- 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. --}}
-{
+{{!-- WebdriverIO/Appium has no .check(). Ensure the toggle ends up ON: read the current state and
+      tap only if it's not already on, so the step is idempotent (re-running a passing test, or
+      running under `noReset` with unknown persisted state, won't flip it back off). State is read
+      the same way the checked/unchecked assertions read it — `checked` attribute on Android,
+      `value` attribute on iOS ('1' = on) — since that's what actually carries state on a Flutter
+      composite row; `isSelected()` is a fallback for widgets where it doesn't. The tap itself uses
+      the trailing-edge coordinate method (not a centre .click()): on a full-width composite row the
+      a11y node merges the label with the switch, so a centre tap lands on the label and doesn't
+      flip the control. --}}
+await (async () => {
   const __cb = await {{> locator}};
+  // Fail loud with the REAL cause when the element never resolved — getElementRect(undefined)
+  // otherwise throws a cryptic `Malformed type for "elementId"` that masks the not-found (#430).
+  if (!__cb.elementId) throw new Error((__cb as any).error?.message || `Element not found: ${__cb.selector}`);
   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();
-}
+  try { __on = driver.isIOS ? (await __cb.getAttribute('value')) === '1' : (await __cb.getAttribute('checked')) === 'true'; }
+  catch { try { __on = await __cb.isSelected(); } catch { /* state unreadable — tap anyway */ } }
+  if (__on) return;
+
+  const r = await driver.getElementRect(__cb.elementId);
+  if (r && r.width) {
+    // Trailing switch: ~right edge, vertical centre. The inset clears the label/track padding while
+    // staying on the switch even on a full-width composite row.
+    const x = Math.round(r.x + r.width - Math.max(48, r.width * 0.08));
+    const y = Math.round(r.y + r.height / 2);
+    if (driver.isIOS) { await driver.execute('mobile: tap', { x, y }); }
+    else { await driver.execute('mobile: clickGesture', { x, y }); }
+  } else {
+    await __cb.click();
+  }
+})();

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

@@ -1,22 +1,26 @@
 if (driver.isIOS) {
-  // iOS (XCUITest) has no UiScrollable. Swipe up in bounded steps until the target is on screen (a
-  // below-fold element isn't in the XCUITest tree until scrolled). A settle `pause` between swipes
-  // paces the loop so it doesn't flood `execute/sync` (rapid back-to-back swipes are a common source
-  // of flakiness; issue #394). Bounded (cap 10) so a missing target can't loop forever. NOTE: this
-  // does NOT fix an app that crashes mid-scroll on its own — that's an app-stability issue, not codegen.
-  const __t = $({{> appium-selector-expr}});
-  for (let __i = 0; __i < 10 && !(await __t.isDisplayed().catch(() => false)); __i++) {
-    await driver.execute('mobile: swipe', { direction: 'up' });
-    await driver.pause(400); // settle: let the app render between swipes (don't flood execute/sync)
-  }
+  // iOS (XCUITest) has no UiScrollable. Delegate to __ensureVisible: geometry-gated small drags
+  // (a below-fold Flutter element stays in the tree with a 0x0 rect and isDisplayed() is unreliable
+  // on XCUITest, so a full-screen-swipe loop gated on isDisplayed overshoots the target — it swiped
+  // clean past section headers on the converter Settings screen). NOTE: this does NOT fix an app
+  // that crashes mid-scroll on its own — that's an app-stability issue, not codegen (issue #394).
+  await __ensureVisible({{> appium-selector-expr}});
 } else {
+  const __t = $({{> appium-selector-expr}});
 {{#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 });
+  // Optional first try: 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). This
+  // no-ops (rather than throwing past callers) when the app exposes no `scrollable(true)` node —
+  // common on Flutter/Compose, where the scroll view isn't a native Android ScrollView — so it
+  // can't be relied on alone; the bounded loop below is what actually guarantees reachability.
+  await $('android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().descriptionContains("{{escapeQuotes value}}"))').catch(() => {}); // no scrollable node — fall through to the gesture loop
 {{/if}}
+  // Bounded scroll-gesture loop (mirrors the iOS branch above): a single 0.6-percent scroll can
+  // land a near item but not a deeper one below the fold, so keep scrolling down until the target
+  // is displayed. Capped (10) so a missing target can't loop forever; a short pause between scrolls
+  // lets a virtualized Flutter/RN list render before the next gesture.
+  for (let __i = 0; __i < 10 && !(await __t.isDisplayed().catch(() => false)); __i++) {
+    await driver.execute('mobile: scrollGesture', { left: 60, top: 420, width: 960, height: 1320, direction: 'down', percent: 0.6 });
+    await driver.pause(400); // settle: let the app render between scrolls (don't flood execute/sync)
+  }
 }

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

@@ -6,6 +6,9 @@
       on/off state idempotently instead. --}}
 await (async () => {
   const e = await {{> locator}};
+  // Fail loud with the REAL cause when the element never resolved — getElementRect(undefined)
+  // otherwise throws a cryptic `Malformed type for "elementId"` that masks the not-found (#430).
+  if (!e.elementId) throw new Error((e as any).error?.message || `Element not found: ${e.selector}`);
   const r = await driver.getElementRect(e.elementId);
   if (r && r.width) {
     // Trailing switch: ~right edge, vertical centre. The inset clears the label/track padding while

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

@@ -1,8 +1,28 @@
-{{!-- WebdriverIO/Appium has no .uncheck(). Tap only if currently on, so the step is idempotent. --}}
-{
+{{!-- WebdriverIO/Appium has no .uncheck(). Ensure the toggle ends up OFF: tap only if currently on,
+      so the step is idempotent under repeat runs / persisted `noReset` state. State read + tap
+      method mirror check-action.hbs (see there for why): platform-correct attribute read
+      (`checked`/`value`) with an isSelected() fallback, then a trailing-edge coordinate tap rather
+      than a centre .click() (a centre tap on a full-width composite row hits the label, not the
+      switch). --}}
+await (async () => {
   const __cb = await {{> locator}};
+  // Fail loud with the REAL cause when the element never resolved — getElementRect(undefined)
+  // otherwise throws a cryptic `Malformed type for "elementId"` that masks the not-found (#430).
+  if (!__cb.elementId) throw new Error((__cb as any).error?.message || `Element not found: ${__cb.selector}`);
   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();
-}
+  try { __on = driver.isIOS ? (await __cb.getAttribute('value')) === '1' : (await __cb.getAttribute('checked')) === 'true'; }
+  catch { try { __on = await __cb.isSelected(); } catch { /* state unreadable — leave as-is */ } }
+  if (!__on) return;
+
+  const r = await driver.getElementRect(__cb.elementId);
+  if (r && r.width) {
+    // Trailing switch: ~right edge, vertical centre. The inset clears the label/track padding while
+    // staying on the switch even on a full-width composite row.
+    const x = Math.round(r.x + r.width - Math.max(48, r.width * 0.08));
+    const y = Math.round(r.y + r.height / 2);
+    if (driver.isIOS) { await driver.execute('mobile: tap', { x, y }); }
+    else { await driver.execute('mobile: clickGesture', { x, y }); }
+  } else {
+    await __cb.click();
+  }
+})();

package/src/generators/test-generator/adapters/appium/templates/steps/assertions/is-hidden-assertion.hbs

@@ -1 +1,3 @@
-await expect({{> locator}}).not.toBeDisplayed();
+{{!-- plain=true: no scroll-into-view. An element asserted hidden is expected absent, so hunting for
+      it by scrolling is pointless and would strand later same-scenario steps that sit above. --}}
+await expect({{> locator plain=true}}).not.toBeDisplayed();

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

@@ -1 +1,15 @@
+{{!-- iOS: XCUITest's `visible` attribute false-negatives on real, on-screen elements (snapshot
+      artifact, amplified on Flutter) — the reliable oracle there is GEOMETRY (an off-screen
+      Flutter element keeps a 0x0 rect). Simple-case selectors route through __assertVisible
+      (scrolls into view, then asserts existence + a real on-screen rect on iOS; plain
+      toBeDisplayed on Android). Parent/scope/nth chains keep toBeDisplayed() — those are
+      container-scoped lookups the bare-selector helper can't express. --}}
+{{~#if parentLocator~}}
 await expect({{> locator}}).toBeDisplayed();
+{{~else if scope~}}
+await expect({{> locator}}).toBeDisplayed();
+{{~else if nth~}}
+await expect({{> locator}}).toBeDisplayed();
+{{~else~}}
+await __assertVisible({{> appium-selector-expr}});
+{{~/if}}

package/src/generators/test-generator/adapters/appium/templates/steps/gestures/tap-top-action.hbs

@@ -1,5 +1,8 @@
 await (async () => {
   const e = await {{> locator}};
+  // Fail loud with the REAL cause when the element never resolved — getElementRect(undefined)
+  // otherwise throws a cryptic `Malformed type for "elementId"` that masks the not-found (#430).
+  if (!e.elementId) throw new Error((e as any).error?.message || `Element not found: ${e.selector}`);
   // Visible-point tap: tap near the TOP of the element (its centre may sit under a floating bottom
   // bar). getElementRect is W3C-standard → works on BOTH Android and iOS (the old `bounds` attribute
   // is Android-only and throws on iOS).