qualiow-exploratory-testing 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/README.md +85 -0
  2. package/bin/mcli +16 -0
  3. package/bin/mobile-cli.mjs +573 -0
  4. package/bin/wadb +6 -0
  5. package/bin/wk-ios +58 -0
  6. package/bin/wkeval.mjs +44 -0
  7. package/data/knowledge/learned-patterns.md +85 -0
  8. package/data/knowledge/manifest.yml +2 -1
  9. package/data/targets/_example-mobile-emulation.yml +52 -0
  10. package/data/targets/_example-native-mobile.yml +61 -0
  11. package/data/targets/_example-sim-android-chrome.yml +81 -0
  12. package/data/targets/_example-sim-ios-safari.yml +80 -0
  13. package/dist/cli/index.js +156 -33
  14. package/dist/cli/index.js.map +1 -1
  15. package/dist/index.d.ts +260 -527
  16. package/dist/index.js +142 -12
  17. package/dist/index.js.map +1 -1
  18. package/docs/MOBILE-SETUP.md +92 -0
  19. package/package.json +23 -11
  20. package/scripts/doctor-mobile.sh +143 -0
  21. package/scripts/setup-mobile.sh +213 -0
  22. package/skills/qa-explore/phases/00-setup.md +8 -1
  23. package/skills/qa-explore/phases/01-auth.md +4 -0
  24. package/skills/qa-explore-mobile/SKILL.md +146 -0
  25. package/skills/qa-explore-mobile/phases/00-setup.md +203 -0
  26. package/skills/qa-explore-mobile/phases/01-auth.md +127 -0
  27. package/skills/qa-explore-mobile/phases/02-charter.md +70 -0
  28. package/skills/qa-explore-mobile/phases/03-discovery.md +79 -0
  29. package/skills/qa-explore-mobile/phases/04-journeys.md +49 -0
  30. package/skills/qa-explore-mobile/phases/05-features.md +72 -0
  31. package/skills/qa-explore-mobile/phases/06-edge-cases.md +157 -0
  32. package/skills/qa-explore-mobile/phases/07-reporting.md +123 -0
  33. package/skills/qa-explore-mobile/references/mobile-edges.md +117 -0
  34. package/skills/qa-explore-quick/SKILL.md +6 -0
