@aarwitz/tapp 0.17.16 → 0.17.18

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tapp",
   "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
-  "version": "0.17.16",
+  "version": "0.17.18",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.16",
+        "@aarwitz/tapp@0.17.18",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -377,6 +377,7 @@ class ExplorerTests: XCTestCase {
             let action = (cmd["action"] as? String ?? "").lowercased()
             var status = "ok"
             var loginDetail = ""
+            noteNavigationTitle() // navigation history, so `back` can recognise its control
 
             switch action {
             case "login":
@@ -391,7 +392,32 @@ class ExplorerTests: XCTestCase {
                 }
             case "tap":
                 if let id = cmd["id"] as? String, !id.isEmpty {
+                    let beforeElements = readUITree(app)
+                    let beforeHash = computeHash(beforeElements)
+                    let beforeTitle = detectTitle(beforeElements) ?? "Unknown"
                     status = sessionTapById(id)
+                    if status == "ok" {
+                        waitForUIStability(timeout: 1.5)
+                        let afterElements = readUITree(app)
+                        // Nothing moved and the target is still sitting there: the tap landed on
+                        // something that is not the control the caller meant — classically a system
+                        // sheet ("Save Password?") whose buttons belong to SpringBoard, not the app
+                        // (field issue #6: three "ok" taps while the sheet stayed up).
+                        let unchanged = computeHash(afterElements) == beforeHash
+                            && (detectTitle(afterElements) ?? "Unknown") == beforeTitle
+                        if unchanged && elementPresent(id) {
+                            if tapSystemSheetButton(id) {
+                                waitForUIStability(timeout: 1.5)
+                                let recovered = readUITree(app)
+                                status = computeHash(recovered) == beforeHash ? "no_effect" : "ok"
+                            } else {
+                                status = "no_effect"
+                            }
+                            if status == "no_effect" {
+                                loginDetail = "‘\(id)’ is still on screen and nothing changed — the tap did not reach the control you meant; if this is a system sheet, tap by {x, y}"
+                            }
+                        }
+                    }
                 } else if let x = cmd["x"] as? Double, let y = cmd["y"] as? Double {
                     app.coordinate(withNormalizedOffset: .zero).withOffset(CGVector(dx: x, dy: y)).tap()
                 } else { status = "bad_args" }
@@ -403,7 +429,8 @@ class ExplorerTests: XCTestCase {
                 case "down": app.swipeDown(); case "left": app.swipeLeft(); case "right": app.swipeRight(); default: app.swipeUp()
                 }
             case "back":
-                sessionBack()
+                status = sessionBack()
+                if status == "no_effect" { loginDetail = "no back control on this screen, or tapping it did not change the screen — this is a root screen, or its Back belongs to a different navigation stack (try tap {id: \"Back\"}, or `swipe` for a gesture)" }
             case "wait":
                 let target = (cmd["id"] as? String).flatMap { $0.isEmpty ? nil : $0 } ?? (cmd["text"] as? String ?? "")
                 let waitMs = (cmd["timeoutMs"] as? Int) ?? 5000
@@ -458,6 +485,8 @@ class ExplorerTests: XCTestCase {
         return false
     }
 
+    private var backTitleHistory: [String] = []
+
     private func sessionTapById(_ identifier: String) -> String {
         var existedButNotHittable = false
         var existedButDisabled = false
@@ -750,14 +779,165 @@ class ExplorerTests: XCTestCase {
         return ("still_on_login", errTexts.prefix(2).joined(separator: " | "))
     }
 
-    private func sessionBack() {
-        let backButton = app.navigationBars.buttons.firstMatch
-        if backButton.exists && backButton.isHittable {
-            backButton.tap()
-        } else {
-            app.coordinate(withNormalizedOffset: CGVector(dx: 0, dy: 0.5))
-                .press(forDuration: 0.05, thenDragTo: app.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5)))
+    /// Go back and PROVE it: a caller that believes a no-op navigated keeps driving the wrong
+    /// screen (field issue #10 — four "ok" backs in a row while the title never changed, then
+    /// every following tap failed `not_hittable` because the pushed screen was still on top).
+    /// Returns "ok" only when the screen actually changed; "no_effect" otherwise.
+    /// A surface the SYSTEM owns even though it renders inside the app process: the share sheet
+    /// (`UIActivityContentView`) and the app extensions it hosts, the photo picker's unavailable
+    /// view, and other remote-view hosts. Their content belongs to Apple or a third-party
+    /// extension, so an empty or unreadable accessibility tree there says nothing about the app
+    /// under test — scoring it produced this app's only "high" finding (field issue #4).
+    private func systemSurfaceName(_ elements: [SimpleElement], title: String) -> String? {
+        let markers = ["UIActivityContentView", "ActivityListView", "PUPickerUnavailableView",
+                       "RemoteViewBridge", "_UIRemoteView", "UIDocumentPickerViewController",
+                       "SFSafariView", "UIActivityGroupView"]
+        for element in elements {
+            let signature = element.type + " " + element.identifier + " " + element.label
+            if let hit = markers.first(where: { signature.contains($0) }) { return hit }
+        }
+        // The share sheet hands off to an extension whose whole UI is out of process; the title
+        // is then the extension's name over a tree the app cannot see.
+        if title == "UIActivityContentView" { return "UIActivityContentView" }
+        return nil
+    }
+
+    /// iOS labels a pushed screen's back button with the PARENT screen's title ("Todo List"),
+    /// not "Back", so a back control cannot be recognised by its own label alone. Remember the
+    /// titles we have actually been on; a leading navigation-bar button named after one of them
+    /// is a genuine back control, while a custom leading action (Share, Delete) is not.
+    private func noteNavigationTitle() {
+        let title = app.navigationBars.firstMatch.identifier
+        guard !title.isEmpty, backTitleHistory.last != title else { return }
+        backTitleHistory.append(title)
+        if backTitleHistory.count > 20 { backTitleHistory.removeFirst() }
+    }
+
+    /// Leave a system-owned surface. A share sheet is a presented sheet, not a pushed screen:
+    /// `back` does nothing and a mid-screen swipe scrolls its content instead of dismissing it.
+    /// Try its real affordances in order, and say honestly whether we actually got out.
+    private func dismissSystemSurface(currentTitle: String) -> Bool {
+        let stillThere = { () -> Bool in
+            let elements = self.readUITree(self.app)
+            return self.systemSurfaceName(elements, title: self.detectTitle(elements) ?? "Unknown") != nil
+        }
+        // 1. An explicit dismissal control, in the app and in SpringBoard (extensions live there).
+        for label in ["Close", "Cancel", "Done", "Dismiss"] {
+            for candidate in [app.buttons[label], XCUIApplication(bundleIdentifier: "com.apple.springboard").buttons[label]] {
+                if candidate.exists && candidate.isHittable {
+                    candidate.tap()
+                    waitForUIStability(timeout: 1.5)
+                    if !stillThere() { return true }
+                }
+            }
         }
+        // 2. Drag the sheet down by its top edge (the grabber), not from the middle.
+        app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.35))
+            .press(forDuration: 0.1, thenDragTo: app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.98)))
+        waitForUIStability(timeout: 1.5)
+        if !stillThere() { return true }
+        // 3. Tap the dimmed backdrop above the sheet.
+        app.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.06)).tap()
+        waitForUIStability(timeout: 1.5)
+        if !stillThere() { return true }
+        // 4. Last resort: relaunch. The surface belongs to iOS; the app is still healthy.
+        app.terminate()
+        Thread.sleep(forTimeInterval: 0.8)
+        app.launch()
+        _ = app.wait(for: .runningForeground, timeout: 10)
+        waitForUIStability(timeout: 2.0)
+        return !stillThere()
+    }
+
+    /// iOS renders "Save Password?", location prompts and similar sheets in SpringBoard, not in
+    /// the app under test, so an app-scoped query silently matches something else. Tap the real
+    /// button when a system sheet is up (field issue #6).
+    private func tapSystemSheetButton(_ identifier: String) -> Bool {
+        let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")
+        for query in [springboard.buttons, springboard.staticTexts] {
+            let element = query[identifier]
+            if element.exists && element.isHittable { element.tap(); return true }
+        }
+        let matches = springboard.descendants(matching: .any)
+            .matching(NSPredicate(format: "label ==[c] %@", identifier)).allElementsBoundByIndex
+        if let match = matches.first(where: { $0.exists && $0.isHittable }) { match.tap(); return true }
+        return false
+    }
+
+    private func sessionBack() -> String {
+        let beforeElements = readUITree(app)
+        let beforeTitle = detectTitle(beforeElements) ?? "Unknown"
+        let beforeHash = computeHash(beforeElements)
+
+        // ONLY a real back affordance counts. Tapping `navigationBars.buttons.firstMatch` meant
+        // that on a screen with no back button, `back` fired whatever toolbar action happened to
+        // come first — observed live: it tapped Share, opened the share sheet, saw the screen
+        // change and reported "ok". A back that performs an unrelated (possibly destructive)
+        // action is worse than one that does nothing.
+        let isBackAffordance = NSPredicate(format:
+            "label ==[c] 'Back' OR label BEGINSWITH[c] 'Back to' OR identifier ==[c] 'BackButton' OR identifier CONTAINS[c] 'back-button'")
+        var backControls = app.buttons.matching(isBackAffordance).allElementsBoundByIndex
+        if backControls.first(where: { $0.exists && $0.isHittable }) == nil {
+            // The standard iOS back button: the navigation bar's leading control, labelled with
+            // a screen we have already been on. A leading button named anything else (Share,
+            // Delete) is an app action, not a back, and must never be tapped by `back`.
+            // The navigation bar's leading control. Recognising it cannot depend on the nav-bar
+            // identifier being readable (that varies by iOS version), so accept three shapes of
+            // the standard back button — named after a screen we have been on, named after the
+            // current screen (a detail view that inherits its parent's title), or a bare chevron
+            // with no label — while never accepting a named app action.
+            let appActionLabels: Set<String> = ["share", "delete", "remove", "add", "edit", "save",
+                                                "done", "cancel", "close", "more", "sign out",
+                                                "log out", "settings", "search", "filter", "menu"]
+            let leading = app.navigationBars.buttons.allElementsBoundByIndex.first
+            if let leading, leading.exists, leading.isHittable,
+               !appActionLabels.contains(leading.label.lowercased()),
+               backTitleHistory.contains(leading.label) || leading.label == beforeTitle || leading.label.isEmpty {
+                backControls = [leading]
+            }
+        }
+        guard let back = backControls.first(where: { $0.exists && $0.isHittable }) else {
+            // No back affordance: say so, and do nothing. The edge-swipe fallback used to run
+            // here and it was not a back — on a screen whose content scrolls sideways the drag
+            // landed in the content and navigated FORWARD ("Dashboard" → "What's New"), which
+            // `back` then reported as a successful pop. A caller who wants the gesture can ask
+            // for it explicitly with `swipe`.
+            print("OCQA_STATE:back_check before=\(beforeTitle) control=none")
+            return "no_effect"
+        }
+        let backLabel = back.label
+        // The CONTROLS on screen are the evidence a pop happened. Re-reading the tapped element
+        // does not work: XCUIElement is a lazy query, so `back.exists` after the tap re-resolves
+        // "the navigation bar's first button" against the NEW screen and finds whatever leads it
+        // there — so a successful pop looked like the control was still present. Titles do not
+        // work either: a detail view that inherits its parent's title reads the same on both
+        // sides. A pop replaces the screen's controls, and that is what we compare.
+        let controlLabels = { (elements: [SimpleElement]) -> Set<String> in
+            Set(elements.filter { self.isInteractable($0.type) && $0.isEnabled }
+                .map { self.normalizeVisibleText($0.label) }
+                .filter { !$0.isEmpty })
+        }
+        let beforeControls = controlLabels(beforeElements)
+        back.tap()
+        waitForUIStability(timeout: 1.5)
+        let afterElements = readUITree(app)
+        let afterTitle = detectTitle(afterElements) ?? "Unknown"
+        let afterControls = controlLabels(afterElements)
+        // Two or more controls differing is a screen change; one is ordinary content churn.
+        let changedControls = beforeControls.symmetricDifference(afterControls).count
+        print("OCQA_STATE:back_check before=\(beforeTitle) after=\(afterTitle) control=\(backLabel) changedControls=\(changedControls)")
+        if changedControls >= 2 { return "ok" }
+        // Navigation is a change of SCREEN, and the screen's identity is its title. A raw tree
+        // hash is too sensitive to be evidence of it: a dashboard with delayed content or a
+        // relative timestamp changes hash on its own, which made a no-op back at a root screen
+        // look like a successful pop (observed on the corpus app). Fall back to the hash only
+        // when neither read produced a title to compare.
+        // Observability: a back that reports the wrong thing is invisible without this.
+        if afterTitle != beforeTitle { return "ok" }
+        if beforeTitle == "Unknown" && afterTitle == "Unknown" {
+            return computeHash(afterElements) != beforeHash ? "ok" : "no_effect"
+        }
+        return "no_effect"
     }
 
     /// Replays an explicit, config-driven login flow (OCQA_LOGIN_STEPS) before exploration — for the
