@sun-asterisk/sungen 3.2.0-beta.141 → 3.2.0-beta.143

package/dist/orchestrator/templates/wdio.conf.ts

@@ -0,0 +1,295 @@
+/**
+ * WebdriverIO runner config for sungen mobile (Appium) tests.
+ * Mobile equivalent of playwright.config.ts. Run with: npm run test:mobile
+ *
+ * Capabilities default to the app configured at `sungen init --mobile`, but every value can be
+ * overridden at runtime via env vars — no need to edit this file to target another app/device:
+ *   APP_PACKAGE=com.other.app ANDROID_UDID=emulator-5556 npm run test:mobile
+ *   (the launch activity is auto-detected from APP_PACKAGE; set APP_ACTIVITY only to pin a non-standard one)
+ *   APP_APK=/path/to/app.apk npm run test:mobile     # install + run from an .apk (Appium derives pkg/activity)
+ *
+ * iOS Simulator (opt in with MOBILE_PLATFORM=ios; needs Xcode + the xcuitest driver):
+ *   MOBILE_PLATFORM=ios IOS_BUNDLE_ID=com.example.app npm run test:mobile          # app already installed on the sim
+ *   MOBILE_PLATFORM=ios IOS_APP=/path/MyApp.app npm run test:mobile                # Appium installs a Simulator build
+ *   (+ optional IOS_DEVICE='iPhone 16' IOS_VERSION='18.0' IOS_UDID=<sim-udid>)
+ *
+ * The @wdio/appium-service auto-starts a local Appium server (auto-detecting the uiautomator2 / xcuitest driver).
+ */
+/// <reference types="node" />
+/// <reference types="@wdio/globals/types" />
+// Load .env.appium (if present) into process.env FIRST — so every override below (ANDROID_HOME / JAVA_HOME /
+// ANDROID_UDID / APP_PACKAGE / IOS_BUNDLE_ID / MOBILE_PLATFORM / SUNGEN_ENV …) can come from a dedicated
+// .env.appium file instead of shell exports. A separate file (not the generic .env) keeps Appium config from
+// clashing with other .env vars (e.g. FIGMA_PAT). dotenv is a dependency; a missing .env.appium is a no-op.
+import dotenv from 'dotenv';
+dotenv.config({ path: '.env.appium' });
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import PwShapeReporter from './specs/reporters/pw-shape-reporter';
+
+/**
+ * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
+ *
+ * sungen emits one spec per feature; the test runner differs by platform:
+ *   - mobile/appium specs import from '@wdio/globals'  ← run these with wdio
+ *   - web/playwright specs import from '@playwright/test' ← run those with `playwright test`
+ * The '@wdio/globals' import is the machine-readable "platform = mobile" marker, so we keep
+ * only those files and never feed Playwright specs into the (incompatible) mocha runner.
+ *
+ * Each mobile spec also carries a `// sungen:platform=<mobile|android|ios>` marker (emitted from the
+ * feature's @platform:* tag). It routes the spec per OS:
+ *   - mobile  → cross-platform: runs on BOTH the Android and iOS capability sets
+ *   - android → Android cap only
+ *   - ios     → iOS cap only
+ * A spec with no marker (older codegen) defaults to `mobile` (runs on both) so nothing is dropped.
+ *
+ * Override with SUNGEN_SPECS=<glob-or-path> for a single spec (still classified by its marker).
+ */
+function readPlatformMarker(file: string): 'mobile' | 'android' | 'ios' {
+  try {
+    const m = /sungen:platform=(mobile|android|ios)/.exec(fs.readFileSync(file, 'utf-8'));
+    return (m?.[1] as 'mobile' | 'android' | 'ios') || 'mobile';
+  } catch {
+    return 'mobile';
+  }
+}
+function classifyMobileSpecs(root: string): Array<{ file: string; platform: string }> {
+  if (!fs.existsSync(root)) return [];
+  return (fs.readdirSync(root, { recursive: true }) as string[])
+    .filter((rel) => rel.endsWith('.spec.ts'))
+    .map((rel) => path.join(root, rel))
+    .filter((full) => {
+      try {
+        return fs.readFileSync(full, 'utf-8').includes('@wdio/globals');
+      } catch {
+        return false;
+      }
+    })
+    .map((file) => ({ file, platform: readPlatformMarker(file) }));
+}
+
+const specEntries = process.env.SUNGEN_SPECS
+  ? [process.env.SUNGEN_SPECS].map((file) => ({ file, platform: readPlatformMarker(file) }))
+  : classifyMobileSpecs(path.join(process.cwd(), 'specs', 'generated'));
+
+// Android cap runs android + mobile (everything except ios-only); iOS cap runs ios + mobile.
+const androidSpecs = specEntries.filter((e) => e.platform !== 'ios').map((e) => e.file);
+const iosSpecs = specEntries.filter((e) => e.platform !== 'android').map((e) => e.file);
+const mobileSpecs = specEntries.map((e) => e.file); // union — top-level fallback
+
+// App under test — env overrides the init-configured defaults.
+const APP_PACKAGE = process.env.APP_PACKAGE || '__APP_PACKAGE__';
+const APP_ACTIVITY = process.env.APP_ACTIVITY || '__APP_ACTIVITY__';
+const APP_APK = process.env.APP_APK; // optional: install + launch from an .apk file
+// appActivity is OPTIONAL: UiAutomator2 auto-resolves the package's launcher activity when it's
+// omitted, and the per-scenario relaunch uses activateApp(package) (no activity). So Android needs
+// only APP_PACKAGE — set APP_ACTIVITY only to pin a non-standard launcher. iOS has no activity
+// concept at all (bundleId only). Only pass the cap when APP_ACTIVITY is a real value (not the
+// unfilled scaffold placeholder / empty), so a package-only setup launches cleanly.
+const HAS_REAL_APP_ACTIVITY = !!APP_ACTIVITY && APP_ACTIVITY !== '__APP_ACTIVITY__';
+
+// ── iOS (Simulator) — opt in with MOBILE_PLATFORM=ios; every value is env-overridable ──────────
+//   MOBILE_PLATFORM=ios IOS_BUNDLE_ID=com.example.app npm run test:mobile
+//   - IOS_APP=/path/MyApp.app  → Appium installs a SIMULATOR build (.app or zipped .app) first.
+//                                (A device .ipa won't run on a Simulator — wrong binary/platform.)
+//   - IOS_BUNDLE_ID=com.x      → attach to an app already installed on the sim (simctl install first).
+//   - IOS_DEVICE / IOS_VERSION → pick the simulator; IOS_UDID targets a specific one.
+//
+// MOBILE_PLATFORM selects which capability set(s) run:
+//   android (default) → Android cap only        (runs @platform:android + @platform:mobile specs)
+//   ios               → iOS cap only            (runs @platform:ios + @platform:mobile specs)
+//   both              → BOTH caps in one run     (a @platform:mobile spec executes on each — write once, run both)
+const MOBILE_PLATFORM = (process.env.MOBILE_PLATFORM || 'android').toLowerCase();
+const RUN_ANDROID = MOBILE_PLATFORM === 'android' || MOBILE_PLATFORM === 'both';
+const RUN_IOS = MOBILE_PLATFORM === 'ios' || MOBILE_PLATFORM === 'both';
+const IOS_APP = process.env.IOS_APP;
+const IOS_BUNDLE_ID = process.env.IOS_BUNDLE_ID || '__IOS_BUNDLE_ID__';
+const IOS_DEVICE = process.env.IOS_DEVICE || '__IOS_DEVICE__';
+const IOS_VERSION = process.env.IOS_VERSION || '__IOS_VERSION__';
+// platformVersion is OPTIONAL on a real device: with IOS_UDID set, XCUITest reads the iOS version off
+// the connected device. Only pass the cap when IOS_VERSION is a real value (not the unfilled scaffold
+// placeholder). On a Simulator set it (or IOS_DEVICE) so Appium picks a matching runtime.
+const HAS_REAL_IOS_VERSION = !!IOS_VERSION && IOS_VERSION !== '__IOS_VERSION__';
+const IOS_UDID = process.env.IOS_UDID;
+// Real iPhone (device) — WebDriverAgent must be code-signed onto it. Set IOS_TEAM_ID (your Apple
+// Team ID) to switch the iOS cap into real-device mode; the Simulator ignores these (they're only
+// emitted when IOS_TEAM_ID is present, so Simulator runs are unchanged). For a real device also set
+// IOS_UDID (the device udid, NOT a sim) and the REAL IOS_BUNDLE_ID (Android package ≠ iOS bundle id).
+const IOS_TEAM_ID = process.env.IOS_TEAM_ID;                       // → appium:xcodeOrgId
+const IOS_SIGNING_ID = process.env.IOS_SIGNING_ID || 'Apple Development'; // → appium:xcodeSigningId
+const IOS_WDA_BUNDLE_ID = process.env.IOS_WDA_BUNDLE_ID || 'com.sungen.wda'; // → appium:updatedWDABundleId; default gives WDA a unique id (required for free teams) so you needn't set it
+
+// ── i18n (device locale) ────────────────────────────────────────────────────
+// SUNGEN_ENV doubles as the locale selector (the same var that swaps the test-data overlay).
+// When its value looks like a locale code ("vi", "ja", "vi-VN"), drive the DEVICE locale via
+// appium:language/appium:locale so an app that localizes from device locale on first launch picks
+// it up, and force a data reset (noReset:false) so that first-launch path actually re-runs (clears
+// any persisted in-app language override). Non-locale envs ("staging", "production") are left
+// untouched, so existing suites are unaffected. SUNGEN_LOCALE overrides explicitly when the device
+// locale must differ from the overlay name. Country defaults are used only when the code omits a region.
+const LOCALE_COUNTRY: Record<string, string> = {
+  vi: 'VN',
+  ja: 'JP',
+  en: 'US',
+  ko: 'KR',
+  zh: 'CN',
+  th: 'TH',
+  id: 'ID',
+  fr: 'FR',
+  de: 'DE',
+  es: 'ES',
+  pt: 'BR',
+  ru: 'RU',
+};
+function resolveLocaleCaps(): Record<string, unknown> {
+  const raw = process.env.SUNGEN_LOCALE || process.env.SUNGEN_ENV;
+  if (!raw) return {};
+  const m = /^([a-z]{2})(?:[-_]([A-Za-z]{2}))?$/.exec(raw.trim());
+  if (!m) return {}; // not a locale code (e.g. "staging") → don't touch the device locale
+  const language = m[1];
+  const country = (m[2] || LOCALE_COUNTRY[language] || language).toUpperCase();
+  return {
+    'appium:language': language,
+    'appium:locale': country,
+    'appium:noReset': false,
+  };
+}
+const localeCaps = resolveLocaleCaps();
+
+export const config: WebdriverIO.Config = {
+  runner: 'local',
+  tsConfigPath: './tsconfig.json',
+
+  specs: mobileSpecs,
+  // SUNGEN_MAX_INSTANCES=2 lets a MOBILE_PLATFORM=both run execute the Android and iOS capability
+  // in PARALLEL (separate devices; uiautomator2/XCUITest do not share ports; the reporter writes
+  // per-platform files so results cannot collide). Default stays 1 — serial is the safe choice on
+  // a laptop driving an emulator + a simulator at once.
+  maxInstances: Number(process.env.SUNGEN_MAX_INSTANCES || 1),
+
+  // Global auto-wait for $/$$ matchers (toBeDisplayed, click, …). Default is 3s, too short for a
+  // heavy app's cold (re)launch — each scenario terminates+activates its app, so the first
+  // find/click must wait out the splash/first-frame. 20s keeps slow native/Flutter apps green.
+  waitforTimeout: 20000,
+
+  // Capability set(s) selected by MOBILE_PLATFORM (android | ios | both). Each cap carries its OWN
+  // `specs` (per-OS routing): the Android cap runs android + mobile specs, the iOS cap runs ios +
+  // mobile specs, so MOBILE_PLATFORM=both executes a @platform:mobile spec on each in a single run.
+  // i18n localeCaps (appium:language/locale + noReset:false) apply to both when SUNGEN_ENV is a locale.
+  capabilities: [
+    ...(RUN_ANDROID
+      ? [
+          {
+            platformName: 'Android',
+            'appium:automationName': 'UiAutomator2',
+            'appium:udid': process.env.ANDROID_UDID || '__ANDROID_UDID__',
+            // APP_APK installs from a file (Appium reads pkg/activity from the manifest);
+            // otherwise target an already-installed app by package + activity.
+            ...(APP_APK
+              ? { 'appium:app': APP_APK }
+              : {
+                  'appium:appPackage': APP_PACKAGE,
+                  // Omit when unset → UiAutomator2 launches the package's default launcher activity.
+                  ...(HAS_REAL_APP_ACTIVITY ? { 'appium:appActivity': APP_ACTIVITY } : {}),
+                }),
+            'appium:noReset': true,
+            'appium:autoGrantPermissions': true,
+            'appium:newCommandTimeout': 300,
+            // i18n: when SUNGEN_ENV/SUNGEN_LOCALE is a locale code, this overrides noReset→false and
+            // adds appium:language/appium:locale so the app boots in that locale. Empty otherwise.
+            ...localeCaps,
+            // Per-capability spec routing (supported by WDIO at runtime; not in the TS cap type → cast).
+            specs: androidSpecs,
+          } as any,
+        ]
+      : []),
+    ...(RUN_IOS
+      ? [
+          {
+            platformName: 'iOS',
+            'appium:automationName': 'XCUITest',
+            'appium:deviceName': IOS_DEVICE,
+            // Omit when unknown (real device, no IOS_VERSION) → XCUITest reads it from the device by udid.
+            ...(HAS_REAL_IOS_VERSION ? { 'appium:platformVersion': IOS_VERSION } : {}),
+            // target a specific simulator if given (else Appium uses the matching device/version)
+            ...(IOS_UDID ? { 'appium:udid': IOS_UDID } : {}),
+            // IOS_APP installs a Simulator build (.app/.zip); otherwise attach to an installed bundleId.
+            ...(IOS_APP
+              ? { 'appium:app': IOS_APP }
+              : IOS_BUNDLE_ID
+                ? { 'appium:bundleId': IOS_BUNDLE_ID }
+                : {}),
+            // Real-device WDA signing — emitted only when IOS_TEAM_ID is set (Simulator: omitted → unchanged).
+            ...(IOS_TEAM_ID
+              ? {
+                  'appium:xcodeOrgId': IOS_TEAM_ID,
+                  'appium:xcodeSigningId': IOS_SIGNING_ID,
+                  // Pass -allowProvisioningUpdates -allowProvisioningDeviceRegistration to xcodebuild so it
+                  // auto-creates/refreshes the WDA profile + registers the device (needed for automatic
+                  // signing on a real device; without it WDA build fails fast with "xcodebuild code 65").
+                  'appium:allowProvisioningDeviceRegistration': true,
+                  ...(IOS_WDA_BUNDLE_ID ? { 'appium:updatedWDABundleId': IOS_WDA_BUNDLE_ID } : {}),
+                }
+              : {}),
+            'appium:noReset': true,
+            'appium:newCommandTimeout': 300,
+            ...localeCaps,
+            specs: iosSpecs,
+          } as any,
+        ]
+      : []),
+  ],
+
+  logLevel: 'warn',
+  framework: 'mocha',
+  // 'spec' for console + PwShapeReporter for a Playwright-shaped JSON the delivery/dashboard reuse.
+  reporters: ['spec', [PwShapeReporter, {}]],
+
+  // Auto-start a local Appium server on :4723 (base path '/')
+  services: ['appium'],
+  port: 4723,
+  path: '/',
+
+  mochaOpts: {
+    ui: 'bdd',
+    timeout: 120000,
+  },
+
+  // iOS + locale: XCUITest's `noReset:false` does NOT actually clear the app's data container
+  // (verified live 2026-06-11) — a Flutter app that persisted its language on a previous launch keeps
+  // it and ignores the new device locale, so the i18n run asserts the wrong language. Wipe the app
+  // data via simctl BEFORE the session so first-launch locale detection re-runs. Android needs no
+  // hook (its noReset:false reset works natively).
+  beforeSession: async (_config, capabilities) => {
+    if (Object.keys(localeCaps).length === 0) return; // not a locale run
+    const caps = capabilities as Record<string, unknown>;
+    if (String(caps['platformName'] || '').toLowerCase() !== 'ios') return;
+    const { execSync } = await import('node:child_process');
+    const fsm = await import('node:fs');
+    const udid = (caps['appium:udid'] as string) || 'booted';
+    // Wipe the session-default app AND every per-feature dual-id bundle the worker's specs declare
+    // (__IOS_BUNDLE__ markers) — a multi-app iOS locale run must reset each app, not just the first.
+    const bundleIds = new Set<string>();
+    if (typeof caps['appium:bundleId'] === 'string') bundleIds.add(caps['appium:bundleId'] as string);
+    for (const spec of specs || []) {
+      try {
+        const src = fsm.readFileSync(String(spec).replace('file://', ''), 'utf-8');
+        const m = /__IOS_BUNDLE__ = '([^']+)'/.exec(src);
+        if (m) bundleIds.add(m[1]);
+      } catch { /* unreadable spec — skip */ }
+    }
+    for (const bundleId of bundleIds) {
+      try { execSync(`xcrun simctl terminate ${udid} ${bundleId}`, { stdio: 'ignore' }); } catch { /* not running */ }
+      try {
+        const dataDir = execSync(`xcrun simctl get_app_container ${udid} ${bundleId} data`).toString().trim();
+        if (dataDir) execSync(`rm -rf "${dataDir}/Library" "${dataDir}/Documents"`);
+        console.log(`[sungen] iOS locale run: wiped app data for ${bundleId} (first-launch locale re-detect)`);
+      } catch { /* app not installed yet */ }
+    }
+  },
+
+  // Per-scenario app reset lives in each generated spec's `beforeEach` (terminate+activate the app
+  // from that feature's `Path:`). One run can therefore host screens from different apps — each spec
+  // launches its own — so there's no single-app reset hook here. The capabilities above only bootstrap
+  // the session (default app / device); the real app per scenario comes from the spec.
+};

