@sun-asterisk/sungen 3.2.28 → 3.2.30

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

@@ -28,6 +28,26 @@ import * as path from 'node:path';
 import { execSync } from 'node:child_process';
 import PwShapeReporter from './specs/reporters/pw-shape-reporter';
 
+/**
+ * Failure-evidence output. `test-results/` is already gitignored — screenshots and page sources
+ * of a real app routinely contain live data (a signed-in email, a token rendered on screen), so
+ * this directory must never become committable.
+ */
+const EVIDENCE_ROOT = path.join('test-results', 'mobile');
+/** A full logcat is unbounded; only the tail is ever diagnostic. */
+const EVIDENCE_LOG_TAIL_LINES = 500;
+/** ~2 MB of accessibility tree is already far more than anyone reads. */
+const EVIDENCE_PAGE_SOURCE_MAX = 2_000_000;
+
+/** Filesystem-safe path segment from a feature/test title. */
+function evidenceSlug(s: string): string {
+  return String(s)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'unnamed';
+}
+
 /**
  * Auto-select MOBILE specs and classify each by its target OS (dual-target routing).
  *
@@ -404,9 +424,93 @@ export const config: WebdriverIO.Config = {
   // Connectivity self-heal (#615): onPrepare heals a device wedged by a previous KILLED run
   // (its onComplete never fired) before the session starts; onComplete restores after this run,
   // pass or fail. Both run in the launcher process, so they fire even when the worker/session died.
-  onPrepare: () => { restoreConnectivity('onPrepare'); setShowTouches('onPrepare'); },
+  onPrepare: () => { restoreConnectivity('onPrepare'); setShowTouches('onPrepare'); fs.mkdirSync(EVIDENCE_ROOT, { recursive: true }); },
   onComplete: () => { restoreConnectivity('onComplete'); setShowTouches('onComplete'); },
 
+  /**
+   * Failure evidence. A mobile failure used to reach the report as a single error string — no
+   * image, no tree, no device log — which makes triaging a native UI almost impossible.
+   *
+   * Only runs on failure, so a passing suite pays nothing. Each capture is wrapped SEPARATELY:
+   * one unavailable command (a Flutter page source that blows the buffer, a driver with no log
+   * endpoint) must not cost us the other two, and nothing in here may convert an already-failing
+   * test into a different error.
+   */
+  afterTest: async (
+    test: { title?: string; parent?: string },
+    _context: unknown,
+    result: { passed?: boolean },
+  ): Promise<void> => {
+    if (result?.passed) return;
+
+    // Opt-out for constrained runners (a device farm billing per artifact, a CI box with no disk).
+    // A feature tagged @screenshot:on-failure declares its evidence essential and overrides it.
+    const forced = (globalThis as Record<string, unknown>).__sungenForceEvidence === true;
+    if (!forced && process.env.SUNGEN_MOBILE_EVIDENCE === 'off') return;
+
+    const feature = test?.parent || 'Tests';
+    const title = test?.title || 'test';
+    const dir = path.join(EVIDENCE_ROOT, evidenceSlug(feature), evidenceSlug(title));
+    const files: Array<{ name: string; path: string; contentType: string }> = [];
+
+    try {
+      fs.mkdirSync(dir, { recursive: true });
+    } catch (e) {
+      console.warn(`[sungen] could not create evidence dir ${dir}: ${(e as Error).message}`);
+      return;
+    }
+
+    // 1. Screenshot — the single most useful artifact for a UI failure.
+    try {
+      const shot = path.join(dir, 'screenshot.png');
+      await driver.saveScreenshot(shot);
+      files.push({ name: 'screenshot', path: shot, contentType: 'image/png' });
+    } catch (e) {
+      console.warn(`[sungen] screenshot capture failed: ${(e as Error).message}`);
+    }
+
+    // 2. Page source — the accessibility tree, i.e. WHY a selector did not match. Capped: a
+    //    Flutter/RecyclerView tree can run to tens of MB and there is no value in writing that.
+    try {
+      const src = await driver.getPageSource();
+      const capped = src.length > EVIDENCE_PAGE_SOURCE_MAX
+        ? `${src.slice(0, EVIDENCE_PAGE_SOURCE_MAX)}\n<!-- [sungen] truncated at ${EVIDENCE_PAGE_SOURCE_MAX} of ${src.length} chars -->`
+        : src;
+      if (src.length > EVIDENCE_PAGE_SOURCE_MAX) {
+        console.warn(`[sungen] page source ${src.length} chars — truncated to ${EVIDENCE_PAGE_SOURCE_MAX}`);
+      }
+      const out = path.join(dir, 'page-source.xml');
+      fs.writeFileSync(out, capped, 'utf-8');
+      files.push({ name: 'page-source', path: out, contentType: 'application/xml' });
+    } catch (e) {
+      console.warn(`[sungen] page source capture failed: ${(e as Error).message}`);
+    }
+
+    // 3. Device log — logcat on Android, syslog on iOS. Tail only: a full logcat is unbounded.
+    try {
+      const logType = driver.isIOS ? 'syslog' : 'logcat';
+      const entries = (await driver.getLogs(logType)) as Array<{ message?: string } | string>;
+      const lines = entries.map((l) => (typeof l === 'string' ? l : l?.message || '')).filter(Boolean);
+      const tail = lines.slice(-EVIDENCE_LOG_TAIL_LINES).join('\n');
+      const out = path.join(dir, 'device.log');
+      fs.writeFileSync(out, tail, 'utf-8');
+      files.push({ name: 'device-log', path: out, contentType: 'text/plain' });
+    } catch (e) {
+      console.warn(`[sungen] device log capture failed: ${(e as Error).message}`);
+    }
+
+    // Hand the paths to the reporter so they land in the result's `attachments`. Resolved off
+    // globalThis, not imported — see the note in specs/reporters/pw-shape-reporter.ts.
+    try {
+      const attach = (globalThis as Record<string, unknown>).__sungenAttachEvidence;
+      if (typeof attach === 'function') {
+        (attach as (f: string, t: string, files: typeof files) => void)(feature, title, files);
+      }
+    } catch (e) {
+      console.warn(`[sungen] could not register evidence with the reporter: ${(e as Error).message}`);
+    }
+  },
+
   // 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