@@ -848,6 +1028,7 @@ class ExplorerTests: XCTestCase {
             let taskName = (raw["__tappTask"] as? [String: Any])?["name"] as? String ?? ""
             // A step is either {action: value} sugar or {action:..., target/value/...}. Normalize.
             let (action, step) = normalizeFlowStep(raw)
+            noteNavigationTitle() // navigation history, so `back` can recognise its control
             let target = subst((step["target"] as? String) ?? "")
             let value = subst((step["value"] as? String) ?? "")
             let timeoutMs = (step["timeoutMs"] as? Int) ?? (step["timeout"] as? Int) ?? flowDefaultTimeoutMs
@@ -888,7 +1069,11 @@ class ExplorerTests: XCTestCase {
             case "swipe":
                 switch target.lowercased() { case "down": app.swipeDown(); case "left": app.swipeLeft(); case "right": app.swipeRight(); default: app.swipeUp() }
             case "back":
-                _ = tryGoBack()
+                // Same rule as the session (#10): a back that did not navigate is a failed step,
+                // not a silent pass — the rest of the Flow would otherwise run against the wrong
+                // screen and fail somewhere unrelated.
+                status = sessionBack() == "ok" ? "pass" : "fail"
+                if status == "fail" { detail = "back did not navigate: no back control on this screen, or tapping it did not change the screen\(visibleLabelsHint())" }
             case "wait":
                 Thread.sleep(forTimeInterval: Double(timeoutMs) / 1000.0)
             case "wait_for":
@@ -933,6 +1118,20 @@ class ExplorerTests: XCTestCase {
             print("OCQA_FLOW_STEP:{\"index\":\(idx),\"action\":\"\(escapeJSON(action))\",\"target\":\"\(escapeJSON(target.isEmpty ? value : target))\",\"assert\":\(isAssert),\"status\":\"\(status)\",\"detail\":\"\(escapeJSON(detail))\"\(taskEvidence)\(contractEvidence)}")
             if status == "fail" {
                 failed += 1
+                // Web and Android flows write flow-failure-N.png next to the log; iOS buried the
+                // evidence in the .xcresult, so seeing the failing screen needed a second run
+                // (field issue #8). Write the same file, and keep the XCTest attachment too.
+                let failureShot = app.screenshot()
+                let failureAttachment = XCTAttachment(screenshot: failureShot)
+                failureAttachment.name = "flow_failure_\(idx)"
+                failureAttachment.lifetime = .keepAlways
+                add(failureAttachment)
+                let evidenceDir = resolve("OCQA_FLOW_EVIDENCE_DIR")
+                if !evidenceDir.isEmpty {
+                    let destination = URL(fileURLWithPath: evidenceDir).appendingPathComponent("flow-failure-\(idx).png")
+                    try? FileManager.default.createDirectory(at: URL(fileURLWithPath: evidenceDir), withIntermediateDirectories: true)
+                    try? failureShot.pngRepresentation.write(to: destination)
+                }
                 // A failed step surfaces as a finding, with the same shape QA findings use.
                 let screen = detectTitle(readUITree(app)) ?? "Unknown"
                 print("OCQA_ISSUE:{\"type\":\"flow_assertion_failed\",\"severity\":\"high\",\"title\":\"\(escapeJSON("Step \(idx) (\(action)) failed: \(detail)"))\",\"screen\":\"\(escapeJSON(screen))\",\"step\":\(idx)}")
@@ -1433,6 +1632,7 @@ class ExplorerTests: XCTestCase {
         // defect (field issue #9: "Personal Info ↔ back" filed as a finding). Remember when we
         // last navigated backwards so the loop detector can tell the two apart.
         var lastExplorerBackStep = -99
+        var systemSurfaceEscapes = 0
         while actionCount < maxActions {
             // Subtract time spent paused for interactive input so human typing never eats the budget.
             if Date().timeIntervalSince(startTime) - totalWaitSeconds > timeoutSeconds {
@@ -1780,6 +1980,31 @@ class ExplorerTests: XCTestCase {
                 )
             }
 
+            // ---- System-owned surface: catalogue, back out, never score ----
+            // The share sheet and the extensions it hosts run inside the app process, so the
+            // left-app detector (which watches the frontmost process) cannot see them. Their
+            // tree is Apple's or a third party's, not the app's: report the handoff as an
+            // observation and leave, instead of filing blank/limited findings against it.
+            if let systemSurface = systemSurfaceName(elements, title: titleStr) {
+                let surfaceKey = "system_surface:\(systemSurface)"
+                if !reportedIssueKeys.contains(surfaceKey) {
+                    reportedIssueKeys.insert(surfaceKey)
+                    print("OCQA_ACTION:{\"type\":\"system_surface\",\"target\":\"\(escapeJSON(systemSurface))\",\"screen\":\"\(escapedTitle)\",\"step\":\(actionCount),\"narrative\":\"\(escapeJSON("Reached \(systemSurface), a system-owned surface — its content belongs to iOS, not the app under test. Backing out."))\"}")
+                }
+                actionCount += 1
+                systemSurfaceEscapes += 1
+                let escaped = dismissSystemSurface(currentTitle: titleStr)
+                // Never let a surface we refuse to explore eat the whole budget: a share sheet
+                // that will not dismiss is a dead end for the run, not a reason to keep trying.
+                if !escaped && systemSurfaceEscapes >= 3 {
+                    print("OCQA_STATE:system_surface_unrecoverable screen=\(escapedTitle) step=\(actionCount)")
+                    explorationStopCause = "system-surface-unrecoverable"
+                    break
+                }
+                emitProgress(action: actionCount, maxActions: maxActions, states: visitedStates.count)
+                continue
+            }
+
             // Screenshot
             let screenshot = app.screenshot()
             let attachment = XCTAttachment(screenshot: screenshot)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.16",
+  "version": "0.17.18",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Let coding agents verify UI changes on real iOS, Android, and web surfaces, then enforce reviewed proof in deterministic CI.",
   "license": "MIT",

package/scripts/run-flow.sh

@@ -48,12 +48,15 @@ case "$FLOW" in
   *) FLOW_EVIDENCE_SOURCE="$EVIDENCE_DIR/flow-source.yml" ;;
 esac
 cp "$FLOW" "$FLOW_EVIDENCE_SOURCE"
-python3 - "$CFG" "$APP" "$FLOW_JSON" "$AI_RESP" "$AI_DIR" <<'PY'
+TAPP_FLOW_EVIDENCE_DIR_RESOLVED="$EVIDENCE_DIR" python3 - "$CFG" "$APP" "$FLOW_JSON" "$AI_RESP" "$AI_DIR" <<'PY'
 import json, os, sys
 cfg, app, flow_json, ai_resp, ai_dir = sys.argv[1:6]
 d = {
   "OCQA_BUNDLE_ID": app,
   "OCQA_FLOW_JSON": flow_json,
+  # Where the harness writes per-step failure screenshots, so iOS flow evidence matches web
+  # and android instead of living only inside the .xcresult (field issue #8).
+  "OCQA_FLOW_EVIDENCE_DIR": os.environ.get("TAPP_FLOW_EVIDENCE_DIR_RESOLVED", ""),
   "OCQA_TEST_EMAIL": os.environ.get("OCQA_TEST_EMAIL", "test@example.com"),
   "OCQA_TEST_PASSWORD": os.environ.get("OCQA_TEST_PASSWORD", "TestPass123!"),
 }