apple-tester

# Apple Tester Skill ## Purpose `apple-tester` is a tester harness, not an autonomous runtime. Default usage is direct command execution + dev watch loop. Use server mode only when you need persistent session state or streamed logs. Use `apple-tester` as the only public entrypoint. Do not invoke `apple-driver` (or `agent-apple`) directly for daemon/session workflows. ## Strict loop Always run this loop: 1. `snapshot` 2. Plan one action 3. Execute one action 4. Verify with `is` / `get` / `assert` 5. Repeat Never run free-form multi-action plans without verification. ## Quick start If `apple-tester` is not on your PATH yet, install it once from the repo root: ```bash pnpm apple-tester:cli:install ``` ```bash apple-tester doctor --build-driver apple-tester server start apple-tester session start --macos apple-tester snapshot --json apple-tester tap @m1 apple-tester is visible @m1 apple-tester session stop apple-tester server stop ``` ## Host input safety macOS host-input gestures are blocked by default to avoid stealing local mouse/keyboard focus. Use `--allow-host-input` only for explicit gesture actions: ```bash apple-tester session start --macos --allow-host-input apple-tester hold @m1 --duration-ms 900 --allow-host-input apple-tester right-click @m3 --allow-host-input ``` ## iOS flow ```bash apple-tester server start apple-tester session start --ios --udid <SIM_UDID> apple-tester snapshot --json apple-tester tap @i1 apple-tester swipe --from 200,700 --to 200,250 apple-tester session stop apple-tester server stop ``` ## macOS gestures ```bash apple-tester hold @m1 --duration-ms 900 --allow-host-input apple-tester longpress --coords 640,380 --allow-host-input apple-tester right-click @m3 --allow-host-input apple-tester swipe --from 400,500 --to 900,500 --duration-ms 500 --allow-host-input ``` ## Promotion Promotion compiles a successful exploratory run into deterministic XCTest files and a promotion manifest: ```bash apple-tester promote --run-id <RUN_ID> --platform ios --name "Login Smoke" apple-tester promote --run-id <RUN_ID> --platform ios --name "Login Smoke" --dry-run --diff-lines 120 apple-tester promote --run-id <RUN_ID> --platform ios --name "Login Smoke" --dry-run --write-report ./artifacts/promotion-report.json ``` Output targets: - iOS: `apps/ios/UITests/Generated/*.swift` - macOS: `apps/macos/UITests/Generated/*.swift` ## Log streaming for agents For parser-friendly polling, prefer NDJSON log output: ```bash apple-tester logs --json --follow | jq -c '.entries[] | {seq, level, message}' ``` ## Canonical local development loop ```bash pnpm dev:watch ``` This performs deterministic change detection and targeted rebuilds without relaunching apps by default (`--no-relaunch`). ## Notes - `right-click` is macOS-only. - `hold`/`longpress` use press-and-hold semantics on macOS and best-effort equivalent on iOS. - Prefer accessibility identifiers in app code for stable promoted tests. - Use `apple-tester logs --follow` for live daemon diagnostics when actions fail. ## Technique Map - **Identify scope** — Determine what the skill applies to before executing. - **Follow workflow** — Use documented steps; avoid ad-hoc shortcuts. - **Verify outputs** — Check results match expected contract. - **Handle errors** — Graceful degradation when dependencies missing. - **Reference docs** — Load references/ when detail needed. - **Preserve state** — Don't overwrite user config or artifacts. ## Technique Notes Skill-specific technique rationale. Apply patterns from the skill body. Progressive disclosure: metadata first, body on trigger, references on demand. ## Prompt Architect Overlay **Role Definition:** Specialist for apple-tester domain. Executes workflows, produces artifacts, routes to related skills when needed. **Input Contract:** Context, optional config, artifacts from prior steps. Depends on skill. **Output Contract:** Artifacts, status, next-step recommendations. Format per skill. **Edge Cases & Fallbacks:** Missing context—ask or infer from workspace. Dependency missing—degrade gracefully; note in output. Ambiguous request—clarify before proceeding.