package/src/utils/selector-types.ts

@@ -1,20 +1,35 @@
 /**
  * Valid selector types used across scaffold generator, selector resolver, and validator.
  * Single source of truth — import this instead of hardcoding.
+ *
+ * The list is partitioned deliberately. A type is either a LOCATOR STRATEGY (the resolver's
+ * strategy switch turns it into a Playwright/WDIO locator) or a NON-STRATEGY declaration (the
+ * entry describes something other than how to find an element, and a reader downstream of the
+ * resolver consumes it). A type that is in neither set but is still accepted as valid is drift:
+ * it reaches the switch's `default:` and resolves as `getByPlaceholder('<whatever value held>')`,
+ * a selector that cannot match. `upload` sat in exactly that gap — valid, documented, and
+ * silently mis-resolved (issue #690).
+ *
+ * Keep the partition total. `tests/codegen/selector-type-dispatch.run.ts` fails if a new member
+ * of VALID_SELECTOR_TYPES is classified into neither half, or if a strategy type stops being
+ * dispatched and starts resolving as a placeholder.
  */
-export const VALID_SELECTOR_TYPES = [
+
+/**
+ * Types the resolver turns into a locator. Every member MUST be dispatched in
+ * `SelectorResolver.resolveFromEntry` — either by a `case` in its strategy switch or by an
+ * early return above it (`locator` and `upload` share one). The contract is on the RESOLVED
+ * STRATEGY, not on the syntax used to produce it.
+ */
+export const STRATEGY_SELECTOR_TYPES = [
   'placeholder',
   'role',
   'testid',
   'label',
   'text',
-  'page',
-  'column',
   'locator',
   'id',
   '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
@@ -23,4 +38,38 @@ export const VALID_SELECTOR_TYPES = [
   'css',                 // hybrid WebView only — CSS inside a WEBVIEW context (after `switch to [X] frame`)
 ] as const;
 
+/**
+ * Types that declare something OTHER than a locator strategy, so they have no `case` by design.
+ * Each is read after resolution via `ResolvedSelector.selectorType`, or by the pattern that owns
+ * the step, which reads the entry's fields directly:
+ *
+ *   page   — `value` is a URL path, not a locator. The page assertion reads `selectorType`
+ *            AFTER resolving (see StepMapper.checkPageStepFallback), so this type must
+ *            pass through the switch rather than throw.
+ *   table  — the table patterns read `columns` (StepMapper's column-index lookup), `rows` (the
+ *            row templates, backed by SG-W016) and `pagination` (the paginate step, #712) off
+ *            the entry. `pagination` was the NOTE that used to sit here: documented, plumbed,
+ *            and read by nothing — the same drift shape as #690, one level down. It has a
+ *            consumer now, and SG-W004 is the gate that makes the next such field fail a check
+ *            rather than wait to be grepped.
+ *   column — addressed through its table's `columns` map, never resolved standalone.
+ *   frame  — consumed by the frame-enter/exit steps, which need the raw iframe selector.
+ *
+ * Reaching the strategy switch is legitimate for these; the placeholder fallback there is inert
+ * because no consumer reads `strategy` for them.
+ */
+export const NON_STRATEGY_SELECTOR_TYPES = [
+  'page',
+  'column',
+  'frame',
+  'table',
+] as const;
+
+export const VALID_SELECTOR_TYPES = [
+  ...STRATEGY_SELECTOR_TYPES,
+  ...NON_STRATEGY_SELECTOR_TYPES,
+] as const;
+
+export type StrategySelectorType = (typeof STRATEGY_SELECTOR_TYPES)[number];
+export type NonStrategySelectorType = (typeof NON_STRATEGY_SELECTOR_TYPES)[number];
 export type SelectorType = (typeof VALID_SELECTOR_TYPES)[number];