package/dist/utils/selector-types.d.ts

@@ -2,6 +2,6 @@
  * Valid selector types used across scaffold generator, selector resolver, and validator.
  * Single source of truth — import this instead of hardcoding.
  */
-export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "page", "column", "locator", "id", "upload", "frame", "table"];
+export declare const VALID_SELECTOR_TYPES: readonly ["placeholder", "role", "testid", "label", "text", "page", "column", "locator", "id", "upload", "frame", "table", "accessibility-id", "xpath", "android-uiautomator", "ios-predicate"];
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];
 //# sourceMappingURL=selector-types.d.ts.map

package/dist/utils/selector-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,4HAavB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"selector-types.d.ts","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,oBAAoB,iMAkBvB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/utils/selector-types.js

@@ -18,5 +18,10 @@ exports.VALID_SELECTOR_TYPES = [
     'upload',
     'frame',
     'table',
+    // === Mobile (Appium) strategies — resolved by the appium adapter (MOB-3) ===
+    'accessibility-id', // cross-platform — Android content-desc / iOS accessibilityIdentifier
+    'xpath', // cross-platform, last resort
+    'android-uiautomator', // Android only — UiSelector expressions
+    'ios-predicate', // iOS only — NSPredicate strings
 ];
 //# sourceMappingURL=selector-types.js.map

