prowl-tools 0.1.4 → 0.1.5

package/NOTICE

@@ -12,6 +12,16 @@ attributions are provided for the benefit of downstream users.
 Direct Runtime Dependencies
 -------------------------------------------------------------------------------
 
+appium-uiautomator2-server
+  License: Apache-2.0
+  Copyright (c) Appium Contributors
+  https://github.com/appium/appium-uiautomator2-server
+
+appium-webdriveragent
+  License: Apache-2.0
+  Copyright (c) Appium Contributors
+  https://github.com/appium/WebDriverAgent
+
 chalk
   License: MIT
   https://github.com/chalk/chalk

package/README.md

@@ -55,6 +55,29 @@ Prowl uses Playwright under the hood. Install the browser:
 npx playwright install chromium
 ```
 
+The on-device agents for the experimental Android/iOS targets
+(`appium-uiautomator2-server`, `appium-webdriveragent`) are **optional
+dependencies** — installed by default so mobile testing works out of the box,
+but skippable for a leaner web-only install:
+
+```bash
+npm install -g prowl-tools --omit=optional
+```
+
+If a mobile target later needs an omitted agent, it fails with exact recovery
+commands for global and local installs. For a global npm install, restore the
+agents with:
+
+```bash
+npm install -g appium-uiautomator2-server@10.6.2 appium-webdriveragent@16.4.0
+```
+
+For a local project install, omit `-g`:
+
+```bash
+npm install appium-uiautomator2-server@10.6.2 appium-webdriveragent@16.4.0
+```
+
 ### 2. Initialize
 
 ```bash