@@ -0,0 +1,92 @@
1
+ # Mobile Setup — running `/qa-explore-mobile` on a fresh Mac
2
+
3
+ The mobile skill drives **real** simulator/emulator browsers and native apps via
4
+ `mobile-cli` (a Maestro / `xcrun simctl` / `adb` shim). Unlike the desktop web skill
5
+ (`/qa-explore`, which only needs `playwright-cli`), the mobile path depends on the iOS
6
+ and/or Android toolchains being installed on the machine. This guide gets a clean Mac to
7
+ the point where a session can start.
8
+
9
+ ## TL;DR
10
+
11
+ ```bash
12
+ # 1. Install everything scriptable + create standard devices (idempotent, re-runnable)
13
+ scripts/setup-mobile.sh # or --android / --ios, add --yes for non-interactive
14
+
15
+ # 2. Confirm the machine is ready (read-only; installs nothing)
16
+ scripts/doctor-mobile.sh
17
+
18
+ # 3. Run a mobile session (once doctor says READY)
19
+ # e.g. iOS Safari against your mobile web app:
20
+ # drive via bin/mcli — see the target config notes in data/targets/_example-sim-*.yml
21
+ ```
22
+
23
+ `scripts/setup-mobile.sh` automates everything it can and **prints clear MANUAL steps**
24
+ for the few things it can't (Xcode + the iOS runtime). It finishes by running the doctor.
25
+
26
+ ## What gets installed / created
27
+
28
+ | Component | Needed for | Auto by `setup-mobile.sh`? |
29
+ |-----------|-----------|----------------------------|
30
+ | Homebrew | base | ✅ (offers to install) |
31
+ | Node ≥ 18 | runs `mobile-cli.mjs` | ✅ |
32
+ | **Maestro** | the driver (hierarchy/tap/input) | ✅ (`get.maestro.mobile.dev`) |
33
+ | **JDK 17** | Android SDK tooling | ✅ `brew install openjdk@17` |
34
+ | Android cmdline-tools | `sdkmanager`/`avdmanager` | ✅ `brew install --cask android-commandline-tools` |
35
+ | platform-tools (`adb`), `emulator` | drive Android | ✅ `sdkmanager` |
36
+ | Google **Play** system image (API 35) | **Chrome must be present** | ✅ `sdkmanager` |
37
+ | SDK licenses | unblock installs | ✅ `sdkmanager --licenses` |
38
+ | Android AVD `qa_pixel_api35` | a device to boot | ✅ `avdmanager create avd` |
39
+ | **Xcode** + CLI tools | iOS simulators at all | ⚠️ **manual** (App Store, multi-GB) |
40
+ | iOS runtime | a simulator OS to run | ⚠️ **manual** if none installed (Xcode ▸ Settings ▸ Components) |
41
+ | iOS simulator device `qa-iphone` | a device to boot | ✅ `simctl create` (once Xcode + a runtime exist) |
42
+ | Safari / Chrome (the browsers) | web-mode SUT | ✅ preinstalled (Safari always; Chrome via the Play image) |
43
+
44
+ ### The two genuinely manual iOS steps
45
+ Xcode can't be reliably scripted:
46
+ ```bash
47
+ # After installing Xcode from the App Store:
48
+ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
49
+ sudo xcodebuild -license accept
50
+ # If no iOS runtime is installed:
51
+ xcodebuild -downloadPlatform iOS # or Xcode ▸ Settings ▸ Components
52
+ ```
53
+ Then re-run `scripts/setup-mobile.sh` — it will create the `qa-iphone` device.
54
+
55
+ ## Standard device names (referenced by the target configs)
56
+ - Android AVD: **`qa_pixel_api35`** (Google-Play API 35) — set `ANDROID_AVD_NAME` to override.
57
+ - iOS sim: **`qa-iphone`** — set `IOS_DEVICE_NAME` to override.
58
+
59
+ The `data/targets/_example-sim-*.yml` configs resolve the device **by name** (not a
60
+ hardcoded UDID) so they're portable across machines. `00-setup` boots the named device,
61
+ creating it if missing.
62
+
63
+ ## Why a Google **Play** (or `google_apis`) Android image
64
+ A stock **AOSP** system image ships **no `com.android.chrome`** — only a basic AOSP
65
+ browser or none. Web-mode Android targets need Chrome, so `setup-mobile.sh` installs a
66
+ `google_apis_playstore` image. Verify on any AVD with:
67
+ ```bash
68
+ adb shell pm list packages | grep chrome
69
+ ```
70
+
71
+ ## Auth reality (web targets)
72
+ There is **no transferable `storage_state`** for a real device browser (unlike Playwright).
73
+ SSO + MFA logins are done **once, interactively, by a human** in the sim/emulator browser;
74
+ the device persists the browser profile across launches. Never script MFA. Never
75
+ `relaunch-clean` a web target (it `pm clear`s the logged-in Chrome profile). See the
76
+ `notes:` blocks in `data/targets/_example-sim-*.yml`.
77
+
78
+ ## Troubleshooting
79
+ - **`doctor-mobile.sh` says NOT READY** → fix each `✗` with the printed command, or run
80
+ `setup-mobile.sh`, then re-run the doctor.
81
+ - **`JAVA_HOME` / `adb` not found mid-session** → `bin/mcli` resolves JDK 17 via
82
+ `/usr/libexec/java_home -v 17` and defaults `ANDROID_HOME` to `~/Library/Android/sdk`.
83
+ Export them explicitly if your SDK lives elsewhere.
84
+ - **Intel Mac** → `setup-mobile.sh` selects `x86_64` system images automatically (`arm64`
85
+ Macs get `arm64-v8a`).
86
+ - **Emulator slow/flaky to boot or Chrome absent** → fall back to the iOS Safari target;
87
+ both engines are independent.
88
+
89
+ ## Scope
90
+ This covers iOS Simulator + Android Emulator (browser **and** native modes). It does **not**
91
+ provision physical devices, CI runners, or the desktop web path (`/qa-explore`, which only
92
+ needs `playwright-cli`).
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "qualiow-exploratory-testing",
3
- "version": "1.1.0",
4
- "description": "qualiow — AI-powered exploratory testing skills using Claude Code + Playwright CLI",
3
+ "version": "1.2.0",
4
+ "description": "qualiow — AI-powered exploratory testing skills using Claude Code + Playwright CLI (web) and Maestro/mobile-cli (iOS/Android simulators)",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
@@ -11,12 +11,20 @@
11
11
  "files": [
12
12
  "dist/",
13
13
  "skills/",
14
+ "bin/",
15
+ "scripts/setup-mobile.sh",
16
+ "scripts/doctor-mobile.sh",
14
17
  "data/domains/*.yml",
15
18
  "data/knowledge/",
16
19
  "data/templates/",
17
20
  "data/targets/_default.yml",
21
+ "data/targets/_example-native-mobile.yml",
22
+ "data/targets/_example-sim-ios-safari.yml",
23
+ "data/targets/_example-sim-android-chrome.yml",
24
+ "data/targets/_example-mobile-emulation.yml",
18
25
  "data/targets/testers-ai.yml",
19
- "docs/GETTING-STARTED.md"
26
+ "docs/GETTING-STARTED.md",
27
+ "docs/MOBILE-SETUP.md"
20
28
  ],
