@sun-asterisk/sungen 3.2.24-beta.6 → 3.2.25

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/biometric-action.hbs

@@ -0,0 +1,9 @@
+// Simulated biometric input — EMULATOR/SIMULATOR only (a real device needs a real finger; the
+// command is rejected there and the step fails loud). Android: `mobile: fingerprint` — finger 1
+// must be ENROLLED on the emulator (Settings → Security); an unenrolled id gives the no-match
+// path. iOS Simulator: `mobile: sendBiometricMatch` (Features → Touch/Face ID enrolled).
+if (driver.isIOS) {
+  await driver.execute('mobile: sendBiometricMatch', { type: '{{#if faceId}}faceId{{else}}touchId{{/if}}', match: {{#if match}}true{{else}}false{{/if}} });
+} else {
+  await driver.execute('mobile: fingerprint', { fingerprintId: {{#if match}}1{{else}}9{{/if}} });
+}

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

@@ -1,9 +1,10 @@
 {{!-- 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 same way the checked/unchecked assertions read it — through the __assertCheckedState
+      oracle's __probeCheckedSignals (test-file preamble), which weighs `checked`/`value`, `selected`
+      and isSelected() on the node and its descendants, because no single one of them is reliable on
+      a custom-rendered control. 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. --}}
@@ -12,9 +13,13 @@ await (async () => {
   // 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 = driver.isIOS ? (await __cb.getAttribute('value')) === '1' : (await __cb.getAttribute('checked')) === 'true'; }
-  catch { try { __on = await __cb.isSelected(); } catch { /* state unreadable — tap anyway */ } }
+  // Read the CURRENT state through the same oracle the checked assertions use. The old read here
+  // was `getAttribute('checked') === 'true'` with an isSelected() fallback in a `catch` — but on
+  // Android that read never throws (UiAutomator2 defaults `checked` to "false" on every node), so
+  // the fallback never fired and a custom-rendered toggle already ON read as OFF. This step then
+  // tapped it and turned it OFF — the idempotence guard silently inverted.
+  const __signals = await __probeCheckedSignals(__cb);
+  const __on = __signals.some(s => s.value);
   if (__on) return;
 
   const r = await driver.getElementRect(__cb.elementId);

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/date-picker-unsupported.hbs

@@ -0,0 +1,4 @@
+{{!-- A date-picker on native mobile is a DIALOG (spinner/calendar), not a text field: the generic
+      fill would click the trigger and setValue into it, selecting nothing while reporting success.
+      Same treatment as the upload step — fail loud, and name both ways forward. --}}
+throw new Error("[sungen] {{escapeQuotes reason}}");

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/deep-link-action.hbs

@@ -0,0 +1,8 @@
+// Open a deep link into the app — VIEW intent on Android, XCUITest deepLink on iOS (Simulator).
+// THE entry point for push-param / universal-link routing scenarios.
+await (async () => {
+  {{#if dataRef}}const __url = String(testData.get('{{dataRef}}'));{{else}}const __url = '{{escapeQuotes url}}';{{/if}}
+  const __pkg = __resolveAppId();
+  await driver.execute('mobile: deepLink', driver.isIOS ? { url: __url, bundleId: __pkg } : { url: __url, package: __pkg });
+  await driver.pause(1500); // let the routed screen mount before the next step asserts on it
+})();

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/lifecycle-missing-app-id.hbs

@@ -0,0 +1,5 @@
+{{!-- A lifecycle step (restart / reinstall) in a feature with no `Path:` app id. The lifecycle
+      templates resolve the app through a helper the test-file emits only when that id is present,
+      so without it the spec used to compile clean and die at runtime with a ReferenceError —
+      taking the whole spec down, not the step. Fail at the step, naming the missing line. --}}
+throw new Error("[sungen] {{escapeQuotes reason}}");

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/location-services-action.hbs

@@ -0,0 +1,11 @@
+// Android-only: XCUITest cannot toggle Location Services — fail loud, never silently skip.
+if (driver.isIOS) {
+  throw new Error('turn device location {{#if on}}on{{else}}off{{/if}}: iOS/XCUITest cannot toggle Location Services — run this scenario on Android or tag it @platform:android');
+}
+// `mobile: toggleGps` flips blindly, so read `mobile: isGpsEnabled` first and only toggle when the
+// state differs (idempotent). NOTE: the execute-method aliases, not the legacy JSONWP wrappers —
+// WDIO v9 removed driver.isLocationServicesEnabled()/toggleLocationServices().
+await (async () => {
+  const __locOn = await driver.execute('mobile: isGpsEnabled');
+  if (__locOn !== {{#if on}}true{{else}}false{{/if}}) { await driver.execute('mobile: toggleGps'); }
+})();

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/reinstall-app-action.hbs

@@ -0,0 +1,21 @@
+// Reinstall the app: remove → install from the session's build file → launch → settle.
+// Persistence oracles (dismissals, pins) hinge on what survives a reinstall.
+await (async () => {
+  const __pkg = __resolveAppId();
+  const __caps = (driver.requestedCapabilities || {}) as Record<string, string>;
+  const __appPath = __caps['appium:app'] || __caps['app'];
+  if (!__appPath) {
+    throw new Error('reinstall the app: the session must install from a build file — set APP_APK (Android) / IOS_APP (iOS) so the appium:app capability is present.');
+  }
+  try { await driver.removeApp(__pkg); } catch { /* not installed */ }
+  await driver.installApp(__appPath);
+  await driver.activateApp(__pkg);
+  let __prevHad = false;
+  await driver
+    .waitUntil(async () => {
+      const src = await driver.getPageSource();
+      const has = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
+      const ok = has && __prevHad; __prevHad = has; return ok;
+    }, { timeout: 45000, interval: 400 })
+    .catch(() => { /* best-effort — first launch after install can be the slowest */ });
+})();

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/restart-app-action.hbs

@@ -0,0 +1,16 @@
+// Restart the app: kill → relaunch → wait for rendered content (same settle oracle as the
+// per-scenario relaunch hook — a cold start first paints a contentless skeleton).
+await (async () => {
+  const __pkg = __resolveAppId();
+  try { await driver.terminateApp(__pkg); } catch { /* not running */ }
+  await driver.pause(500);
+  await driver.activateApp(__pkg);
+  let __prevHad = false;
+  await driver
+    .waitUntil(async () => {
+      const src = await driver.getPageSource();
+      const has = /content-desc="[^"]+"|\btext="[^"]+"/.test(src);
+      const ok = has && __prevHad; __prevHad = has; return ok;
+    }, { timeout: 30000, interval: 400 })
+    .catch(() => { /* best-effort — the next step has its own wait */ });
+})();

package/dist/generators/test-generator/adapters/appium/templates/steps/actions/set-connectivity-action.hbs

@@ -0,0 +1,11 @@
+// Android-only: XCUITest exposes no connectivity control — fail loud, never silently skip.
+if (driver.isIOS) {
+  throw new Error('turn {{kind}} {{#if on}}on{{else}}off{{/if}}: iOS/XCUITest cannot toggle device connectivity — run this scenario on Android or tag it @platform:android');
+}
+{{#if isAirplane}}
+// Airplane {{#if on}}ON kills wifi+data{{else}}OFF restores wifi+data{{/if}} — set all three explicitly.
+await driver.execute('mobile: setConnectivity', { wifi: {{#if on}}false{{else}}true{{/if}}, data: {{#if on}}false{{else}}true{{/if}}, airplaneMode: {{#if on}}true{{else}}false{{/if}} });
+{{else}}
+await driver.execute('mobile: setConnectivity', { {{kindKey}}: {{#if on}}true{{else}}false{{/if}} });
+{{/if}}
+await driver.pause(1500); // let the radio state settle before the next step acts on the UI

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

@@ -1,7 +1,7 @@
 {{!-- 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
+      method mirror check-action.hbs (see there for why): state via __probeCheckedSignals (the
+      multi-signal oracle), 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 () => {
@@ -9,9 +9,13 @@ await (async () => {
   // 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 = driver.isIOS ? (await __cb.getAttribute('value')) === '1' : (await __cb.getAttribute('checked')) === 'true'; }
-  catch { try { __on = await __cb.isSelected(); } catch { /* state unreadable — leave as-is */ } }
+  // Read the CURRENT state through the same oracle the checked assertions use. The old read here
+  // was `getAttribute('checked') === 'true'` with an isSelected() fallback in a `catch` — but on
+  // Android that read never throws (UiAutomator2 defaults `checked` to "false" on every node), so
+  // the fallback never fired and a custom-rendered toggle already ON read as OFF. This step then
+  // tapped it and turned it ON — the idempotence guard silently inverted.
+  const __signals = await __probeCheckedSignals(__cb);
+  const __on = __signals.some(s => s.value);
   if (!__on) return;
 
   const r = await driver.getElementRect(__cb.elementId);

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

@@ -1,4 +1,10 @@
-// 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');
+{{!-- Checkbox/toggle state via the __assertCheckedState oracle (test-file preamble), NOT a bare
+      toHaveAttribute. A single `checked`(Android)/`value`(iOS) read cannot be trusted on its own:
+      UiAutomator2 defaults `checked` to "false" on EVERY node, so a custom-rendered control that
+      publishes no checked semantics (Flutter without Semantics(checked:), RN without
+      accessibilityState) reports a confident false while sitting visibly ON. The oracle probes
+      `checked`/`value`, `selected` and isSelected() on the node AND on its descendants (on a
+      composite row the state routinely sits on an inner node), and passes on ANY positive signal.
+      `selected` alone is no substitute either — toBeSelected() is always false for a Flutter
+      Switch, which is why this template stopped using it. --}}
+await __assertCheckedState(await ({{> locator}}), true, '{{escapeQuotes selectorRef}}');

package/dist/generators/test-generator/adapters/appium/templates/steps/assertions/device-log-assertion.hbs

@@ -0,0 +1,16 @@
+{{!-- Device-log oracle (Android: logcat · iOS: syslog) — makes SILENT failure modes and analytics
+      events observable. getLogs returns entries SINCE THE LAST CALL (incremental buffer), so
+      poll-accumulate up to 10s before failing loud with the log type in the message. --}}
+await (async () => {
+  {{#if dataRef}}const __needle = String(testData.get('{{dataRef}}'));{{else}}const __needle = '{{escapeQuotes value}}';{{/if}}
+  const __type = driver.isIOS ? 'syslog' : 'logcat';
+  let __buf = '';
+  const __t0 = Date.now();
+  while (Date.now() - __t0 < 10000) {
+    const __entries = (await driver.getLogs(__type)) as Array<{ message?: string } | string>;
+    __buf += __entries.map((e) => (typeof e === 'string' ? e : (e && e.message) || '')).join('\n') + '\n';
+    if (__buf.includes(__needle)) return;
+    await driver.pause(500);
+  }
+  throw new Error(`device log (${__type}) did not contain ${JSON.stringify(__needle)} within 10s`);
+})();

package/dist/generators/test-generator/adapters/appium/templates/steps/assertions/disappears-within-assertion.hbs

@@ -0,0 +1,5 @@
+{{!-- The element must vanish within the window (auto-dismiss / expiry oracle). Plain $() on
+      purpose — never __ensureVisible: scroll-hunting for something that should disappear would
+      drag the screen away. A 2s grace absorbs accessibility-tree churn latency without hiding a
+      genuinely stuck element. --}}
+await $({{> appium-selector-expr}}).waitForDisplayed({ reverse: true, timeout: {{seconds}} * 1000 + 2000, timeoutMsg: '{{selectorRef}} still visible after the {{seconds}}s disappear window' });

package/dist/generators/test-generator/adapters/appium/templates/steps/assertions/matches-format-assertion.hbs

@@ -0,0 +1,15 @@
+{{!-- Format assertion (mobile): same multi-source read as have-text/contain-text
+      (@text / @content-desc on Android, label/value on iOS), matched against the shape the spec
+      states. The error quotes the FORMAT and the actual string — the compiled regex is noise to
+      the person who wrote the requirement. --}}
+{
+  const __el = await {{> locator}};
+  await __el.waitForDisplayed();
+  const __sources = driver.isIOS
+    ? [await __el.getAttribute('label'), await __el.getAttribute('value')]
+    : [await __el.getText(), await __el.getAttribute('content-desc')];
+  const __actual = String(__sources.find(s => s && String(s).trim() !== '') ?? '').trim();
+  if (!{{{formatRegex}}}.test(__actual)) {
+    throw new Error(`[sungen] Expected [{{escapeQuotes selectorRef}}] to match the format "{{escapeQuotes format}}" but it reads "${__actual}"`);
+  }
+}

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

@@ -1,4 +1,6 @@
-// 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');
+{{!-- The unchecked twin of checked-assertion — same __assertCheckedState oracle, expected=false.
+      Deliberately NOT symmetric with the checked direction: "unchecked" requires that NO probed
+      signal anywhere (node or descendant, `checked`/`value`/`selected`/isSelected()) reads
+      positive, so a visibly-ON custom-rendered control cannot slip through as a false PASS the way
+      a single Android `checked="false"` read would let it. --}}
+await __assertCheckedState(await ({{> locator}}), false, '{{escapeQuotes selectorRef}}');

package/dist/generators/test-generator/adapters/appium/templates/steps/assertions/state-with-filter-assertion.hbs

@@ -1,6 +1,7 @@
 {{!-- State-with-filter (mobile): $$ over the base selector, per-OS text read (hand-rolled — no
       CSS filter() combinator on Appium) matched against dataValue, then assert the state on the
-      match. checked/selected map to the composite-row attribute (mirrors checked-assertion);
+      match. checked/selected go through the __assertCheckedState oracle (mirrors checked-assertion) —
+      a single `checked`/`value` read is unreliable on a custom-rendered control;
       empty is a text read; enabled/focused use direct WDIO matchers. A state with no
       native-mobile analog (sorted*, aria-busy loading) fails loud, matching sorted-assertion's
       house style. --}}
@@ -13,8 +14,8 @@
     if (String(__s.find(s => s && String(s).trim() !== '') ?? '').trim() === __expected) { __el = __c; break; }
   }
   if (!__el) throw new Error(`[sungen] No match with text "${__expected}" to assert state on`);
-  {{#if (or selectedProbe (eq stateAssertion "toBeChecked()"))}}await expect(__el).toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');
-  {{else if (eq stateAssertion "toBeChecked({ checked: false })")}}await expect(__el).not.toHaveAttribute(driver.isIOS ? 'value' : 'checked', driver.isIOS ? '1' : 'true');
+  {{#if (or selectedProbe (eq stateAssertion "toBeChecked()"))}}await __assertCheckedState(__el, true, `item with "${__expected}"`);
+  {{else if (eq stateAssertion "toBeChecked({ checked: false })")}}await __assertCheckedState(__el, false, `item with "${__expected}"`);
   {{else if (eq stateAssertion "toBeEnabled()")}}await expect(__el).toBeEnabled();
   {{else if (eq stateAssertion "toBeFocused()")}}await expect(__el).toBeFocused();
   {{else if (eq stateAssertion "toBeEmpty()")}}await expect(__el).toHaveText('');

package/dist/generators/test-generator/adapters/appium/templates/steps/assertions/still-visible-after-assertion.hbs

@@ -0,0 +1,4 @@
+{{!-- The element must SURVIVE the window (e.g. a barcode valid for 60s, a banner that must not
+      auto-dismiss). Wait out the window first, then run the platform-aware visibility oracle. --}}
+await driver.pause({{seconds}} * 1000);
+await __assertVisible({{> appium-selector-expr}});

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

@@ -1,9 +1,12 @@
 {{!-- Filtered visible (mobile): $$ over the base selector, per-OS text read matched against
       dataValue — no CSS filter() combinator exists on Appium, so the match is hand-rolled
       (covers both the locator- and role-strategy call sites, since both resolve through
-      appium-selector-expr). Assert at least one match is displayed. --}}
+      appium-selector-expr). Assert at least one match is displayed. Substring match by
+      default, matching the web hasText string contract: case-insensitive with collapsed
+      whitespace; `exact` opts into full case-sensitive equality (the anchored-regex twin). --}}
 {
   const __expected = String('{{escapeQuotes dataValue}}').trim();
+  const __norm = (s: string) => s.replace(/\s+/g, ' ').trim().toLowerCase();
   const __items = await $$({{> appium-selector-expr}});
   let __found = false;
   for (const __el of __items) {
@@ -11,7 +14,7 @@
       ? [await __el.getAttribute('label'), await __el.getAttribute('value')]
       : [await __el.getText(), await __el.getAttribute('content-desc')];
     const __actual = String(__sources.find(s => s && String(s).trim() !== '') ?? '').trim();
-    if (__actual === __expected && await __el.isDisplayed()) { __found = true; break; }
+    if ({{#if exact}}__actual === __expected{{else}}__norm(__actual).includes(__norm(__expected)){{/if}} && await __el.isDisplayed()) { __found = true; break; }
   }
   if (!__found) throw new Error(`[sungen] Expected a visible match with text "${__expected}"`);
 }

package/dist/generators/test-generator/adapters/appium/templates/steps/gestures/pull-to-refresh-action.hbs

@@ -1,4 +1,7 @@
 await (async () => { const e = await {{> locator}};
+  // Fail loud on a missing target — an undefined elementId otherwise surfaces as the opaque
+  // server error "The swipe area coordinates must be provided if element is not set".
+  if (!e.elementId) { throw new Error('pull-to-refresh target not found: ' + {{> appium-selector-expr}}); }
   // Pull-to-refresh = drag the content down. Platform-native swipe per OS.
   if (driver.isIOS) { await driver.execute('mobile: swipe', { elementId: e.elementId, direction: 'down' }); }
   else { await driver.execute('mobile: swipeGesture', { elementId: e.elementId, direction: 'down', percent: 0.9, speed: 5000 }); }

package/dist/generators/test-generator/adapters/appium/templates/steps/gestures/swipe-action.hbs

@@ -1,4 +1,7 @@
 await (async () => { const e = await {{> locator}};
+  // Fail loud on a missing target — an undefined elementId otherwise surfaces as the opaque
+  // server error "The swipe area coordinates must be provided if element is not set".
+  if (!e.elementId) { throw new Error('swipe target not found: ' + {{> appium-selector-expr}}); }
   // Platform-native swipe: XCUITest `mobile: swipe` (direction only) vs UiAutomator2 `mobile: swipeGesture`.
   if (driver.isIOS) { await driver.execute('mobile: swipe', { elementId: e.elementId, direction: '{{direction}}' }); }
   else { await driver.execute('mobile: swipeGesture', { elementId: e.elementId, direction: '{{direction}}', percent: 0.75 }); }

package/dist/generators/test-generator/adapters/appium/templates/steps/partials/appium-selector.hbs

@@ -8,7 +8,13 @@
 {{~#case 'xpath'}}{{escapeQuotes value}}{{/case~}}
 {{~#case 'android-uiautomator'}}android={{escapeQuotes value}}{{/case~}}
 {{~#case 'ios-predicate'}}-ios predicate string:{{escapeQuotes value}}{{/case~}}
-{{~#case 'id'}}id={{escapeQuotes value}}{{/case~}}
+{{~!--
+  'id' — Appium's id strategy prepends `<appPackage>:id/` to any value WITHOUT a colon, so a bare
+  Compose testTagsAsResourceId value ("bottom_bar") silently never matches. Bare values therefore
+  compile to an exact UiSelector.resourceId match (Android); package-qualified classic View ids
+  ("com.foo:id/btn") keep the plain id strategy, which passes them through unchanged.
+--~}}
+{{~#case 'id'}}{{#if (includes value ':')}}id={{escapeQuotes value}}{{else}}android=new UiSelector().resourceId("{{escapeQuotes value}}"){{/if}}{{/case~}}
 {{~#case 'locator'}}{{escapeQuotes value}}{{/case~}}
 {{~#case 'css'}}{{escapeQuotes value}}{{/case~}}
 {{~#default}}~{{escapeQuotes value}}{{/default~}}