@sun-asterisk/sungen 3.2.2-beta.11 → 3.2.2-beta.14

package/src/cli/commands/delivery.ts

@@ -21,6 +21,7 @@ import {
   writeCsv,
 } from '../../exporters/csv-exporter';
 import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
+import { resolvePlatformAppId } from '../../exporters/mobile-app-id';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
 
 const COLOR = {
@@ -394,6 +395,40 @@ function getEnvironment(cwd: string): EnvironmentInfo {
   return { baseURL, projectName, executor };
 }
 
+/**
+ * True when this is a mobile project (`platform: mobile` in qa/capabilities.yaml).
+ * Mobile results are written PER-OS (`<feature>-test-result.android|ios.json`) —
+ * android/ios are separate platform runs, not locales of one run — so delivery
+ * emits one csv+xlsx per OS and skips the (empty/misleading) base aggregate.
+ */
+function isMobileProject(cwd: string): boolean {
+  try {
+    const p = path.join(cwd, 'qa', 'capabilities.yaml');
+    if (!fs.existsSync(p)) return false;
+    const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as { platform?: string } | null;
+    return parsed?.platform === 'mobile';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove a stale base (no-suffix) deliverable pair for a feature. Used in mobile
+ * per-OS mode where the base `<feature>-testcases.{csv,xlsx}` is not produced —
+ * deletes leftovers from a previous (pre-per-OS) delivery so the folder only
+ * holds the per-OS files.
+ */
+function removeBaseDeliverables(cwd: string, featureBaseName: string): void {
+  const dir = path.join(cwd, 'qa', 'deliverables');
+  for (const ext of ['csv', 'xlsx']) {
+    const f = path.join(dir, `${featureBaseName}-testcases.${ext}`);
+    if (fs.existsSync(f)) {
+      fs.rmSync(f);
+      log(`  ${COLOR.gray}removed stale base deliverable ${path.relative(cwd, f)} (mobile → per-OS files)${COLOR.reset}`);
+    }
+  }
+}
+
 // ----------------------------------------------------------------------------
 // Per-screen export
 // ----------------------------------------------------------------------------
@@ -440,10 +475,15 @@ async function exportTarget(
     //                   one CSV per locale (CSV has no sheet concept).
     //     <2 variants → single-sheet XLSX with the canonical 'Testcases' sheet.
     if (explicitEnv) {
+      // Mobile: a stale base (no-suffix) pair from a pre-per-OS run is misleading
+      // sitting next to the env-suffixed file — drop it.
+      if (isMobileProject(cwd)) removeBaseDeliverables(cwd, target.featureBaseName);
       const rows = buildTestCaseRows({
         screen: label,
         featureName: feature.featureName,
-        featurePath,
+        // OS-precise env column: a mobile dual-id Path resolves to just the
+        // android package / ios bundle id for SUNGEN_ENV=android|ios.
+        featurePath: resolvePlatformAppId(featurePath, explicitEnv),
         merged,
         testData: loadTestData(testDataFile),
         results: resolveResultsPath(cwd, target) ? loadPlaywrightReport(resolveResultsPath(cwd, target)!) : null,
@@ -470,6 +510,50 @@ async function exportTarget(
     }
 
     const variants = discoverLocaleVariants(cwd, target);
+
+    // Mobile: emit ONE deliverable per OS (csv + xlsx), each from its own
+    // `<feature>-test-result.<os>.json`. Android/iOS are SEPARATE platform runs,
+    // not locales of one run, so a single aggregated base workbook is empty &
+    // misleading — produce per-OS files and skip the base (issue: per-OS delivery).
+    if (isMobileProject(cwd)) {
+      // OS runs = variants whose first dot-segment is android|ios (incl. env-suffixed
+      // android.staging / ios.ja). A bare locale variant is NOT an OS run and stays on
+      // the standard aggregation path below.
+      const osVariants = variants.filter((v) => !!v.resultsPath && /^(android|ios)(\.|$)/.test(v.locale));
+      if (osVariants.length > 0) {
+        removeBaseDeliverables(cwd, target.featureBaseName); // drop any stale no-suffix pair
+        let mobileSummary: ScreenSummary | null = null;
+        for (const variant of osVariants) {
+          const variantRows = buildTestCaseRows({
+            screen: label,
+            featureName: feature.featureName,
+            featurePath: resolvePlatformAppId(featurePath, variant.locale), // OS-precise app id
+            merged,
+            testData: loadTestData(testDataFile, variant.locale || null),
+            results: variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null,
+            env,
+            selectorKeyMap,
+          });
+          const csv = renderCsv(buildSummary(label, variantRows, ''), variantRows, specLink);
+          const csvPath = writeCsv(cwd, target.featureBaseName, csv, variant.locale);
+          const autoRows = variantRows.filter((r) => r.testcaseType !== 'Manual');
+          const manualRows = variantRows.filter((r) => r.testcaseType === 'Manual');
+          const wb = renderXlsxMultiSheet([
+            { sheetName: 'Auto', summary: buildSummary(label, autoRows, ''), rows: autoRows, specLink },
+            { sheetName: 'Manual', summary: buildSummary(label, manualRows, ''), rows: manualRows, specLink },
+          ]);
+          await writeXlsx(cwd, target.featureBaseName, wb, variant.locale);
+          const s = buildSummary(label, variantRows, path.relative(cwd, csvPath));
+          // Prefer the android line for the single summary-table row (deterministic);
+          // startsWith covers env-suffixed android.staging etc.
+          if (!mobileSummary || variant.locale.startsWith('android')) mobileSummary = s;
+        }
+        return mobileSummary;
+      }
+      // Mobile but no per-OS results yet → fall through to the base export below
+      // so the test CASES still deliver (execution columns empty/pending).
+    }
+
     let primarySummary: ScreenSummary | null = null;
     let primaryCsvPath = '';
     // XLSX is split by automation type: an "Auto" sheet (automatable TCs, results differ per
@@ -487,7 +571,10 @@ async function exportTarget(
       const variantRows = buildTestCaseRows({
         screen: label,
         featureName: feature.featureName,
-        featurePath,
+        // No-op for web (URL Path); for a mobile fall-through (a no-suffix result
+        // json) this collapses the dual-id to the android package so the combined
+        // dual-id never leaks into the env column.
+        featurePath: resolvePlatformAppId(featurePath, variant.locale),
         merged,
         testData: variantTestData,
         results: variantResults,

package/src/cli/commands/generate.ts

@@ -219,7 +219,8 @@ export function registerGenerateCommand(program: Command): void {
           for (const w of ddWarnings.slice(0, 20)) console.log(`   ${w.scenario ? w.scenario + ': ' : ''}${w.message}`);
         }
 
-        console.log(`Next step: npx playwright test --ui\n`);
+        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : 'npx playwright test --ui';
+        console.log(`Next step: ${nextStep}\n`);
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/cli/commands/init.ts

@@ -4,11 +4,46 @@ export function registerInitCommand(program: Command): void {
   program
     .command('init [projectName]')
     .description('Initialize Sungen project (optionally create and initialize in a new project folder)')
-    .requiredOption('--base-url <url>', 'Base URL for Playwright tests (e.g. https://your-app.com)')
-    .action(async (projectName: string | undefined, options: { baseUrl: string }) => {
+    .option('--base-url <url>', 'Base URL for Playwright (web) tests (e.g. https://your-app.com). Required for web projects (omit only with --mobile)')
+    .option('--mobile', 'Mobile project (Appium/WebdriverIO): scaffold ONLY the mobile harness — no Playwright config, no Chromium download, no --base-url needed')
+    .option('--app-package <pkg>', 'Android appPackage for mobile (e.g. com.example.app). Used with --mobile')
+    .option('--app-activity <activity>', 'Android appActivity for mobile (e.g. com.example.app.MainActivity). OPTIONAL — omit to let Appium auto-resolve the launcher activity from --app-package; pass it only to pin a non-standard launcher. Used with --mobile')
+    .option('--app-apk <path>', 'Path to an .apk to install & run for mobile (alternative to package/activity). Used with --mobile')
+    .option('--android-udid <udid>', 'Default Android device/emulator UDID for mobile (default: emulator-5554)')
+    .option('--ios-bundle-id <id>', 'iOS bundle id for mobile (e.g. com.example.app.dev) — default app when MOBILE_PLATFORM=ios|both. Used with --mobile')
+    .option('--ios-device <name>', "iOS Simulator device name for mobile (default: 'iPhone 16'). Used with --mobile")
+    .option('--ios-version <ver>', "iOS Simulator platform version for mobile (default: '18.0'). Used with --mobile")
+    .action(async (projectName: string | undefined, options: {
+      baseUrl?: string;
+      mobile?: boolean;
+      appPackage?: string;
+      appActivity?: string;
+      appApk?: string;
+      androidUdid?: string;
+      iosBundleId?: string;
+      iosDevice?: string;
+      iosVersion?: string;
+    }) => {
       try {
+        // `--mobile` = a mobile-only project: no web scaffolding, no base URL needed.
+        // Plain `init` = a web project and requires `--base-url`.
+        const mobile = !!options.mobile;
+        if (!mobile && !options.baseUrl) {
+          console.error('❌ --base-url is required for a web project. For a mobile project pass --mobile (no base URL needed).');
+          process.exit(1);
+        }
         const { ProjectInitializer } = require('../../orchestrator/project-initializer');
-        const initializer = new ProjectInitializer(options.baseUrl);
+        const initializer = new ProjectInitializer(options.baseUrl || '', {
+          enabled: mobile,
+          mobileOnly: mobile,
+          appPackage: options.appPackage,
+          appActivity: options.appActivity,
+          appApk: options.appApk,
+          androidUdid: options.androidUdid,
+          iosBundleId: options.iosBundleId,
+          iosDevice: options.iosDevice,
+          iosVersion: options.iosVersion,
+        });
         await initializer.initialize(projectName);
       } catch (error) {
         console.error('❌ Init failed:', error);

package/src/cli/commands/journey.ts

@@ -1,7 +1,7 @@
 import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
-import { runJourney, waive, signoff, renderJourneyBoard } from '../../harness/journey';
+import { runJourney, waive, signoff, renderJourneyBoard, rollupJourney, renderRollupBoard } from '../../harness/journey';
 import { reportSlug } from '../../harness/unit-paths';
 
 function findScreenDir(name: string): string | null {
@@ -19,6 +19,7 @@ export function registerJourneyCommand(program: Command): void {
     .command('journey')
     .description('Durable "you are here" board (#381): obligations + what-to-review + next, synthesised read-only from the audit report + ledger already on disk.')
     .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--all', 'Roll up every unit (screens + flows + api) into one board — the serial review surface for multi-unit fan-out')
     .option('--waive <obligation>', 'Waive an obligation (e.g. OB-coverage) — requires --reason')
     .option('--reason <text>', 'The reason a waived obligation is acceptable (mandatory with --waive)')
     .option('--signoff', 'Sign off the review queue — the single human gate (allowed only when every other obligation is satisfied/waived)')
@@ -26,8 +27,20 @@ export function registerJourneyCommand(program: Command): void {
     .option('--json', 'Output the raw JSON report')
     .action((options) => {
       try {
+        if (options.all) {
+          const rows = rollupJourney(process.cwd());
+          const board = renderRollupBoard(rows);
+          const outDir = path.join(process.cwd(), '.sungen', 'journey');
+          fs.mkdirSync(outDir, { recursive: true });
+          fs.writeFileSync(path.join(outDir, '_rollup.json'), JSON.stringify(rows, null, 2), 'utf-8');
+          fs.writeFileSync(path.join(outDir, '_rollup.board.md'), board, 'utf-8');
+          if (options.json) console.log(JSON.stringify(rows, null, 2));
+          else { console.log(''); console.log(board); console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, '_rollup.board.md'))}`); console.log(''); }
+          return;
+        }
+
         const name = options.screen;
-        if (!name) throw new Error('Provide --screen <name>');
+        if (!name) throw new Error('Provide --screen <name> (or --all for the roll-up)');
         if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const report = options.waive

package/src/dashboard/snapshot-builder.ts

@@ -22,6 +22,7 @@ import { loadSelectorKeyMap } from '../exporters/selector-key-resolver';
 import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
 import { mergeFeatureAndSpec } from '../exporters/scenario-merger';
 import { buildScreenSnapshot } from '../exporters/json-exporter';
+import { resolvePlatformAppId } from '../exporters/mobile-app-id';
 import { getPackageVersion } from '../exporters/package-info';
 import { EnvironmentInfo } from '../exporters/types';
 import {
@@ -167,6 +168,12 @@ function buildOneFeature(
   // Discover locale variants by scanning <feature>-test-result*.json files.
   // Always includes base ('') as the first entry, even if its results file
   // is missing — UI still needs to render the feature.
+  // NOTE (mobile): for a `platform: mobile` project the "locale" variants are
+  // actually the per-OS runs (android / ios) — the dashboard reuses the locale
+  // switcher to surface them as tabs. The env column per tab is OS-precise (see
+  // resolvePlatformAppId below), but the top-level featurePath (base variant)
+  // defaults to the Android id. Delivery has a dedicated per-OS path; aligning the
+  // dashboard onto a distinct "platform" axis is a possible follow-up.
   const variants = discoverLocaleVariants(genBase, featureBaseName);
 
   // Build per-locale ScreenSnapshot, then collect into FeatureSnapshot.locales[].
@@ -185,7 +192,9 @@ function buildOneFeature(
       screen: featureBaseName,
       isFlow: target.isFlow,
       featureName: feature.featureName,
-      featurePath,
+      // OS-precise env column: a mobile dual-id Path resolves to just the android
+      // package / ios bundle id for the android|ios result variant.
+      featurePath: resolvePlatformAppId(featurePath, variant.locale),
       specLink,
       merged,
       testData,

package/src/exporters/csv-exporter.ts

@@ -202,7 +202,9 @@ export function buildSummary(screen: string, rows: TestCaseRow[], outputFile: st
 function formatEnv(baseURL: string, featurePath: string | undefined, projectName: string): string {
   const base = (baseURL || '').replace(/\/+$/, '');
   const p = (featurePath || '').replace(/^\/+/, '');
-  const url = p ? `${base}/${p}` : base;
+  // Join with '/' only when there is a baseURL (web). For mobile baseURL is empty
+  // and `p` is an app id (e.g. com.kngroup.media.converter) — emit it bare, no '/'.
+  const url = base && p ? `${base}/${p}` : (p || base);
   return `${url} (${projectName})`;
 }
 

package/src/exporters/json-exporter.ts

@@ -165,7 +165,9 @@ export function buildScreenSnapshot(input: BuildScreenSnapshotInput): ScreenSnap
 function formatTestEnvironment(baseURL: string, featurePath: string | undefined, projectName: string): string {
   const base = (baseURL || '').replace(/\/+$/, '');
   const p = (featurePath || '').replace(/^\/+/, '');
-  const url = p ? `${base}/${p}` : base;
+  // Join with '/' only when there is a baseURL (web). For mobile baseURL is empty
+  // and `p` is an app id (e.g. com.kngroup.media.converter) — emit it bare, no '/'.
+  const url = base && p ? `${base}/${p}` : (p || base);
   return `${url} (${projectName})`;
 }
 

package/src/exporters/mobile-app-id.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolve the OS-specific app id from a feature `Path:` for the delivery /
+ * dashboard "Test Environment" column.
+ *
+ * Mobile features carry a DUAL-ID Path: `<androidPkg>[/<activity>] | <iosBundleId>`
+ * (e.g. `com.kngroup.media.converter | com.kngroup.media.converter.dev`). The
+ * deliverable's environment column must show ONLY the id for the OS the results
+ * came from — Android → the package (launch activity stripped), iOS → the bundle
+ * id — never the combined dual-id.
+ *
+ * Web features carry a URL Path (no `|`) and are returned unchanged.
+ *
+ * @param featurePath the feature `Path:` value (dual-id for mobile, URL for web)
+ * @param platform    the OS/result axis the row belongs to. The OS is the FIRST
+ *                     dot-segment, so env-suffixed result variants resolve too —
+ *                     `'ios'`, `'ios.staging'`, `'ios.ja'` all select the bundle id;
+ *                     anything else (`'android'`, `'android.staging'`, a bare locale,
+ *                     base) falls back to the Android package.
+ * @returns the resolved single id, or `featurePath` unchanged when it is not a dual-id.
+ */
+export function resolvePlatformAppId(
+  featurePath: string | undefined,
+  platform: string | undefined,
+): string | undefined {
+  if (!featurePath || !featurePath.includes('|')) return featurePath;
+  const [androidPart = '', iosPart = ''] = featurePath.split('|').map((s) => s.trim());
+  const androidId = androidPart.split('/')[0].trim(); // package only (drop /MainActivity)
+  const iosId = iosPart.trim();
+  // OS = first dot-segment so `ios.staging` / `ios.ja` (env-suffixed result files
+  // <name>-test-result.<os>[.<env>].json) still resolve to the iOS bundle id.
+  const os = (platform || '').toLowerCase().split('.')[0];
+  if (os === 'ios') return iosId || androidId;
+  return androidId || iosId;
+}

package/src/exporters/spec-parser.ts

@@ -25,7 +25,9 @@ function extractTestBlock(content: string, startIdx: number): {
   // The options object uses `\{.*?\}` (non-greedy, not `[^}]*`) so a tag value containing a
   // `}` — e.g. `@query:q(p={{var}})` — doesn't truncate the match (issue #271). The header is
   // single-line, so `.*?` anchored on `}, async` is safe.
-  const testRegex = /test\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
+  // Accept both Playwright `test(...)` and mobile/Appium mocha `it(...)` (issue #391). The leading
+  // `\b` prevents `it(` from matching the tail of a larger word like `submit(` / `edit(`.
+  const testRegex = /\b(?:test|it)\s*\(\s*(['"`])((?:(?!\1).)+)\1\s*,\s*(?:\{.*?\}\s*,\s*)?async\s*\([^)]*\)\s*=>\s*\{/g;
   testRegex.lastIndex = startIdx;
   const match = testRegex.exec(content);
   if (!match) return null;
@@ -57,7 +59,9 @@ function extractTestBlock(content: string, startIdx: number): {
  */
 function extractDescribeBlocks(content: string): Array<{ name: string; bodyStart: number; bodyEnd: number }> {
   const result: Array<{ name: string; bodyStart: number; bodyEnd: number }> = [];
-  const regex = /test\.describe(?:\.serial)?\s*\(\s*['"]([^'"]+)['"]\s*,\s*\(\s*\)\s*=>\s*\{/g;
+  // Accept Playwright `test.describe(...)` / `test.describe.serial(...)` AND mobile/Appium mocha
+  // `describe(...)` (issue #391). The optional `test.` prefix keeps web specs matching unchanged.
+  const regex = /(?:test\.)?describe(?:\.serial)?\s*\(\s*['"]([^'"]+)['"]\s*,\s*\(\s*\)\s*=>\s*\{/g;
   let match: RegExpExecArray | null;
   while ((match = regex.exec(content)) !== null) {
     const name = match[1];

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

@@ -23,11 +23,14 @@ export interface TestFileData {
   featureFileName?: string; // Feature file name for TestDataLoader.load()
   isParallel?: boolean; // @parallel tag: fresh page per test (opt-out from serial default)
   flowMode?: boolean;   // flow: cross-screen → longer per-test timeout (bug #243)
+  platform?: string;    // mobile @platform:* value (mobile|android|ios) → `// sungen:platform=` marker for wdio per-OS routing
   cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
   backgroundSteps?: Array<{ comment?: string; code: string }>; // Raw background steps for serial beforeAll
   scenarios: string[];
   authGroups?: AuthGroup[]; // Grouped by auth role for nested describes
   singleAuthRole?: string;  // Auth role when all scenarios share the same role
+  appPackage?: string;      // Mobile (appium): Android package from the feature `Path:` → drives the per-scenario relaunch reset (beforeEach terminate+activate)
+  iosBundleId?: string;     // Mobile (appium): iOS bundle id from a dual-id `Path: <pkg>/<activity> | <bundleId>`
 }
 
 export interface ScenarioData {

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

@@ -1,10 +1,13 @@
 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.
+  // 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 < 12 && !(await __t.isDisplayed().catch(() => false)); __i++) {
+  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)
   }
 } else {
 {{#if (eq strategy 'accessibility-id')}}

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

@@ -1,3 +1,20 @@
-{{!-- 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();
+{{!-- A switch/toggle flips state on tap. On Flutter (and many native layouts) the row's a11y node
+      spans the FULL width and merges the label with the switch, so a centre .click() lands on the
+      LABEL and does NOT flip the control — only the trailing visual switch toggles. So tap the
+      RIGHT portion (vertical centre) via getElementRect (W3C-standard → Android + iOS). Falls back to
+      a plain centre click when the rect is unavailable. Use `check`/`uncheck` to drive a specific
+      on/off state idempotently instead. --}}
+await (async () => {
+  const e = await {{> locator}};
+  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
+    // 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 e.click();
+  }
+})();

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

@@ -1 +1,4 @@
-await expect({{> locator}}).toBeSelected();
+// Mobile toggle state lives in the `checked` attribute (Android) or `value` "1"/"0" (iOS) — NOT
+// `selected` (what toBeSelected() reads; always false for a Flutter Switch). The composite row node
+// carries it, so the row selector resolves the state directly.
+await expect({{> locator}}).toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');

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

@@ -1 +1,4 @@
-await expect({{> locator}}).not.toBeSelected();
+// Mobile toggle state lives in the `checked` attribute (Android) or `value` "1"/"0" (iOS) — NOT
+// `selected` (what toBeSelected() reads; always false for a Flutter Switch). The composite row node
+// carries it, so the row selector resolves the state directly.
+await expect({{> locator}}).not.toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');

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

@@ -152,6 +152,9 @@ describe('{{featureName}}', () => {
     const __APP_PKG__ = __resolveAppId();
     try { await driver.terminateApp(__APP_PKG__); } catch { /* app may not be running yet */ }
     await driver.activateApp(__APP_PKG__);
+    // Restore portrait so a prior scenario's `rotate to landscape` can't leak into this one — the
+    // app relaunch above resets in-app state, but device orientation is OS-level and persists.
+    try { await driver.setOrientation('PORTRAIT'); } catch { /* orientation control not supported */ }
     // Settle after a cold (re)launch: a Flutter app first renders a BLANK accessibility skeleton
     // (nested FrameLayout/View, no content-desc) for several seconds before the real tree appears.
     // That skeleton is static, so a "two equal reads" check alone false-positives on it and we'd

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

@@ -173,8 +173,10 @@ function getEffectiveAuthRole(
  * @manual at scenario level → skip that scenario
  */
 function isManual(tags: string[]): boolean {
-  // @deferred:flow is owned by a flow → not automated on this screen, so it skips like @manual (H6).
-  return tags.some(tag => tag === '@manual' || tag === '@deferred:flow');
+  // Recognize bare `@manual` AND the reason-coded `@manual:Mx` convention (what create-test emits) —
+  // must match harness/parse.ts + capability-plan.ts, else an `@manual:Mx` scenario is wrongly
+  // GENERATED (and run) instead of skipped. @deferred:flow is owned by a flow → also skips here (H6).
+  return tags.some(tag => /^@manual\b/i.test(tag) || tag === '@deferred:flow');
 }
 
 /**
@@ -487,7 +489,15 @@ export class CodeGenerator {
     let background: string | undefined;
     let backgroundSteps: Array<{ comment?: string; code: string }> | undefined;
     if (feature.background) {
-      if (isParallel) {
+      // Mobile (appium) ALWAYS inlines Background via `backgroundSteps`: the test-file template emits a
+      // relaunch-per-scenario beforeEach and renders Background INSIDE it (it has no separate `background`
+      // beforeEach slot), and that per-scenario relaunch already gives @parallel its reset semantics.
+      // Routing a @parallel *mobile* feature to generateBeforeEach() computes the nav steps into
+      // `background`, which the mobile template then ignores → the Background nav (e.g. `tap [Settings]
+      // tab`) is silently dropped and every scenario runs on the launcher. So branch on isParallel only
+      // for web; for appium always use generateBackgroundSteps().
+      const isMobile = this.adapter.frameworkName === 'appium';
+      if (isParallel && !isMobile) {
         background = await this.generateBeforeEach(feature.background);
       } else {
         backgroundSteps = await this.generateBackgroundSteps(feature.background);
@@ -597,6 +607,29 @@ export class CodeGenerator {
     const cleanup = extractCleanupFlags(feature.tags || []);
     const screenshotOnFailure = hasScreenshotOnFailure(feature.tags || []);
 
+    // Mobile: the @platform:* value (mobile|android|ios). Emitted as a `// sungen:platform=` marker
+    // so wdio.conf routes the spec per OS — android/ios = that OS only, mobile (default) = both.
+    // Only the appium adapter consumes it; web features have no @platform tag → undefined → no marker.
+    const platform = this.adapter.frameworkName === 'appium'
+      ? (feature.tags || []).find(t => t.startsWith('@platform:'))?.split(':')[1]
+      : undefined;
+
+    // Mobile: parse the feature `Path:` (the app entry) into the app id(s) the per-scenario relaunch
+    // reset needs. Dual-id form: `<androidPkg>[/<activity>] | <iosBundleId>` — appPackage is the Android
+    // package (activity stripped, it isn't needed for terminateApp/activateApp); iosBundleId is the part
+    // after `|` when present. Without these the test-file template's `{{#if appPackage}}` stays false and
+    // the beforeEach (terminate+activate) reset is never emitted → nav scenarios cascade-fail.
+    let appPackage: string | undefined;
+    let iosBundleId: string | undefined;
+    if (this.adapter.frameworkName === 'appium' && feature.path) {
+      const [androidPart, iosPart] = feature.path.split('|').map(s => s.trim());
+      // Guard against a web-style URL Path (`/login`): only treat as a package when it isn't a route.
+      if (androidPart && !androidPart.startsWith('/')) {
+        appPackage = androidPart.split('/')[0].trim() || undefined;
+      }
+      if (iosPart) iosBundleId = iosPart;
+    }
+
     // Use adapter to render the complete test file structure
     return this.adapter.renderTestFile({
       imports: '', // Not used in template as it's rendered separately
@@ -613,11 +646,14 @@ export class CodeGenerator {
       featureFileName: featureName,
       isParallel,
       flowMode: isFlowFeature,
+      platform,
       cleanup,
       backgroundSteps,
       scenarios: needsGrouping ? [] : scenarios,
       authGroups: needsGrouping ? authGroups : undefined,
       singleAuthRole,
+      appPackage,
+      iosBundleId,
     });
   }
 

package/src/generators/test-generator/template-engine.ts

@@ -21,9 +21,19 @@ export class TemplateEngine {
       return text.split('\n').map(line => indentation + line).join('\n');
     });
 
+    // Escape a raw string for embedding inside a single-quoted JS string literal. Every caller wraps
+    // the result in '…' (selector values, attribute values, scope), so a value containing a newline,
+    // backslash, or quote must be escaped or the generated spec is a syntax error (e.g. a Flutter
+    // composite content-desc like "Quick Convert\nSelect File\n…" used as an accessibility-id).
+    // Order matters: backslash first, then the rest.
     Handlebars.registerHelper('escapeQuotes', function(text: string) {
       if (text == null) return '';
-      return String(text).replace(/'/g, "\\'");
+      return String(text)
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
     });
 
     Handlebars.registerHelper('escapeRegex', function(text: string) {
@@ -259,11 +269,14 @@ export class TemplateEngine {
     screenName?: string;
     featureFileName?: string;
     isParallel?: boolean;
+    platform?: string;
     cleanup?: { overlay?: boolean; forms?: boolean; scroll?: boolean; storage?: boolean };
     backgroundSteps?: Array<{ comment?: string; code: string }>;
     scenarios: string[];
     authGroups?: Array<{ authRole?: string; scenarios: string[] }>;
     singleAuthRole?: string;
+    appPackage?: string;
+    iosBundleId?: string;
   }): string {
     return this.render('test-file', data);
   }

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -20,6 +20,12 @@ interface SelectorEntry {
   scope?: string;         // Parent landmark aria-label to scope within (e.g., 'desktop navigation')
   match?: 'exact' | 'partial';  // For getByText matching (default: partial)
 
+  // === Mobile per-platform variant (issue #392) ===
+  // `android:`/`ios:` sub-selectors for one logical element whose locator differs per OS (composite
+  // content-desc, partial/dynamic text, native predicate). Each is a full SelectorEntry.
+  android?: SelectorEntry;
+  ios?: SelectorEntry;
+
   // === v2: Complex Elements ===
   variant?: 'native' | 'custom' | 'dragdrop';  // Dropdown/upload subtype
   trigger?: string;       // Visible button that triggers hidden file input
@@ -52,8 +58,17 @@ interface LegacySelectorFile {
 }
 
 export interface ResolvedSelector {
-  strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator';
+  // Web (Playwright) strategies + mobile (Appium) strategies. Mobile types pass through from
+  // selectors.yaml so the appium adapter's `appium-selector` switch can emit the right WDIO selector
+  // (`~` / raw xpath / `android=` / `-ios predicate string:` / `id=`). See issue #392.
+  strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator'
+    | 'accessibility-id' | 'xpath' | 'android-uiautomator' | 'ios-predicate';
   value: string;
+  // Mobile per-platform variant (`android:`/`ios:` in selectors.yaml). When set, the appium codegen
+  // emits a runtime `driver.isIOS ? '<ios>' : '<android>'` so one @platform:mobile spec resolves the
+  // right native selector per OS. Each side carries its own strategy+value (issue #392).
+  androidSelector?: { strategy: ResolvedSelector['strategy']; value: string; name?: string };
+  iosSelector?: { strategy: ResolvedSelector['strategy']; value: string; name?: string };
   role?: string;        // For role-based selectors (e.g., 'button', 'link')
   name?: string;        // For accessible name in role selectors
   locator?: string;     // CSS locator for fallback
@@ -472,6 +487,25 @@ export class SelectorResolver {
       return { ...resolved, ...v2Fields };
     };
 
+    // Mobile per-platform variant (issue #392): `{ android: {...}, ios: {...} }`. Resolve each side
+    // and emit androidSelector/iosSelector so the appium codegen renders `driver.isIOS ? ios : android`.
+    // The base strategy/value falls back to whichever side is present (a missing side falls back to it).
+    // `nth`/`scope` are shared (top-level) — they cannot diverge per-OS (the codegen ternary swaps only
+    // strategy+value); a case needing per-OS nth/scope is a sub-feature, not a variant.
+    if (entry.android || entry.ios) {
+      const av = entry.android ? this.resolveFromEntry(entry.android, originalLabel) : undefined;
+      const iv = entry.ios ? this.resolveFromEntry(entry.ios, originalLabel) : undefined;
+      const base = (av || iv) as ResolvedSelector;
+      return withExtras({
+        strategy: base.strategy,
+        value: base.value,
+        name: base.name,
+        nth,
+        ...(av ? { androidSelector: { strategy: av.strategy, value: av.value, name: av.name } } : {}),
+        ...(iv ? { iosSelector: { strategy: iv.strategy, value: iv.value, name: iv.name } } : {}),
+      });
+    }
+
     // If type is 'locator', use locator field (or value as fallback) as the CSS locator directly
     if (type === 'locator') {
       const locatorValue = locator && locator.trim() ? locator : value;
@@ -536,6 +570,22 @@ export class SelectorResolver {
           exact,
         });
 
+      // Mobile (Appium) native strategies — pass through unchanged; the appium adapter's
+      // `appium-selector` switch renders the right WDIO selector (`~` / raw xpath / `android=` /
+      // `-ios predicate string:` / `id=`). On web these types never appear. See issue #392.
+      case 'accessibility-id':
+      case 'xpath':
+      case 'android-uiautomator':
+      case 'ios-predicate':
+      case 'id':
+        return withExtras({
+          strategy: type,
+          value,
+          name,
+          nth,
+          exact,
+        });
+
       default:
         // Fallback to placeholder
         return withExtras({