@vostride/agent-qa-android 0.2.3 → 0.2.4

package/dist/index.js

@@ -31,7 +31,7 @@ import {
 // src/session.ts
 import { remote } from "webdriverio";
 import { MobileSetupError } from "@vostride/agent-qa-core";
-async function createAndroidSession(config, farmSession) {
+async function createAndroidSession(config) {
   const match = config.device?.match ?? {};
   const appiumUrl = process.env.AGENT_QA_APPIUM_URL ?? config.appiumUrl ?? "http://localhost:4723";
   const url = new URL(appiumUrl);
@@ -74,17 +74,6 @@ async function createAndroidSession(config, farmSession) {
       delete capabilities[key];
     }
   }
-  if (farmSession) {
-    Object.assign(capabilities, farmSession.capabilities);
-    return remote({
-      protocol: "https",
-      hostname: farmSession.hostname,
-      port: farmSession.port,
-      path: farmSession.path,
-      logLevel: config.verbose ? "info" : "silent",
-      capabilities
-    });
-  }
   return remote({
     hostname: url.hostname,
     port: parseInt(url.port || "4723", 10),
@@ -264,8 +253,7 @@ return (function() {
     return node ? (node.textContent || '').trim() : '';
   }
 
-  // 437 D-11 (CR-02): a field is named by its label, never by its value, so typed text never
-  // becomes a name. A wrapping label's text drops the field's own text (a select's options).
+  // A field is named by its label, not its value; a wrapping label drops the field's own text.
   function labelText(el, label) {
     var text = label.textContent || '';
     var own = el.textContent || '';
@@ -289,8 +277,7 @@ return (function() {
     return '';
   }
 
-  // parentIndex is the nearest INCLUDED ancestor (structural/skipped nodes collapse
-  // away, matching the mobile/web walkers' Pitfall #7 handling).
+  // The nearest included ancestor: structural and skipped nodes collapse, as on mobile and web.
   function nearestAncestorIndex(el) {
     var p = el.parentElement;
     while (p) {
@@ -310,8 +297,7 @@ return (function() {
     if (style.display === 'none' || style.visibility === 'hidden') continue;
 
     var tag = el.tagName;
-    // 2026-10-19 (444.1-05, D-09): only the outermost content-editable element is an editor;
-    // its descendants are ordinary nodes.
+    // Only the outermost content-editable element is an editor; its descendants are ordinary nodes.
     var host = el.isContentEditable === true
       && !(el.parentElement && el.parentElement.isContentEditable === true);
     var ariaRole = el.getAttribute('role');
@@ -349,7 +335,7 @@ return (function() {
       height: Math.round(rect.height)
     };
 
-    // Real DOM state signals only \u2014 the builder derives every default (D-08).
+    // Real DOM state signals only; the builder derives every default.
     var state = {};
     var disabled = el.disabled === true
       || el.hasAttribute('disabled')
@@ -375,7 +361,7 @@ return (function() {
 
     var parentIndex = nearestAncestorIndex(el);
 
-    // 2026-10-19 (444.1-05 D-08, 444.1-22 D-33): what a field or an editor holds is its value, never its name; a password's never.
+    // What a field or an editor holds is its value, never its name; a password has no value here.
     var observedValue = undefined;
     var textEntry = tag === 'TEXTAREA' || (tag === 'INPUT' && !VALUELESS_TYPES[String(el.type).toLowerCase()]);
     if (textEntry && el.value) {
@@ -534,14 +520,13 @@ var AndroidPlatformAdapter = class {
   captureConsole = true;
   appPackage = null;
   appPid = null;
-  // EXEC-03 session-cached app registry (D-10/D-12): enumerated once per session; null = not yet
-  // enumerated (or enumeration failed and may be retried). Reset in cleanup().
+  // Enumerated once per session; `null` is not yet enumerated or retryable; reset in `cleanup()`.
   appRegistry = null;
   async setup(config) {
     this.config = config;
     this.captureConsole = config.logCapture?.console !== false;
     this.appPackage = this.config.appPackage ?? config.device?.match?.appPackage ?? null;
-    this.driver = await createAndroidSession(this.config, config.farmSession);
+    this.driver = await createAndroidSession(this.config);
     const appPackage = this.appPackage;
     if (appPackage && !this.config.browserName && !this.config.device?.match?.browserName) {
       let state;
@@ -610,7 +595,7 @@ var AndroidPlatformAdapter = class {
   // Once true, we know a WebView/browser exists and should retry rather than
   // falling back to native (which returns an opaque WebView and can crash UiAutomator2).
   hasSeenWebContext = false;
-  async observe(_options) {
+  async observe() {
     if (!this.driver) {
       throw new Error("AndroidPlatformAdapter not initialized \u2014 call setup() first");
     }
@@ -685,7 +670,7 @@ var AndroidPlatformAdapter = class {
         const dims = await getImageDimensions(buf);
         const { width } = await this.driver.getWindowSize();
         if (dims && Math.abs(dims.width - width) > 1) {
-          console.warn(`[android-adapter] screenshot width ${dims.width} != window width ${width} (coord-space divergence, handled by scaleFactor per D-19/D-20)`);
+          console.warn(`[android-adapter] screenshot width ${dims.width} != window width ${width} (coord-space divergence, handled by scaleFactor)`);
         }
       } catch {
       }
@@ -717,13 +702,7 @@ var AndroidPlatformAdapter = class {
     if (!level) return newLogs;
     return newLogs.filter((e) => e.level === level);
   }
-  /**
-   * 428 D-11: the labelled 1s snapshot preview, over `captureScreenshot()` — `takeScreenshot()`
-   * and nothing else. Never `screenshot()`: that one switches the Appium context, and a tick
-   * landing between a step's context switch and its command would run the command in the wrong
-   * context. Declared before the driver exists (a capture then answers `undefined`), so the
-   * composition's selection never falls through to `screenshot()`.
-   */
+  // `takeScreenshot()` only: `screenshot()` switches the Appium context mid-step.
   get liveStream() {
     this.liveStreamCapability ??= createSnapshotLiveStream({ capture: () => this.captureScreenshot() });
     return this.liveStreamCapability;
@@ -899,9 +878,6 @@ var AndroidPlatformAdapter = class {
       return void 0;
     }
   }
-  // ---------------------------------------------------------------------------
-  // Compound behaviors (EXEC-01/02/03)
-  // ---------------------------------------------------------------------------
   /** Read the live text of a focused element handle; undefined when nothing is readable. */
   async readElementText(el) {
     try {
@@ -918,15 +894,12 @@ var AndroidPlatformAdapter = class {
       return false;
     }
   }
-  /** An empty field's getText() returns its hint (437 Pitfall 4), so a showing hint reads ''. */
+  /** An empty field's getText() returns its hint, so a showing hint reads ''. */
   async readFocusedValue(el) {
     if (await this.focusedMatches(FOCUSED_HINT_XPATH)) return "";
     return await this.readElementText(el);
   }
-  /**
-   * The `mobile: shell` route of keyevent and openQuickSettings (437 D-18). A refusal by secure
-   * Appium is recorded as unavailable and any other driver error as failed; neither is a pass.
-   */
+  // A secure-Appium refusal is recorded as unavailable and any other driver error as failed.
   async runShell(verb, args) {
     try {
       await this.driver.execute("mobile: shell", args);
@@ -949,7 +922,7 @@ var AndroidPlatformAdapter = class {
       return { success: false, error: `${verb} failed: ${detail}`, metadata: { shellAction } };
     }
   }
-  /** The one submit mechanism on every Android path (437 D-13); pressed once, never retried. */
+  /** The one submit mechanism on every Android path; pressed once, never retried. */
   async pressEnter() {
     try {
       await this.driver.execute("mobile: pressKey", { keycode: ENTER_KEYCODE });
@@ -958,7 +931,7 @@ var AndroidPlatformAdapter = class {
       return { sent: false, outcome: "failed", detail: firstErrorLine(err) };
     }
   }
-  /** 437 FA-2 (owner, 2026-10-08): line breaks into a single-line field are refused before typing. */
+  // Line breaks into a single-line field are refused before typing.
   refuseLineBreaks(action, box) {
     const fillRefusal = {
       verb: "fill",
@@ -972,14 +945,7 @@ var AndroidPlatformAdapter = class {
       metadata: { fillRefusal, ...action.submit ? { fillSubmit: { ...INPUT_FAILED } } : {} }
     };
   }
-  /**
-   * Native fill from the focused handle (437 D-08..D-10, D-12, D-13, D-15, D-17). Delivers once
-   * (addValue for append, setValue for replace), reads back from the same handle and records the
-   * shared verdict. An unknown append prior or an unreadable read-back is unverified, which never
-   * stops a requested Enter; a mismatch or a multi-line field holds it. A driver error during
-   * delivery ends the fill: nothing is typed again and no Enter follows. A secure field yields
-   * length sentinels only.
-   */
+  // Delivers once and reads back; an unverified result still presses Enter, a mismatch holds it.
   async fillNativeCompound(el, action, box) {
     const isAppend = action.clearMode === "append";
     if (LINE_BREAK_RE.test(action.text) && await this.focusedMatches(FOCUSED_SINGLE_LINE_XPATH)) {
@@ -1015,11 +981,7 @@ var AndroidPlatformAdapter = class {
       return void 0;
     }
   }
-  /**
-   * 437 D-11 (WR-02): where the focused node is relative to the ref, judged by its read bounds.
-   * An unreadable or unparseable value is no evidence, so the native path stays (D-04, D-15).
-   * 444.1 D-07: 'elsewhere' needs positive evidence, the bounds of another observed field.
-   */
+  // `elsewhere` needs positive evidence: the read bounds of another observed field.
   async focusIsElsewhere(handle, ref, bounds) {
     let raw;
     try {
@@ -1036,18 +998,12 @@ var AndroidPlatformAdapter = class {
     }
     return "moved";
   }
-  /** Ctrl+A then DEL as key input; clears only the view holding input focus (437 D-14). */
+  /** Ctrl+A then DEL as key input; clears only the view holding input focus. */
   async clearByKeys() {
     await this.driver.execute("mobile: pressKey", CTRL_A);
     await this.driver.execute("mobile: pressKey", { keycode: DEL_KEYCODE });
   }
-  /**
-   * The last-resort keyboard path (437 D-14): the tap left no focused handle. Replace clears by
-   * keys, the text goes through one `mobile: type` (Appium's Unicode IME, exact for every D-08
-   * text), and the value is read back only when a focused handle can be found afterwards. An
-   * append's prior value is unknown, so it is never better than unverified. The field's kind comes
-   * from the observed input-type (D-15): only positive evidence refuses line breaks or holds Enter.
-   */
+  // Last resort when the tap left no handle; an append's prior is unknown, so at best unverified.
   async fillKeyboardPath(action, box, refData) {
     const isAppend = action.clearMode === "append";
     const kind = fieldKindOf(refData);
@@ -1075,11 +1031,7 @@ var AndroidPlatformAdapter = class {
       enter: () => this.pressEnter()
     });
   }
-  /**
-   * Native and keyboard clearText (437 D-16): clearValue on the focused handle, or Ctrl+A then DEL
-   * when the tap left none, then the hint-aware read-back judged against the empty string. The
-   * caller has already checked that a focused handle is the referenced field (WR-02).
-   */
+  // The caller has already checked that a focused handle is the referenced field.
   async clearNativeOrKeyboard(box, handle) {
     const path = handle ? "native" : "keyboard";
     const before = handle ? await this.isSecure(handle) : false;
@@ -1139,11 +1091,7 @@ var AndroidPlatformAdapter = class {
       metadata: { fillVerdict, ...action.submit ? { fillSubmit: { ...INPUT_FAILED } } : {} }
     };
   }
-  /**
-   * The shared end of every Android fill (437 D-09, D-10, D-13, D-15, D-17): records the verdict
-   * and, when a submit was requested, holds Enter on a mismatch or a multi-line field and otherwise
-   * presses it once through `enter`.
-   */
+  // Holds Enter on a mismatch or a multi-line field; otherwise presses it once.
   async settleFill(action, box, settle) {
     const { path, verdict, multiline, enter } = settle;
     const fillVerdict = {
@@ -1179,7 +1127,7 @@ var AndroidPlatformAdapter = class {
     }
     return { success: true, ...box, ...notice, metadata };
   }
-  /** A real W3C touch tap in the WebView context at the ref's CSS-pixel centre (437 D-11). */
+  /** A real W3C touch tap in the WebView context at the ref's CSS-pixel centre. */
   async trustedWebTap(center) {
     await safePerform(
       this.driver.action("pointer", { parameters: { pointerType: "touch" } }).move({ x: Math.round(center.x), y: Math.round(center.y), origin: "viewport" }).down({ button: 0 }).up({ button: 0 })
@@ -1232,7 +1180,7 @@ var AndroidPlatformAdapter = class {
       if (this.activeWebContext) await this.ensureContext(this.activeWebContext);
     }
   }
-  /** 437 D-11: a tap that left no editable field, or another field, focused writes nothing. */
+  // A tap that leaves no editable field, or another field, focused writes nothing.
   refuseFocus(verb, ref, focus, submit, box) {
     const nothing = verb === "fill" ? "nothing was typed" : "nothing was cleared";
     let fillRefusal;
@@ -1254,10 +1202,7 @@ var AndroidPlatformAdapter = class {
       metadata: { fillRefusal, ...submit ? { fillSubmit: { ...INPUT_FAILED } } : {} }
     };
   }
-  /**
-   * WebView clearText (437 D-11, D-16): the same tap and focus probe as the fill, W3C Ctrl+A and
-   * Backspace, then a read-back judged against the empty string. Never success without that check.
-   */
+  // Never success without the read-back judged against the empty string.
   async clearWebViewField(ref, center, box) {
     const driver = this.driver;
     await this.trustedWebTap(center);
@@ -1273,11 +1218,7 @@ var AndroidPlatformAdapter = class {
     }
     return this.settleClear("webview", await this.readWebFieldValue(), focus.secure, box);
   }
-  /**
-   * WebView fill as trusted input (437 D-11): a W3C tap on the ref, a read-only focus probe,
-   * W3C Ctrl+A and Backspace for replace, `mobile: type` from NATIVE_APP, a read-only read-back,
-   * and one `mobile: pressKey 66` from NATIVE_APP. No script writes the field or fires an event.
-   */
+  // Trusted input only: no page script writes the field or fires an event.
   async fillWebViewCompound(action, box, center) {
     const driver = this.driver;
     const isAppend = action.clearMode === "append";
@@ -1314,15 +1255,7 @@ var AndroidPlatformAdapter = class {
       enter: () => this.withNativeContext(() => this.pressEnter())
     });
   }
-  /**
-   * EXEC-02 platform primitives injected into the shared runner scroll loops (D-02/D-03; 436-02
-   * D-25). A native swipe is `mobile: scrollGesture` over the container (the ref's bounds, else the
-   * screen), whose boolean is the driver's own boundary signal; in a WebView the touch swipe is
-   * measured over every WebView scroller before and after (436-18), paired by identity (436-23).
-   * nativeSearchScroll drives the UiAutomator
-   * `UiScrollable.scrollIntoView` rung over an injection-escaped selector; readInterimTree is a
-   * light page-source parse — NO refMap mint, NO screenshot, lastRefs untouched.
-   */
+  // Native swipes trust `scrollGesture`'s boolean; WebView swipes compare every scroller by id.
   async buildAndroidScrollPrimitives(scrollDirection, maxSwipes, factor = 1) {
     const driver = this.driver;
     const viewport = await driver.getWindowSize();
@@ -1381,13 +1314,7 @@ var AndroidPlatformAdapter = class {
       }
     };
   }
-  /**
-   * The WebView scrollers a touch swipe may have acted on (436-18 · D-25), read by the shared
-   * WEBVIEW_SCROLLERS_SCRIPT. The touch point cannot be mapped into the WebView's CSS coordinates,
-   * so the swipe is judged over all of them.
-   * 2026-10-08 (436-23): a frame in view reads unknown; members carry an identity and are paired
-   * by it; open shadow roots are walked; only on-screen element scrollers are members.
-   */
+  // The touch point cannot map into CSS coordinates, so the swipe is judged over every scroller.
   async readWebViewScrollers() {
     try {
       return parseWebViewScrollers(await this.driver.execute(WEBVIEW_SCROLLERS_SCRIPT));
@@ -1395,12 +1322,7 @@ var AndroidPlatformAdapter = class {
       return void 0;
     }
   }
-  /**
-   * EXEC-03 openApp (D-10/D-11/D-12). Resolve a human name to a package id (or validate an
-   * explicit bundleId) over the session-cached registry, then launch via activateApp. On a
-   * resolution MISS the registry is re-enumerated exactly once (catches mid-run installs) before
-   * erroring with the resolver's candidate ids. Never a best-guess launch (T-359-04).
-   */
+  // On a resolution miss the registry is re-enumerated once before erroring; never a best guess.
   async openApp(action) {
     const driver = this.driver;
     let registry = await this.ensureAppRegistry();
@@ -1452,12 +1374,7 @@ var AndroidPlatformAdapter = class {
     if (enumerated !== null) this.appRegistry = enumerated;
     return enumerated;
   }
-  /**
-   * Enumerate installed apps through the driver only (ownership contract — no adb/child_process).
-   * `mobile: listApps` maps package ids → AppRegistryEntry (labels only when the same call carries
-   * them, D-10 — no per-package round-trips). On failure, fall back to `mobile: shell` pm-list ONLY
-   * when the AGENT_QA_ANDROID_USE_MOBILE_SHELL gate is '1' (Pitfall 4). Null = enumeration unavailable.
-   */
+  // Driver only, no adb; the `mobile: shell` fallback needs `AGENT_QA_ANDROID_USE_MOBILE_SHELL=1`.
   async enumerateApps() {
     const driver = this.driver;
     try {
@@ -1893,8 +1810,6 @@ var AndroidPlatformAdapter = class {
               success: false,
               error: 'assertValue {source:"network"} (HTTP log inspection) is not available on the Android adapter. Use a web target for network assertions, or assert on visible UI text.'
             };
-          case "expr-result":
-            return { success: true, data: void 0 };
         }
       }
       case "drag": {
@@ -1948,11 +1863,7 @@ var AndroidPlatformAdapter = class {
         }
         return { success: true, coordinates: { x, y } };
       }
-      // Runner-minted / author-channel verbs (D-01/D-15): reportValue, assertAI, extractAI, and
-      // setVariable are intercepted at the runner dispatch seam and never reach the adapter. A
-      // grouped §7.1 defensive case surfaces a dispatch-routing error if one arrives here;
-      // assertNever remains the backstop for a genuinely unknown schema verb. (uniqueValue is
-      // web-only and is not part of ActionsFor<'android'>.)
+      // Runner-channel verbs never reach the adapter; one arriving here is a routing error.
       case "reportValue":
       case "assertAI":
       case "extractAI":