21
29
  "scripts": {
22
30
  "sync:skills": "rm -rf skills && cp -R .claude/skills skills",
@@ -35,6 +43,10 @@
35
43
  "qa",
36
44
  "testing",
37
45
  "playwright",
46
+ "maestro",
47
+ "mobile-testing",
48
+ "ios-simulator",
49
+ "android-emulator",
38
50
  "ai",
39
51
  "claude",
40
52
  "skills",
@@ -55,13 +67,13 @@
55
67
  "url": "https://github.com/willcoliveira/qualiow-exploratory-testing-skills/issues"
56
68
  },
57
69
  "dependencies": {
58
- "@playwright/cli": "^0.1.6",
70
+ "@playwright/cli": "^0.1.15",
59
71
  "chalk": "^5.3.0",
60
- "commander": "^13.1.0",
61
- "glob": "^11.0.0",
72
+ "commander": "^15.0.0",
73
+ "glob": "^13.0.6",
62
74
  "handlebars": "^4.7.8",
63
- "yaml": "^2.7.0",
64
- "zod": "^3.24.0"
75
+ "yaml": "^2.9.0",
76
+ "zod": "^4.4.3"
65
77
  },
66
78
  "peerDependencies": {
67
79
  "@playwright/test": "^1.59.1"
@@ -72,9 +84,9 @@
72
84
  }
73
85
  },
74
86
  "devDependencies": {
75
- "@types/node": "^22.0.0",
87
+ "@types/node": "^26.1.1",
76
88
  "tsup": "^8.4.0",
77
- "typescript": "^5.7.0",
78
- "vitest": "^3.0.0"
89
+ "typescript": "^5.9.3",
90
+ "vitest": "^4.1.10"
79
91
  }
80
92
  }