@@ -424,11 +447,21 @@ Config lives at `.prowl/config.yml`. All options with defaults:
 ```yaml
 # Execution target. Defaults to the web target; existing configs work unchanged.
 target:
-  type: "web"                         # "web" (default) or "macos" (experimental)
+  type: "web"                         # "web" (default), "macos", "android", or "ios" (experimental)
   url: "http://localhost:3000"        # Required for web targets
   # For the experimental macOS target instead:
   #   type: "macos"
   #   app: "com.example.App"          # bundle id or /path/to/App.app  (see "macOS Target")
+  # For the experimental Android target instead:
+  #   type: "android"
+  #   app: "com.example.app"          # package name or /path/to/app.apk  (see "Android Target")
+  #   deviceSerial: "emulator-5554"   # optional; required only with several devices attached
+  #   coldStart: false                # optional; pm clear before launch
+  # For the experimental iOS simulator target instead:
+  #   type: "ios"
+  #   app: "com.example.App"          # bundle id or /path/to/App.app  (see "iOS Target")
+  #   udid: "..."                     # optional; required only with several booted simulators
+  #   coldStart: false                # optional; uninstall+reinstall before launch (needs a .app)
 
 # Browser settings
 browser:
@@ -458,7 +491,7 @@ guardrails:
   forbiddenSelectors:                  # selectors that steps cannot use
     - "[data-danger]"
     - ".delete-btn"
-  allowedApps: []                      # macOS target only: bundle IDs, bundle names, or .app paths
+  allowedApps: []                      # native targets only: macOS bundle IDs/names/.app paths, Android package IDs/canonical APK paths, or iOS bundle IDs/.app paths
 
 # Auth state from `prowl login`
 auth:
@@ -985,6 +1018,52 @@ Native selectors address accessibility identifiers, roles, and labels:
 semantics as the web target). Prefer `id=` (accessibility identifiers) — the native
 analog of `data-testid`.
 
+### Finding selectors
+
+Don't guess selectors — dump them. `prowl analyze` works on the macOS target the
+same way it does on the web: it launches/attaches to the app, walks the
+Accessibility tree, and prints every interactive element with **ranked selector
+candidates** (best first) plus the app's windows and status-item menu contents.
+It is read-only (the only interaction is opening and closing the status menu),
+honors `guardrails.allowedApps`, and leaves the app running when done.
+
+```bash
+# Uses the macOS target from .prowl/config.yml:
+prowl analyze
+
+# …or point it at any app without a config:
+prowl analyze --app com.example.App
+prowl analyze --app "/Applications/Example.app"
+
+# Machine-readable output for agents:
+prowl analyze --app com.example.App --json
+```
+
+Example (human-readable) output:
+
+```text
+  App Analysis: com.example.App
+
+  Windows:
+    "Main Window" id=mainWindow
+
+  Interactive Elements:
+    AXButton id=saveButton "Save"
+    AXTextField label="Email" "Email"
+    AXCheckBox label="Remember me" "Remember me" (disabled)
+
+  Menu Bar:
+    AXMenuItem id=preferences "Preferences…"
+    AXMenuItem label="Quit" "Quit"
+
+  3 elements, 1 windows, 2 menu items
+```
+
+Selectors are ranked `id=` > `label=` > `role=…[name="…"]` > `text=` — copy the
+first (most durable) candidate into your hunt. Status-item menu identifiers
+(`id=preferences` above) are especially valuable, since menu titles often carry
+ellipses or localized text that are awkward to match by substring.
+
 ### Step compatibility
 
 Portable steps run on **both** targets; web-only steps are rejected up front on the
@@ -1009,6 +1088,202 @@ after the run.
 
 ---
 
+## Android Target (Experimental)
+
+> **Experimental (PROWL-058).** Prowl can drive **native Android apps** on an
+> emulator or a USB-connected device, in addition to the web and macOS targets.
+> It follows the same "external agent + JSON protocol" shape as the macOS target:
+> `adb` handles device lifecycle and the on-device
+> [`appium-uiautomator2-server`](https://github.com/appium/appium-uiautomator2-driver)
+> (Apache-2.0) handles UI interaction over a plain HTTP/JSON API driven with raw
+> `fetch`. The API, selector dialect, and step coverage may change.
+
+### Requirements
+
+- **`adb`** on your `PATH` (from the Android SDK platform-tools), plus at least
+  one **booted emulator or device** (`adb devices -l` should list it as `device`).
+- The two prebuilt agent APKs ship inside the `appium-uiautomator2-server` npm
+  dependency and are installed onto the device automatically — **nothing to build**.
+  No Appium server, no JVM, no gRPC.
+- If `target.app` is an **`.apk`**, Android build-tools **`aapt`/`aapt2`** must be
+  on `PATH` so Prowl can read the package name (or set `target.app` to the package
+  name directly and install the APK yourself).
+
+### Enabling it
+
+Point your config at an Android target:
+
+```yaml
+target:
+  type: android
+  app: "com.example.app"        # a package name, or a path to an .apk to install
+  # deviceSerial: "emulator-5554"  # required only when several devices are attached
+  # coldStart: true                # `pm clear` before launch for a deterministic start (default off)
+guardrails:
+  allowedApps:                     # optional scope; empty = allow the target app
+    - "com.example.app"
+```
+
+Then run a hunt as usual: `prowl run my-android-hunt`.
+
+On launch Prowl selects the device (failing with an actionable error, listing
+serials, if several are attached and no `deviceSerial` is set), installs the app
+(when given an `.apk`) and the agent, starts the agent via `am instrument`,
+port-forwards it on a **dynamically allocated** local port (so parallel sessions /
+CI jobs don't collide), and waits for the agent to report ready. Everything is
+torn down (agent session, instrumentation, port forward, `am force-stop`) after
+the run. `guardrails.allowedApps` accepts Android package IDs or canonical full
+`.apk` paths; when `target.app` is an APK, Prowl resolves its package ID and
+validates it before installing.
+
+### Selector dialect (Android)
+
+Native selectors address `resource-id`, `content-desc`, visible text, and widget
+class. Semantics match the macOS target so a selector means the same thing on both
+native targets:
+
+| Selector | Matches |
+|---|---|
+| `id=save` | element whose `resource-id` is `save` — a bare name is auto-qualified with the target app's package (`com.pkg:id/save`); ids in other namespaces need the full form (e.g. `id=android:id/title`) |
+| `label="Submit"` | element whose `content-desc` equals `Submit` (exact) |
+| `role=android.widget.Button` | element of that widget class |
+| `role=android.widget.Button[name="Save"]` | that widget class whose visible text contains `Save` |
+| `text="Save"` or bare `Save` | element whose visible text contains the text (substring) |
+
+Prefer `id=` (the native analog of `data-testid`). **Jetpack Compose caveat:**
+Compose nodes only expose a `resource-id` when the app sets
+`Modifier.testTag(...)` **and** enables `testTagsAsResourceId = true`; otherwise
+match Compose UI with `text=` or `label=` (from `Modifier.semantics { contentDescription = ... }`).
+`forbiddenSelectors` still applies (text patterns use the same substring semantics
+as the other targets).
+
+### Step compatibility
+
+Portable steps run on the Android target; web-only steps are rejected up front
+(with a clear error), and `prowl login` / URL guardrails do not apply.
+
+| Portable (Android) | Not supported on Android |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute`, `evalScript`, `runScript` |
+| `assert: visible` / `notVisible` | `onDialog`, `select` / `selectOption`, `setInputFiles` |
+| `screenshot`, `assertScreenshot` | `waitForDownload`, `scroll`, `assert: urlIncludes` / `urlEquals` |
+| `repeat`, `if`, `runHunt`, `copyText` | `hover`, `scrollTo` (no touch equivalent yet — see below) |
+
+Notes: `type` and `fill` set text on the focused / matched field **unicode-safely**
+(via the agent's `element/value`, not `adb shell input text`); `press` maps key
+names (`Enter`, `Tab`, `Backspace`, `Back`, `Home`, arrow keys, …) onto Android key
+codes and dispatches them to the focused view. `hover` and `scrollTo` have no touch
+equivalent yet and are rejected with a clear message; scroll-gesture support is a
+follow-up. A degraded pure-`adb` fallback (`uiautomator dump` + `input tap`) is a
+possible future diagnostic mode, not the primary path.
+
+> Out of scope for PROWL-058 (tracked separately): `prowl analyze` for Android and
+> CI recipes (PROWL-061), the unified native selector engine (PROWL-060), and real
+> iOS devices (PROWL-062). The iOS **simulator** target ships below.
+
+---
+
+## iOS Target (Experimental)
+
+> **Experimental (PROWL-059).** Prowl can drive **native iOS apps** on a **booted
+> iOS Simulator**, in addition to the web, macOS, and Android targets. It follows
+> the same "external agent + JSON protocol" shape: `xcrun simctl` handles simulator
+> lifecycle and screenshots, and the on-simulator
+> [WebDriverAgent](https://github.com/appium/WebDriverAgent) (Apache-2.0) handles UI
+> interaction over its W3C-shaped HTTP/JSON API driven with raw `fetch`. The API,
+> selector dialect, and step coverage may change. **Real devices are out of scope**
+> (PROWL-062) — simulators only.
+
+### Requirements
+
+- **macOS with a full Xcode** (not just the command-line tools) installed and
+  selected (`xcode-select -p`), so `xcrun simctl` and `xcodebuild` are available.
+- At least one **booted simulator** (`xcrun simctl list devices | grep Booted`, or
+  boot one with `xcrun simctl boot <udid>` / from Xcode).
+- The **WebDriverAgent** runner is built **once** from the `appium-webdriveragent`
+  npm dependency (`xcodebuild build-for-testing`) and cached under
+  `~/.prowl/wda/<wda-version>-xcode<xcode-version>/`; the first run prints a one-time
+  "building WebDriverAgent…" notice and can take a few minutes. Simulators need **no
+  code signing**. Set `PROWL_WDA_RUNNER` to a prebuilt `WebDriverAgentRunner-Runner.app`
+  to skip the build (e.g. in CI with a cached runner).
+
+### Enabling it
+
+Point your config at an iOS target:
+
+```yaml
+target:
+  type: ios
+  app: "com.example.App"          # a bundle id, or a path to a built .app to install
+  # udid: "ABCD-1234"                # required only when several simulators are booted
+  # coldStart: true                  # uninstall+reinstall before launch (requires a .app path)
+guardrails:
+  allowedApps:                       # optional scope; empty = allow the target app
+    - "com.example.App"
+```
+
+Then run a hunt as usual: `prowl run my-ios-hunt`.
+
+On launch Prowl selects the booted simulator (failing with an actionable error,
+listing candidates, if several are booted and no `udid` is set), installs the app
+(when given a `.app`, reading its bundle id from the bundle's **root** `Info.plist`),
+builds/caches and installs the WebDriverAgent runner, launches it on a
+**dynamically allocated** port (passed via `SIMCTL_CHILD_USE_PORT` so parallel
+sessions / CI jobs don't collide), launches the target app, and waits for WDA to
+report ready. Everything is torn down (WDA session, `simctl terminate` of the runner
+and the app) after the run. `guardrails.allowedApps` accepts iOS bundle ids or
+`.app` paths; a `.app` path is authorized by its path, bundle name, or the bundle id
+read from its root `Info.plist`. Note: a bare `target.app` ending in `.app` is
+treated as a **bundle id** unless a directory of that name exists, so bundle ids like
+`com.company.app` are not mistaken for paths.
+
+### Selector dialect (iOS)
+
+Native selectors address accessibility ids, labels, visible text, and element type.
+Semantics match the macOS/Android targets so a selector means the same thing across
+native targets:
+
+| Selector | Matches |
+|---|---|
+| `id=save` | element whose accessibility id (`accessibilityIdentifier` / name) is `save` |
+| `label="Submit"` | element whose `accessibilityLabel` equals `Submit` (exact) |
+| `role=XCUIElementTypeButton` | element of that type (shorthand `role=Button` works too) |
+| `role=Button[name="Save"]` | that type whose visible `label`/`value` contains `Save` |
+| `text="Save"` or bare `Save` | element whose `label` or `value` contains the text (substring) |
+| `:focus` | the element with keyboard focus (`hasKeyboardFocus == 1`) |
+
+Prefer `id=` (set `accessibilityIdentifier` in your app — the native analog of
+`data-testid`). Text/label/role+name selectors compile to WDA NSPredicate strings
+(quotes and backslashes are escaped). `forbiddenSelectors` still applies.
+
+### Step compatibility
+
+Portable steps run on the iOS target; web-only steps are rejected up front (with a
+clear error), and URL guardrails do not apply.
+
+| Portable (iOS) | Not supported on iOS |
+|---|---|
+| `click`, `fill`, `type`, `press` | `navigate`, `waitForUrl`, `waitForNetworkIdle` |
+| `wait`, `waitForSelector` | `mockRoute` / `unmockRoute`, `evalScript`, `runScript` |
+| `assert: visible` / `notVisible` | `onDialog`, `select` / `selectOption`, `setInputFiles` |
+| `screenshot`, `assertScreenshot` | `waitForDownload`, `scroll`, `assert: urlIncludes` / `urlEquals` |
+| `repeat`, `if`, `runHunt`, `copyText` | `hover`, `scrollTo` (no touch equivalent yet) |
+
+Notes: `type` and `fill` set text on the focused / matched field via WDA's
+`element/value`; `press` supports a small honest key set — `enter`/`return` and
+`delete`/`backspace` (sent through WDA's key endpoint to the focused element) and
+`home` (returns to the springboard) — and rejects other keys with the supported-keys
+message. Screenshots are captured with `simctl` (not WDA), so artifacts still work
+even if the agent wedges. `hover` and `scrollTo` have no touch equivalent yet and are
+rejected with a clear message; scroll-gesture support is a follow-up.
+
+> Out of scope for PROWL-059 (tracked separately): `prowl analyze` for iOS and CI
+> recipes (PROWL-061), the unified native selector engine (PROWL-060), and real iOS
+> devices (PROWL-062).
+
+---
+
 ## Troubleshooting
 
 ### "Could not find .prowl/config.yml"