package/dist/utils/selector-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;CACC,CAAC"}
+{"version":3,"file":"selector-types.js","sourceRoot":"","sources":["../../src/utils/selector-types.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACU,QAAA,oBAAoB,GAAG;IAClC,aAAa;IACb,MAAM;IACN,QAAQ;IACR,OAAO;IACP,MAAM;IACN,MAAM;IACN,QAAQ;IACR,SAAS;IACT,IAAI;IACJ,QAAQ;IACR,OAAO;IACP,OAAO;IACP,8EAA8E;IAC9E,kBAAkB,EAAK,sEAAsE;IAC7F,OAAO,EAAgB,8BAA8B;IACrD,qBAAqB,EAAE,wCAAwC;IAC/D,eAAe,EAAQ,iCAAiC;CAChD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.2.0-beta.141",
+  "version": "3.2.0-beta.143",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -9,7 +9,7 @@
   },
   "scripts": {
     "build": "rm -rf dist && tsc && npm run copy-templates",
-    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
+    "copy-templates": "mkdir -p dist/generators/test-generator/adapters/playwright/templates/steps && mkdir -p dist/generators/test-generator/templates && mkdir -p dist/orchestrator/templates && mkdir -p dist/dashboard/templates && cp -r src/generators/test-generator/adapters/playwright/templates/*.hbs dist/generators/test-generator/adapters/playwright/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/playwright/templates/steps dist/generators/test-generator/adapters/playwright/templates/ && mkdir -p dist/generators/test-generator/adapters/appium/templates/steps && cp -r src/generators/test-generator/adapters/appium/templates/*.hbs dist/generators/test-generator/adapters/appium/templates/ 2>/dev/null || true && cp -r src/generators/test-generator/adapters/appium/templates/steps dist/generators/test-generator/adapters/appium/templates/ && cp src/generators/test-generator/templates/*.hbs dist/generators/test-generator/templates/ 2>/dev/null || true && cp -r src/orchestrator/templates/* dist/orchestrator/templates/ && cp src/dashboard/templates/index.html dist/dashboard/templates/index.html && mkdir -p dist/harness/catalog && cp src/harness/catalog/*.yaml dist/harness/catalog/",
     "build:dashboard": "cd ../../dashboard && npm install --silent && npm run build && cd - && cp ../../dashboard/dist/index.html src/dashboard/templates/index.html",
     "dev": "tsx src/cli/index.ts",
     "test": "tsx tests/golden/run.ts && tsx tests/audit/run.ts && tsx tests/ingest/run.ts && tsx tests/eval/run.ts && tsx tests/exporter/run.ts && tsx tests/capabilities/run.ts && tsx tests/openapi/run.ts && tsx tests/packaging/run.ts",
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@sungen/driver-ui": "3.2.0-beta.141",
+    "@sungen/driver-ui": "3.2.0-beta.143",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",

package/src/capabilities/context-router.ts

@@ -20,6 +20,12 @@ export interface RouteTask {
   artifact: string;
   /** Capability tags present on the target (e.g. ['@query'], ['@api'], ['@cases']). */
   tags?: string[];
+  /**
+   * The project's active platform (qa/capabilities.yaml `platform:` — web | mobile | …). A platform
+   * capability (mobile/native) is activated by the project's platform, NOT by a tag, so it is keyed
+   * separately. `web` has no capability id of its own (the in-core default is `ui`) → no-op.
+   */
+  platform?: string;
 }
 
 export interface RoutePlan {
@@ -34,11 +40,17 @@ export interface RoutePlan {
 }
 
 class ContextRouter {
-  /** Which capabilities a set of tags activates: the default capability + any owning a present tag. */
-  capabilitiesFor(tags: string[] = []): string[] {
+  /**
+   * Which capabilities a task activates: the default capability + the active platform's capability
+   * (when one is registered with `id === platform`) + any capability owning a present tag.
+   */
+  capabilitiesFor(tags: string[] = [], platform?: string): string[] {
     const ids = new Set<string>();
     const def = capabilityRegistry.defaultCapabilityId();
     if (def) ids.add(def);
+    // A platform capability (mobile/native/…) is activated by the project's platform, not by a tag.
+    // `web` has no capability of its own → falls through to the default `ui` (byte-identical).
+    if (platform && capabilityRegistry.get(platform)) ids.add(platform);
     for (const cap of capabilityRegistry.all()) {
       if ((cap.annotations ?? []).some((a) => tags.includes(a))) ids.add(cap.id);
     }
@@ -47,7 +59,7 @@ class ContextRouter {
 
   /** Compute the routing plan for a task (deterministic). */
   route(task: RouteTask): RoutePlan {
-    const capabilities = this.capabilitiesFor(task.tags ?? []);
+    const capabilities = this.capabilitiesFor(task.tags ?? [], task.platform);
     // Generic sensors (no capability, or the always-on `core`) run regardless of the task's tags;
     // capability-specific sensors run only when their capability is in scope.
     const inScope = (capId?: string) => capId == null || capId === 'core' || capabilities.includes(capId);

package/src/capabilities/discover.ts

@@ -23,7 +23,7 @@ import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
  * move to their packages (R5.5/R5.6) they join this list and leave `LOCAL_DRIVERS`; eventually this
  * becomes a scan of installed `@sungen/driver-*` packages (R5.7).
  */
-const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api'];
+const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api', '@sungen/driver-mobile'];
 
 function loadExternalDriver(name: string): void {
   // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers

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);
+}