Use
Troubleshooting & FAQ
| Symptom | Fix |
|---|---|
iOS: SimulatorKit not found … / … has no Indigo HID builders | Run looktap doctor. Point xcode-select at a full Xcode: sudo xcode-select -s /Applications/Xcode.app |
iOS: input unavailable (dtuhid): dtuhidd did not answer | The simulator is still booting, or its input service is restarting. Retry in a few seconds |
iOS: an element you can see is missing from ls | Some containers hide their children from accessibility. looktap probes for them, but tapxy is the fallback |
only the status bar is readable — a system prompt … may be covering the app | A passcode, permission or alert prompt drawn by iOS. looktap shot to see it |
both iOS and Android devices are up — pass -p ios|android | Add -p, or export LOOKTAP_PLATFORM=… |
not found: <label> | Run looktap ls and copy the label. If the screen is slow to load, raise --wait |
"<label>" is ambiguous — matches N labels | Use more of the label, a @ref, or --exact |
keyboard is still up (iOS) | Search keyboards have no Done key. Tap the screen's Cancel/close control |
Android ls fails right after boot | Wait until adb shell getprop sys.boot_completed prints 1 |
Android ls fails after Appium was used | Appium still holds UiAutomation: adb shell am force-stop io.appium.uiautomator2.server |
Appium / uiautomator fail after looktap was used | looktap's helper holds UiAutomation: looktap -p android teardown |
Android helper did not start — falling back to uiautomator dump | Something else holds UiAutomation (see above). looktap keeps working, just slower |
| Android keyboard never appears | Set hw.keyboard = no in the AVD's config.ini, then cold-boot the emulator |
| Android screenshot is black | That screen is FLAG_SECURE: use shot without --plain on an emulator. System PIN and biometric sheets stay black in every mode |
| App sits on the splash screen (Android, React Native) | Metro isn't reachable: looktap setup (adds adb reverse tcp:8081), make sure Metro runs, then looktap launch |
launch says no launchable activity | The app isn't installed or the id is wrong: adb shell pm list packages, or xcrun simctl listapps booted |
FAQ
Is this a test framework?
No. It has no assertions, spec files or reporters. It's for looking at and using an app: by an agent while it builds a feature, by you while you debug, or in a script that sweeps screenshots. Checks that should run on every build belong in your app's own test suite (XCTest, Espresso, Detox, Maestro, …).
Does it work on a real iPhone?
Yes. looktap installs a small XCUITest runner on it, signed with your own Apple ID (a free one works). See Using a real iPhone for the one-time setup and what works there.
On Android it works with emulators and with USB-debugging devices. (On a device, screenshots go through the
device, so FLAG_SECURE screens are black.)
Does it install anything on my device or in my app?
Nothing on the iOS simulator. On Android it copies an 8 KB helper to /data/local/tmp and runs it with
app_process, the way scrcpy does. No APK is installed, no app is modified, and there's no SDK to add to your app.
looktap teardown stops the helper.
Does it work with React Native, Flutter, SwiftUI, Compose, web views?
It reads the platform accessibility tree, so anything that exposes accessibility labels works. That includes React
Native (it was built while driving RN apps), SwiftUI, UIKit, Compose and Views. It also reads web content in
Safari, in-app browsers and web views. Flutter isn't tested yet: it exposes elements through its semantics tree,
so it should work wherever that is enabled. Elements without a label show as (no label) and can be tapped by @ref.
Linux or Windows?
iOS needs a Mac. The Android side is plain Node + adb and should work anywhere they do. It's developed and tested
on macOS.
Will an Xcode update break it?
It can. The iOS helper uses private simulator frameworks, like idb does. looktap doctor tells you if something
it needs has moved. Reading the screen and screenshots have held steady. Input changed in Xcode 27, and looktap
already has a path for that, though it isn't tested yet.
Can my agent sign in to my app with it?
It can type, but it shouldn't type real credentials. Have a person sign in (and enter OTPs), then let the agent continue. The skill tells agents exactly that. See Safety rules.
Generated from README.md. Edit it there.