@@ -0,0 +1,143 @@
1
+ #!/usr/bin/env bash
2
+ # doctor-mobile.sh — read-only preflight for the qa-explore-mobile skill.
3
+ #
4
+ # Verifies that everything mobile-cli needs to drive iOS Simulator Safari/native and
5
+ # Android Emulator Chrome/native is present on THIS machine. Installs NOTHING — it only
6
+ # reports ✓/✗ with the exact fix command for each gap. The mobile session's 00-setup
7
+ # phase runs this first so a fresh machine fails fast with actionable guidance instead of
8
+ # a cryptic error deep in a session.
9
+ #
10
+ # Usage:
11
+ # scripts/doctor-mobile.sh # check both platforms
12
+ # scripts/doctor-mobile.sh --ios # iOS only
13
+ # scripts/doctor-mobile.sh --android # Android only
14
+ # scripts/doctor-mobile.sh --quiet # only print failures + final verdict
15
+ #
16
+ # Exit code: 0 if all REQUIRED checks for the requested platform(s) pass, 1 otherwise.
17
+
18
+ set -uo pipefail
19
+
20
+ PLATFORM="both"
21
+ QUIET=0
22
+ for arg in "$@"; do
23
+ case "$arg" in
24
+ --ios) PLATFORM="ios" ;;
25
+ --android) PLATFORM="android" ;;
26
+ --quiet) QUIET=1 ;;
27
+ -h|--help) sed -n '2,18p' "$0"; exit 0 ;;
28
+ *) echo "unknown arg: $arg" >&2; exit 2 ;;
29
+ esac
30
+ done
31
+
32
+ # ---- resolution helpers (mirror what bin/mcli does, with fallbacks) ----
33
+ ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
34
+ JAVA_HOME_RESOLVED="${JAVA_HOME:-}"
35
+ if [ -z "$JAVA_HOME_RESOLVED" ] && [ -x /usr/libexec/java_home ]; then
36
+ JAVA_HOME_RESOLVED="$(/usr/libexec/java_home -v 17 2>/dev/null || true)"
37
+ fi
38
+ [ -z "$JAVA_HOME_RESOLVED" ] && [ -d /opt/homebrew/opt/openjdk@17 ] && JAVA_HOME_RESOLVED=/opt/homebrew/opt/openjdk@17
39
+ [ -z "$JAVA_HOME_RESOLVED" ] && [ -d /usr/local/opt/openjdk@17 ] && JAVA_HOME_RESOLVED=/usr/local/opt/openjdk@17
40
+ MAESTRO_BIN="$HOME/.maestro/bin/maestro"
41
+
42
+ PASS=0; FAIL=0; WARN=0
43
+ ok() { PASS=$((PASS+1)); [ "$QUIET" = 1 ] || printf ' \033[32m✓\033[0m %s\n' "$1"; }
44
+ bad() { FAIL=$((FAIL+1)); printf ' \033[31m✗\033[0m %s\n ↳ fix: %s\n' "$1" "$2"; }
45
+ warn() { WARN=$((WARN+1)); [ "$QUIET" = 1 ] || printf ' \033[33m!\033[0m %s\n ↳ %s\n' "$1" "$2"; }
46
+ hdr() { [ "$QUIET" = 1 ] || printf '\n\033[1m%s\033[0m\n' "$1"; }
47
+
48
+ # ============================ COMMON ============================
49
+ hdr "Common"
50
+ if [ "$(uname -s)" = "Darwin" ]; then ok "macOS ($(sw_vers -productVersion 2>/dev/null))"; else
51
+ bad "not macOS — iOS sims need macOS; Android may work on Linux but is unverified here" "use a Mac"; fi
52
+
53
+ if command -v brew >/dev/null 2>&1; then ok "Homebrew ($(brew --version 2>/dev/null | head -1))"; else
54
+ bad "Homebrew not found" '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'; fi
55
+
56
+ if command -v node >/dev/null 2>&1; then
57
+ NV="$(node -v | sed 's/^v//')"; NMAJ="${NV%%.*}"
58
+ if [ "${NMAJ:-0}" -ge 18 ]; then ok "Node $NV (>=18)"; else bad "Node $NV is < 18" "brew install node (or nvm install --lts)"; fi
59
+ else bad "Node not found" "brew install node"; fi
60
+
61
+ if [ -x "$MAESTRO_BIN" ] || command -v maestro >/dev/null 2>&1; then
62
+ ok "Maestro present ($MAESTRO_BIN)"
63
+ else bad "Maestro not found" 'curl -Ls "https://get.maestro.mobile.dev" | bash'; fi
64
+
65
+ # ============================ ANDROID ============================
66
+ if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "android" ]; then
67
+ hdr "Android"
68
+ # JDK 17
69
+ if [ -n "$JAVA_HOME_RESOLVED" ] && [ -x "$JAVA_HOME_RESOLVED/bin/java" ]; then
70
+ JV="$("$JAVA_HOME_RESOLVED/bin/java" -version 2>&1 | head -1)"
71
+ case "$JV" in *\"17.*) ok "JDK 17 ($JAVA_HOME_RESOLVED)";; *) warn "Java found but not 17: $JV" "Android SDK tools expect JDK 17 — brew install openjdk@17";; esac
72
+ else bad "JDK 17 not found" "brew install openjdk@17"; fi
73
+
74
+ # SDK root
75
+ if [ -d "$ANDROID_HOME" ]; then ok "Android SDK root ($ANDROID_HOME)"; else
76
+ bad "Android SDK not found at $ANDROID_HOME" "scripts/setup-mobile.sh (installs cmdline-tools + SDK)"; fi
77
+
78
+ # adb / emulator / sdkmanager / avdmanager
79
+ for tuple in \
80
+ "platform-tools/adb:adb:sdkmanager 'platform-tools'" \
81
+ "emulator/emulator:emulator:sdkmanager 'emulator'" ; do
82
+ rel="${tuple%%:*}"; rest="${tuple#*:}"; label="${rest%%:*}"; fix="${rest#*:}"
83
+ if [ -x "$ANDROID_HOME/$rel" ]; then ok "$label ($ANDROID_HOME/$rel)"; else bad "$label missing" "$fix"; fi
84
+ done
85
+ SDKMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
86
+ AVDMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/avdmanager 2>/dev/null | head -1)"
87
+ if [ -n "$SDKMGR" ]; then ok "sdkmanager present"; else bad "sdkmanager (cmdline-tools) missing" "brew install --cask android-commandlinetools (or Android Studio)"; fi
88
+ [ -n "$AVDMGR" ] && ok "avdmanager present"
89
+
90
+ # AVD existing? (Chrome needs a Google Play system image)
91
+ if [ -x "$ANDROID_HOME/emulator/emulator" ]; then
92
+ AVDS="$("$ANDROID_HOME/emulator/emulator" -list-avds 2>/dev/null)"
93
+ if [ -n "$AVDS" ]; then ok "AVD(s) available: $(echo "$AVDS" | tr '\n' ' ')"; else
94
+ bad "no Android AVD created" "scripts/setup-mobile.sh (creates a Google-Play API-35 AVD)"; fi
95
+ fi
96
+ warn "Chrome-on-Android needs a Google **Play** (or google_apis) system image" "AOSP images have no com.android.chrome — verify with: adb shell pm list packages | grep chrome"
97
+ fi
98
+
99
+ # ============================ iOS ============================
100
+ if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "ios" ]; then
101
+ hdr "iOS"
102
+ # Command Line Tools are the floor (xcode-select/xcrun exist at all); full Xcode is
103
+ # still required on top of them for simulators.
104
+ if xcode-select -p >/dev/null 2>&1; then
105
+ ok "Xcode Command Line Tools path set ($(xcode-select -p))"
106
+ else
107
+ bad "Xcode Command Line Tools not installed" "xcode-select --install"
108
+ fi
109
+ if ! command -v xcrun >/dev/null 2>&1; then
110
+ bad "xcrun not found (no Xcode command line tools)" "xcode-select --install"
111
+ else
112
+ XPATH="$(xcode-select -p 2>/dev/null)"
113
+ case "$XPATH" in
114
+ *Xcode*.app*|*/Xcode/*) ok "Full Xcode selected ($XPATH)";;
115
+ *) bad "only Command Line Tools selected ($XPATH) — full Xcode is required for simulators" "install Xcode from the App Store, then: sudo xcode-select -s /Applications/Xcode.app && sudo xcodebuild -license accept";;
116
+ esac
117
+ if xcodebuild -version >/dev/null 2>&1; then ok "xcodebuild ($(xcodebuild -version 2>/dev/null | head -1))"; else
118
+ warn "xcodebuild not runnable (license not accepted?)" "sudo xcodebuild -license accept"; fi
119
+ RT="$(xcrun simctl list runtimes 2>/dev/null | grep -i 'iOS' | head -1)"
120
+ if [ -n "$RT" ]; then ok "iOS runtime: $(echo "$RT" | sed 's/ (.*//')"; else
121
+ bad "no iOS simulator runtime installed" "Xcode ▸ Settings ▸ Components ▸ install an iOS runtime (or: xcodebuild -downloadPlatform iOS)"; fi
122
+ # A usable simulator device
123
+ DEV="$(xcrun simctl list devices available 2>/dev/null | grep -iE 'iPhone' | head -1 | sed 's/^[[:space:]]*//')"
124
+ if [ -n "$DEV" ]; then ok "iPhone simulator available: ${DEV%% (*}"; else
125
+ bad "no available iPhone simulator device" "scripts/setup-mobile.sh (creates one), or: xcrun simctl create qa-iphone com.apple.CoreSimulator.SimDeviceType.iPhone-16 <runtime>"; fi
126
+ # Safari is always preinstalled on iOS sims — no check needed.
127
+ # WebKit DOM bridge (bin/wk-ios): restores JS eval / DOM assertions in sim Safari.
128
+ if command -v ios_webkit_debug_proxy >/dev/null 2>&1; then
129
+ ok "ios-webkit-debug-proxy present (bin/wk-ios DOM bridge)"
130
+ else
131
+ warn "ios-webkit-debug-proxy missing — bin/wk-ios (Safari JS/DOM eval) unavailable" "brew install ios-webkit-debug-proxy"
132
+ fi
133
+ fi
134
+ fi
135
+
136
+ # ============================ VERDICT ============================
137
+ printf '\n\033[1mSummary:\033[0m %d ok, %d warning(s), %d failure(s)\n' "$PASS" "$WARN" "$FAIL"
138
+ if [ "$FAIL" -gt 0 ]; then
139
+ printf '\033[31mNOT READY\033[0m — resolve the ✗ items above (or run: scripts/setup-mobile.sh) then re-run this doctor.\n'
140
+ exit 1
141
+ fi
142
+ printf '\033[32mREADY\033[0m — mobile-cli can drive the requested platform(s).\n'
143
+ exit 0
@@ -0,0 +1,213 @@
1
+ #!/usr/bin/env bash
2
+ # setup-mobile.sh — idempotent bootstrap for the qa-explore-mobile skill on a fresh Mac.
3
+ #
4
+ # Installs everything mobile-cli needs that CAN be scripted, and creates standard-named
5
+ # devices the target configs expect. Re-runnable: every step checks before acting.
6
+ #
7
+ # What it can do automatically:
8
+ # - Homebrew (offers to install if missing), Node, JDK 17, Maestro
9
+ # - Android: cmdline-tools, platform-tools, emulator, a Google-Play system image,
10
+ # license acceptance, and a standard AVD ($ANDROID_AVD_NAME, default qa_pixel_api35)
11
+ # - iOS: a standard simulator device ($IOS_DEVICE_NAME, default qa-iphone) from an
12
+ # installed iOS runtime
13
+ #
14
+ # What stays MANUAL (printed as guidance, never silently skipped):
15
+ # - Xcode itself (multi-GB App Store install) + `xcodebuild -license accept`
16
+ # - iOS runtime download (Xcode ▸ Settings ▸ Components) if none is installed
17
+ #
18
+ # Usage:
19
+ # scripts/setup-mobile.sh # both platforms
20
+ # scripts/setup-mobile.sh --android # Android only
21
+ # scripts/setup-mobile.sh --ios # iOS only
22
+ # scripts/setup-mobile.sh --yes # non-interactive (assume yes to prompts)
23
+ #
24
+ # After it finishes it runs doctor-mobile.sh to confirm the result.
25
+
26
+ set -uo pipefail
27
+
28
+ PLATFORM="both"; ASSUME_YES=0
29
+ for arg in "$@"; do
30
+ case "$arg" in
31
+ --android) PLATFORM="android" ;;
32
+ --ios) PLATFORM="ios" ;;
33
+ --yes|-y) ASSUME_YES=1 ;;
34
+ -h|--help) sed -n '2,28p' "$0"; exit 0 ;;
35
+ *) echo "unknown arg: $arg" >&2; exit 2 ;;
36
+ esac
37
+ done
38
+
39
+ HERE="$(cd "$(dirname "$0")" && pwd)"
40
+ ARCH="$(uname -m)" # arm64 | x86_64
41
+ ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
42
+ ANDROID_AVD_NAME="${ANDROID_AVD_NAME:-qa_pixel_api35}"
43
+ ANDROID_API="${ANDROID_API:-35}"
44
+ IOS_DEVICE_NAME="${IOS_DEVICE_NAME:-qa-iphone}"
45
+ if [ "$ARCH" = "arm64" ]; then ABI="arm64-v8a"; else ABI="x86_64"; fi
46
+ SYS_IMAGE="system-images;android-${ANDROID_API};google_apis_playstore;${ABI}"
47
+
48
+ say() { printf '\n\033[1m▸ %s\033[0m\n' "$1"; }
49
+ info() { printf ' %s\n' "$1"; }
50
+ skip() { printf ' \033[32m✓ already present:\033[0m %s\n' "$1"; }
51
+ manual(){ printf ' \033[33m⚠ MANUAL STEP:\033[0m %s\n' "$1"; }
52
+ confirm() {
53
+ [ "$ASSUME_YES" = 1 ] && return 0
54
+ printf ' %s [y/N] ' "$1"; read -r ans </dev/tty 2>/dev/null || ans=n
55
+ case "$ans" in y|Y|yes) return 0;; *) return 1;; esac
56
+ }
57
+
58
+ # ----------------------------------------------------------------- Homebrew
59
+ say "Homebrew"
60
+ if command -v brew >/dev/null 2>&1; then skip "brew $(brew --version | head -1)"; else
61
+ if confirm "Homebrew not found. Install it now?"; then
62
+ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
63
+ else manual "Install Homebrew, then re-run: https://brew.sh"; fi
64
+ fi
65
+ BREW="$(command -v brew || true)"
66
+ [ -z "$BREW" ] && [ -x /opt/homebrew/bin/brew ] && BREW=/opt/homebrew/bin/brew
67
+ [ -z "$BREW" ] && [ -x /usr/local/bin/brew ] && BREW=/usr/local/bin/brew
68
+
69
+ # ----------------------------------------------------------------- Node
70
+ say "Node.js (>=18)"
71
+ if command -v node >/dev/null 2>&1 && [ "$(node -v | sed 's/v//;s/\..*//')" -ge 18 ]; then
72
+ skip "node $(node -v)"
73
+ elif [ -n "$BREW" ]; then info "installing node..."; "$BREW" install node || manual "brew install node failed — install Node >=18 manually"; fi
74
+
75
+ # ----------------------------------------------------------------- Maestro
76
+ say "Maestro"
77
+ if [ -x "$HOME/.maestro/bin/maestro" ] || command -v maestro >/dev/null 2>&1; then
78
+ skip "maestro present"
79
+ else
80
+ if confirm "Install Maestro now?"; then curl -Ls "https://get.maestro.mobile.dev" | bash || manual 'curl -Ls "https://get.maestro.mobile.dev" | bash'; fi
81
+ fi
82
+
83
+ # ============================================================ ANDROID
84
+ if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "android" ]; then
85
+ say "Android — JDK 17"
86
+ if /usr/libexec/java_home -v 17 >/dev/null 2>&1; then skip "JDK 17 ($(/usr/libexec/java_home -v 17))"; else
87
+ if [ -n "$BREW" ]; then info "installing openjdk@17..."; "$BREW" install openjdk@17 || manual "brew install openjdk@17"; fi
88
+ fi
89
+ JAVA_HOME_17="$(/usr/libexec/java_home -v 17 2>/dev/null || echo /opt/homebrew/opt/openjdk@17)"
90
+ export JAVA_HOME="$JAVA_HOME_17"
91
+
92
+ say "Android — SDK command-line tools"
93
+ if ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager >/dev/null 2>&1; then skip "cmdline-tools present"; else
94
+ if [ -n "$BREW" ] && confirm "Install android-commandlinetools via Homebrew?"; then
95
+ "$BREW" install --cask android-commandlinetools || manual "install Android Studio or cmdline-tools manually"
96
+ else manual "Install Android cmdline-tools (Android Studio ▸ SDK Manager, or brew install --cask android-commandlinetools)"; fi
97
+ fi
98
+ SDKMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
99
+ # Homebrew installs the cask under its own prefix (share/android-commandlinetools,
100
+ # older cask versions used share/android-commandline-tools) and links the binaries
101
+ # into $(brew --prefix)/bin — fall back through those locations. ANDROID_HOME stays
102
+ # at its default: packages are installed there via --sdk_root, matching what
103
+ # bin/mcli, bin/wadb and doctor-mobile.sh expect.
104
+ if [ -z "$SDKMGR" ]; then
105
+ for CASK_SHARE in /opt/homebrew/share/android-commandlinetools /opt/homebrew/share/android-commandline-tools /usr/local/share/android-commandlinetools /usr/local/share/android-commandline-tools; do
106
+ CAND="$(ls "$CASK_SHARE"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
107
+ if [ -n "$CAND" ]; then SDKMGR="$CAND"; break; fi
108
+ done
109
+ fi
110
+ [ -z "$SDKMGR" ] && command -v sdkmanager >/dev/null 2>&1 && SDKMGR="$(command -v sdkmanager)"
111
+ AVDMGR="$(dirname "${SDKMGR:-/x}")/avdmanager"
112
+ [ ! -x "$AVDMGR" ] && command -v avdmanager >/dev/null 2>&1 && AVDMGR="$(command -v avdmanager)"
113
+
114
+ if [ -n "$SDKMGR" ] && [ -x "$SDKMGR" ]; then
115
+ say "Android — SDK packages + licenses (into $ANDROID_HOME)"
116
+ export ANDROID_SDK_ROOT="$ANDROID_HOME"
117
+ mkdir -p "$ANDROID_HOME"
118
+ # yes exits via SIGPIPE when sdkmanager closes stdin — under `set -o pipefail`
119
+ # that marks the pipeline failed even though sdkmanager succeeded, so run the
120
+ # licenses pipe with pipefail off, and the installs with no pipe at all
121
+ # (licenses are already accepted; </dev/null prevents any interactive hang).
122
+ info "accepting licenses..."; ( set +o pipefail; yes 2>/dev/null | "$SDKMGR" --sdk_root="$ANDROID_HOME" --licenses >/dev/null 2>&1 ) || true
123
+ # cmdline-tools;latest goes FIRST: it puts sdkmanager/avdmanager INSIDE the SDK
124
+ # root. avdmanager resolves the SDK from its own install location, so the copy
125
+ # under the brew cask prefix cannot see packages installed into $ANDROID_HOME
126
+ # ("Package path is not valid ... null") — the in-SDK copy can.
127
+ for pkg in "cmdline-tools;latest" "platform-tools" "emulator" "platforms;android-${ANDROID_API}" "$SYS_IMAGE"; do
128
+ info "ensuring: $pkg"; "$SDKMGR" --sdk_root="$ANDROID_HOME" "$pkg" >/dev/null 2>&1 </dev/null || manual "sdkmanager --sdk_root=\"$ANDROID_HOME\" \"$pkg\" failed — install via Android Studio SDK Manager"
129
+ done
130
+ # Prefer the in-SDK binaries from here on (see comment above).
131
+ IN_SDK_SDKMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
132
+ [ -n "$IN_SDK_SDKMGR" ] && SDKMGR="$IN_SDK_SDKMGR" && AVDMGR="$(dirname "$SDKMGR")/avdmanager"
133
+
134
+ say "Android — standard AVD ($ANDROID_AVD_NAME)"
135
+ if "$ANDROID_HOME/emulator/emulator" -list-avds 2>/dev/null | grep -qx "$ANDROID_AVD_NAME"; then
136
+ skip "AVD $ANDROID_AVD_NAME"
137
+ elif [ -x "$AVDMGR" ]; then
138
+ info "creating AVD $ANDROID_AVD_NAME from $SYS_IMAGE..."
139
+ echo "no" | "$AVDMGR" create avd -n "$ANDROID_AVD_NAME" -k "$SYS_IMAGE" -d "pixel_7" \
140
+ && info "created $ANDROID_AVD_NAME" \
141
+ || manual "avdmanager create avd -n $ANDROID_AVD_NAME -k \"$SYS_IMAGE\" -d pixel_7"
142
+ else manual "avdmanager not found — create an AVD in Android Studio using a Google Play API-$ANDROID_API image"; fi
143
+ fi
144
+ fi
145
+
146
+ # ============================================================ iOS
147
+ if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "ios" ]; then
148
+ say "iOS — Xcode Command Line Tools"
149
+ if xcode-select -p >/dev/null 2>&1; then
150
+ skip "CLT/Xcode path selected ($(xcode-select -p))"
151
+ else
152
+ if confirm "Xcode Command Line Tools not found. Trigger the install now? (opens a GUI dialog)"; then
153
+ xcode-select --install 2>/dev/null || true
154
+ manual "Complete the Command Line Tools install dialog, then re-run this script."
155
+ else
156
+ manual "xcode-select --install"
157
+ fi
158
+ fi
159
+
160
+ say "iOS — WebKit DOM bridge (ios-webkit-debug-proxy for bin/wk-ios)"
161
+ if command -v ios_webkit_debug_proxy >/dev/null 2>&1; then
162
+ skip "ios-webkit-debug-proxy present"
163
+ elif [ -n "$BREW" ]; then
164
+ info "installing ios-webkit-debug-proxy..."
165
+ "$BREW" install ios-webkit-debug-proxy || manual "brew install ios-webkit-debug-proxy (enables bin/wk-ios JS/DOM eval in sim Safari)"
166
+ else
167
+ manual "brew install ios-webkit-debug-proxy (enables bin/wk-ios JS/DOM eval in sim Safari)"
168
+ fi
169
+
170
+ say "iOS — Xcode"
171
+ XPATH="$(xcode-select -p 2>/dev/null || true)"
172
+ case "$XPATH" in
173
+ *Xcode*.app*|*/Xcode/*) skip "full Xcode ($XPATH)";;
174
+ *) manual "Install Xcode from the App Store (multi-GB), then run:"
175
+ manual " sudo xcode-select -s /Applications/Xcode.app/Contents/Developer"
176
+ manual " sudo xcodebuild -license accept" ;;
177
+ esac
178
+
179
+ if command -v xcrun >/dev/null 2>&1 && xcodebuild -version >/dev/null 2>&1; then
180
+ say "iOS — runtime + simulator device ($IOS_DEVICE_NAME)"
181
+ RUNTIME_ID="$(xcrun simctl list runtimes 2>/dev/null | grep -i 'iOS' | grep -oE 'com\.apple\.CoreSimulator\.SimRuntime\.iOS[^ ]*' | head -1)"
182
+ if [ -z "$RUNTIME_ID" ]; then
183
+ manual "No iOS runtime installed. Install one via Xcode ▸ Settings ▸ Components (or: xcodebuild -downloadPlatform iOS), then re-run."
184
+ else
185
+ if xcrun simctl list devices 2>/dev/null | grep -q "$IOS_DEVICE_NAME"; then
186
+ skip "simulator device $IOS_DEVICE_NAME"
187
+ else
188
+ # devicetypes are listed NEWEST FIRST, and modern ids have non-numeric
189
+ # suffixes (iPhone-17-Pro, iPhone-Air, iPhone-16e) — take the first match.
190
+ DTYPE="$(xcrun simctl list devicetypes 2>/dev/null | grep -oE 'com\.apple\.CoreSimulator\.SimDeviceType\.iPhone-[0-9A-Za-z-]+' | head -1)"
191
+ [ -z "$DTYPE" ] && DTYPE="com.apple.CoreSimulator.SimDeviceType.iPhone-16"
192
+ info "creating simulator $IOS_DEVICE_NAME ($DTYPE)..."
193
+ xcrun simctl create "$IOS_DEVICE_NAME" "$DTYPE" "$RUNTIME_ID" >/dev/null 2>&1 \
194
+ && info "created $IOS_DEVICE_NAME" \
195
+ || manual "xcrun simctl create $IOS_DEVICE_NAME $DTYPE $RUNTIME_ID"
196
+ fi
197
+ fi
198
+ else
199
+ manual "Xcode not runnable yet — finish the Xcode steps above, then re-run scripts/setup-mobile.sh"
200
+ fi
201
+ fi
202
+
203
+ # ----------------------------------------------------------------- verify
204
+ say "Verifying with doctor-mobile.sh"
205
+ DOCTOR_ARGS=""; [ "$PLATFORM" = "ios" ] && DOCTOR_ARGS="--ios"; [ "$PLATFORM" = "android" ] && DOCTOR_ARGS="--android"
206
+ bash "$HERE/doctor-mobile.sh" $DOCTOR_ARGS || {
207
+ echo
208
+ echo "Some checks still fail — resolve the MANUAL steps above (Xcode / iOS runtime are the usual ones) and re-run."
209
+ exit 1
210
+ }
211
+ echo
212
+ echo "Done. Standard devices: Android AVD '$ANDROID_AVD_NAME', iOS sim '$IOS_DEVICE_NAME'."
213
+ echo "Target configs (data/targets/_example-sim-*.yml) reference these names."
@@ -9,7 +9,14 @@ Extract from user message:
9
9
  - **time_box**: Session duration (default: 45 min, max: 45 min)
10
10
  - **context**: Path to requirements file OR inline context text (optional)
11
11
 
12
- Resolve target config from `data/targets/` if available. Read domain config from `data/domains/`.
12
+ Resolve target config in this order:
13
+ 1. If `--target <name>` given → load from skill `data/targets/<name>.yml`
14
+ 2. Else if CWD contains `qa/target.yml` → load it as the target config
15
+ 3. Else fall back to `data/targets/_default.yml`
16
+
17
+ If loaded from `qa/target.yml`, also check `qa/.env` in CWD for credential env var values before falling back to the skill root `.env`.
18
+
19
+ Read domain config from `data/domains/`.
13
20
 
14
21
  ## Step 2: Load Context (if provided)
15
22
 
@@ -11,6 +11,10 @@ playwright-cli goto <base_url>
11
11
 
12
12
  ## Credentials (adaptive -- uses snapshot to find form fields)
13
13
 
14
+ Before filling credentials, resolve their values:
15
+ 1. If `qa/.env` exists in CWD, read it — use the values for the env var names specified in `auth.credentials.username` / `auth.credentials.password` in the target config
16
+ 2. Otherwise read from the skill root `.env`
17
+
14
18
  ```bash
15
19
  playwright-cli open <login_url>
16
20
  playwright-cli snapshot