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

package/src/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/src/utils/selector-types.ts

@@ -15,6 +15,11 @@ export const 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
 ] as const;
 
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];