@aarwitz/tapp 0.17.0-rc.6 → 0.17.0-rc.8

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -1518,6 +1518,8 @@ class ExplorerTests: XCTestCase {
                     if current.isEmpty || current == ph {
                         reportedPersistenceKeys.insert(memKey)
                         let t = "Entered value did not persist: '\(fieldKey)' on \(titleStr)"
+                        issues.append((type: "state_persistence", severity: "medium", title: t,
+                                       desc: "Typed '\(typed)' into this field earlier in the run; after navigating away and returning, the field is empty — entered state was silently lost."))
                         print("OCQA_ISSUE:{\"type\":\"state_persistence\",\"severity\":\"medium\",\"title\":\"\(escapeJSON(t))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapeJSON(fieldKey))\",\"step\":\(actionCount),\"desc\":\"Typed '\(escapeJSON(typed))' into this field earlier in the run; after navigating away and returning, the field is empty — entered state was silently lost.\"}")
                     }
                 }
@@ -1679,7 +1681,13 @@ class ExplorerTests: XCTestCase {
 
             // ---- Blank-screen detection ----
             // Distinguish between "no a11y labels / custom UI" vs genuinely empty.
-            if visibleTextInventory.isEmpty && interactable.count == 0 {
+            // A system Back/Close affordance is navigation chrome, not screen content. Treat a
+            // destination whose only usable control is that chrome as blank too; otherwise an
+            // EmptyView pushed by NavigationStack looks like a healthy one-control screen.
+            let contentInteractables = interactable.filter {
+                !isNavBackButton($0) && !isLikelyGlobalNavigation($0, screenBounds: screenBounds)
+            }
+            if visibleTextInventory.isEmpty && contentInteractables.isEmpty {
                 let blankKey = "blank:\(titleStr)"
                 let blankCount = (actionCounts[blankKey] ?? 0) + 1
                 actionCounts[blankKey] = blankCount
@@ -2273,12 +2281,21 @@ class ExplorerTests: XCTestCase {
             // the crash itself goes unreported. app.state is non-throwing even when the app is dead.
             // (Found on a real app: a login submit terminated the app; the run limped on but emitted
             // no crash finding.) Try one relaunch to distinguish a hard crash from a transient exit.
-            if app.state != .runningForeground {
-                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(app.state.rawValue)")
+            let stateAfterAction = app.state
+            if stateAfterAction != .runningForeground {
+                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(stateAfterAction.rawValue)")
+                let crashKey = "crash:\(titleStr)|\(key)"
+                // A terminated process is already proof of an in-run crash. Relaunching it may
+                // succeed, but that must not erase the user-visible failure that just happened.
+                if stateAfterAction == .notRunning && !reportedIssueKeys.contains(crashKey) {
+                    reportedIssueKeys.insert(crashKey)
+                    issues.append((type: "crash", severity: "critical", title: "App crashed after \(actionType) on \(titleStr)",
+                                   desc: "The app process terminated after \(actionType) '\(targetName)' on '\(titleStr)'."))
+                    print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed after \(actionType) on \(titleStr)"))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                }
                 app.activate()
                 Thread.sleep(forTimeInterval: 3.0)
                 if app.state != .runningForeground {
-                    let crashKey = "crash:\(titleStr)|\(key)"
                     if !reportedIssueKeys.contains(crashKey) {
                         reportedIssueKeys.insert(crashKey)
                         issues.append((type: "crash", severity: "critical", title: "App crashed after \(actionType) on \(titleStr)",
@@ -2382,16 +2399,28 @@ class ExplorerTests: XCTestCase {
 
             // ---- App left foreground / crash detection ----
             // Check both .exists and .state — external links may cause either to fail
-            let appInForeground = app.state == .runningForeground
+            let stateAfterDelayedChecks = app.state
+            let appInForeground = stateAfterDelayedChecks == .runningForeground
             if !appInForeground || !app.exists {
-                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(app.state.rawValue)")
+                print("OCQA_STATE:app_left_foreground step=\(actionCount) state=\(stateAfterDelayedChecks.rawValue)")
+                let crashKey = "crash:\(titleStr)|\(key)"
+                if stateAfterDelayedChecks == .notRunning && !reportedIssueKeys.contains(crashKey) {
+                    reportedIssueKeys.insert(crashKey)
+                    issues.append((type: "crash", severity: "critical",
+                                   title: "App crashed after \(actionType) on \(titleStr)",
+                                   desc: "The app process terminated after: \(actionDesc)"))
+                    print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"\(escapeJSON("App crashed after \(actionType) on \(titleStr)"))\",\"screen\":\"\(escapedTitle)\",\"control\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                }
                 app.activate()
                 Thread.sleep(forTimeInterval: 3.0)
                 if app.state != .runningForeground {
-                    issues.append((type: "crash", severity: "critical",
-                                   title: "App not recoverable",
-                                   desc: "App left foreground after: \(actionDesc)"))
-                    print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"App not recoverable\",\"action\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                    if !reportedIssueKeys.contains(crashKey) {
+                        reportedIssueKeys.insert(crashKey)
+                        issues.append((type: "crash", severity: "critical",
+                                       title: "App not recoverable",
+                                       desc: "App left foreground after: \(actionDesc)"))
+                        print("OCQA_ISSUE:{\"type\":\"crash\",\"severity\":\"critical\",\"title\":\"App not recoverable\",\"action\":\"\(escapedTarget)\",\"step\":\(actionCount)}")
+                    }
                     break
                 }
                 print("OCQA_STATE:app_reactivated step=\(actionCount)")

package/bin/tapp.js

@@ -235,6 +235,7 @@ function safeCommandUsage(verb) {
     pr: "tapp pr plan [--base REF|--changed-files FILE] [--head REF] [--platform PLATFORM] [--out FILE]\ntapp pr gate PLAN [gate target/options]\ntapp pr adopt PLAN --item ID [--project-dir DIR]",
     plan: "tapp plan show [FILE]\ntapp plan review [FILE] --approve NAME[,NAME] --reject NAME[,NAME] --defer NAME[,NAME]\ntapp plan generate|validate|promote [FILE] [options]",
     baseline: "tapp baseline create [repo] [--platform PLATFORM] [--target NAME] [--from GATE.json] [--replace]",
+    ci: "tapp ci ...\ntapp ci install [repo] [--out FILE] [--manifest FILE] [--dry-run] [--replace]",
     actor: "tapp actor set NAME --email-env ENV --password-env ENV [--project-dir DIR]\ntapp actor list [repo]",
     app: "tapp app [repo] [--no-open] [--port PORT]",
     report: "tapp report [captureId|latest]",
@@ -248,7 +249,10 @@ function safeCommandUsage(verb) {
 // Safe help: `--help`/`-h` on ANY verb prints the command reference and does NOTHING else — never
 // builds, launches, writes, or opens (ADR-0005 manual-testing requirement). `ci` keeps its own
 // richer `--help` (a safe usage print in ci-gate.sh); help/version don't need interception.
-if ((rest.includes("--help") || rest.includes("-h")) && !["help", "version", "--version", "-v", "ci"].includes(command)) {
+const safeHelpRequested = (rest.includes("--help") || rest.includes("-h"))
+  && !["help", "version", "--version", "-v"].includes(command)
+  && (command !== "ci" || rest[0] === "install");
+if (safeHelpRequested) {
   console.log(`Usage:\n  ${safeCommandUsage(command).replaceAll("\n", "\n  ")}\n\nℹ️  --help never builds, launches, writes, or opens. Full command reference:\n`);
   command = "help";
   rest = [];
@@ -1460,9 +1464,15 @@ switch (command) {
     const runs = roots
       .flatMap((root) => fs.readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(root, e.name)))
       .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
-    const wanted = rest[0] && rest[0] !== "latest" ? runs.find((r) => path.basename(r) === rest[0]) : runs[0];
+    const hasMarkers = (dir) => fs.existsSync(path.join(dir, "ocqa-markers.txt"));
+    // `latest` (default) resolves to the newest *exploration* capture — the captures directory is
+    // also full of flow-*/scenario-* evidence dirs with no ocqa-markers.txt, and picking the newest
+    // of those made `tapp report` fail even though valid exploration captures existed. An explicitly
+    // named capture is honored as-is so a non-exploration capture still gets a clear "no markers".
+    const explicit = rest[0] && rest[0] !== "latest";
+    const wanted = explicit ? runs.find((r) => path.basename(r) === rest[0]) : runs.find(hasMarkers);
     if (!wanted) {
-      bad("No captures found", rest[0] ? `no capture named "${rest[0]}"` : "run a QA exploration first");
+      bad("No captures found", explicit ? `no capture named "${rest[0]}"` : "run an exploration first (no capture with exploration markers was found)");
       process.exit(1);
     }
     const { writeHtmlReport } = await import(path.join(packageRoot, "mcp-server", "src", "html-report.js"));
@@ -1472,7 +1482,9 @@ switch (command) {
       process.exit(1);
     }
     ok("Evidence report", out);
-    spawnSync("open", [out], { stdio: "ignore" });
+    // Only launch a browser from an interactive terminal — agents, scripts, and tests that invoke
+    // `tapp report` non-interactively get the path without a surprise GUI window.
+    if (process.stdout.isTTY) spawnSync("open", [out], { stdio: "ignore" });
     break;
   }
 

package/mcp-server/src/android-driver.js

@@ -282,6 +282,19 @@ export class AndroidDriver {
     return { screenTitle: detectAndroidScreen(elements, activity), elements, activity, xml };
   }
 
+  async observeActivityTransition(beforeActivity, timeoutMs = 700) {
+    const initial = String(beforeActivity || "");
+    if (!initial) return false;
+    const deadline = Date.now() + timeoutMs;
+    do {
+      const current = await this.currentActivity();
+      if (current && current !== initial) return true;
+      if (Date.now() >= deadline) break;
+      await sleep(60);
+    } while (Date.now() < deadline);
+    return false;
+  }
+
   async screenshot(filePath) {
     const r = await this.adb(["exec-out", "screencap", "-p"], { encoding: "buffer", timeout: 30_000, maxBuffer: 32 * 1024 * 1024 });
     if (r.code !== 0 || !r.stdout?.length) throw new Error("Android screenshot failed");

package/mcp-server/src/android-explorer.js

@@ -57,8 +57,9 @@ export function isAndroidBlankSnapshot(snapshot) {
   return !meaningful && !interactive;
 }
 
-export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", clearData = true, seedTargets = [], onProgress = () => {}, driver }) {
+export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40, timeoutSec = 300, outDir, testEmail = "", testPassword = "", clearData = true, seedTargets = [], onProgress = () => {}, driver, screenshotDelayMs }) {
   const d = driver || new AndroidDriver({ appId, serial });
+  const visualSettleMs = Number.isFinite(screenshotDelayMs) ? Math.max(0, screenshotDelayMs) : (driver ? 0 : 350);
   d.appId = appId;
   await d.ensureDevice();
   if (apkPath) await d.install(apkPath);
@@ -112,6 +113,10 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
     const screen = snapshot.screenTitle;
     if (!visited.has(hash)) {
       visited.set(hash, screen);
+      // UIAutomator can expose a fully populated hierarchy a fraction before
+      // SurfaceFlinger composites the first app frame. Give real devices one
+      // bounded draw interval so retained PNG evidence matches the tree.
+      if (visualSettleMs) await sleep(visualSettleMs);
       await d.screenshot(path.join(screenshots, `${String(visited.size).padStart(2, "0")}-${screen.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}.png`)).catch(() => {});
     }
     const inputs = inputDescriptors(snapshot.elements);
@@ -209,7 +214,14 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       const before = hash;
       const r = await d.tap(target, snap);
       actions += 1;
-      snap = await d.settle();
+      // UIAutomator can miss a short-lived Activity that opens and cleanly
+      // returns before its next hierarchy dump. Observe the cheaper Activity
+      // signal in parallel so a real transient response is not called dead.
+      const activityEffect = r.status === "ok" && typeof d.observeActivityTransition === "function"
+        ? d.observeActivityTransition(snap.activity)
+        : Promise.resolve(false);
+      const [settledSnap, activityEffectObserved] = await Promise.all([d.settle(), activityEffect]);
+      snap = settledSnap;
       const after = stateHash(snap);
       emit("ACTION", { type: loginSubmit ? "login_submit" : "tap", target, reason: "untried_control", step: actions, screen, status: r.status });
       if (!isAndroidAppSnapshot(snap, appId)) {
@@ -221,7 +233,7 @@ export async function exploreAndroid({ appId, apkPath, serial, maxActions = 40,
       if (r.status === "ok" && authFailed) {
         emit("ISSUE", { type: "auth_failed", severity: "high", title: "Sign-in attempt remained on the login screen", screen, target, step: actions });
         issues += 1;
-      } else if (r.status === "ok" && before === after && candidate.clickable) {
+      } else if (r.status === "ok" && before === after && candidate.clickable && !activityEffectObserved) {
         emit("ISSUE", { type: "unresponsive_element", severity: "medium", title: `Control did not respond: ${target}`, screen, target, step: actions });
         issues += 1;
       }

package/mcp-server/src/html-report.js

@@ -14,6 +14,22 @@ const SEV_COLOR = { critical: "#cf222e", high: "#bc4c00", medium: "#9a6700", low
 
 const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
 
+const VALID_PLATFORMS = new Set(["web", "android", "ios"]);
+
+// Recover a capture's platform when no in-memory report is available. Prefer the run's persisted
+// metadata (ui-map.json → app.platforms) — it is authoritative and survives a renamed folder — and
+// fall back to the capture-id prefix (web-*/android-*, ios unprefixed) only for legacy captures that
+// predate the map. Defaults to ios if nothing is resolvable, matching buildQaReport's own default.
+export function capturePlatform(captureDir) {
+  try {
+    const map = JSON.parse(fs.readFileSync(path.join(captureDir, "ui-map.json"), "utf8"));
+    const fromMap = (map?.app?.platforms || []).find((p) => VALID_PLATFORMS.has(p));
+    if (fromMap) return fromMap;
+  } catch { /* no map, unreadable, or no valid platform — fall back to the id prefix */ }
+  const base = path.basename(captureDir);
+  return base.startsWith("web-") ? "web" : base.startsWith("android-") ? "android" : "ios";
+}
+
 // Two capture layouts exist: web runs write state_*.png at the capture root; iOS runs
 // export XCUITest attachments into screenshots/ as UUID files with a manifest carrying
 // the human-readable state_N_<Screen> names.
@@ -50,7 +66,11 @@ function collectShots(captureDir) {
 }
 
 export function writeHtmlReport(captureDir, { report, label = "", recordingWarning = "" } = {}) {
-  const r = report || buildQaReport(path.join(captureDir, "ocqa-markers.txt"));
+  // Rebuild path (e.g. `tapp report`): no report object is passed, so buildQaReport would default to
+  // native — rendering a web/android page with the wrong "Checked / Not checked" scope, overclaiming
+  // native checks it never ran. Recover the run's real platform (metadata first, id prefix as a
+  // legacy fallback). When a report object IS passed (explore/init), it is already correct.
+  const r = report || buildQaReport(path.join(captureDir, "ocqa-markers.txt"), { platform: capturePlatform(captureDir) });
   if (!r) return null;
 
   const shots = collectShots(captureDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.0-rc.6",
+  "version": "0.17.0-rc.8",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
   "license": "MIT",

package/scripts/flow_ai_judge.py

@@ -26,7 +26,7 @@ def _ctx():
 
 
 SSL_CTX = _ctx()
-MODEL = os.environ.get("TAPP_VISION_MODEL") or os.environ.get("AUTOTAP_VISION_MODEL", "claude-haiku-4-5-20251001")
+MODEL = os.environ.get("TAPP_VISION_MODEL", "claude-haiku-4-5-20251001")
 SYSTEM = (
     "You are a QA test oracle. You are shown one iOS app screenshot and a CLAIM the test asserts about "
     "it. Decide if the claim is TRUE of what is actually visible. Be strict and literal — only pass if "