qualiow-exploratory-testing 1.0.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 (41) 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 +33 -11
  20. package/scripts/doctor-mobile.sh +143 -0
  21. package/scripts/setup-mobile.sh +213 -0
  22. package/skills/qa-explore/SKILL.md +2 -1
  23. package/skills/qa-explore/phases/00-setup.md +22 -1
  24. package/skills/qa-explore/phases/01-auth.md +4 -0
  25. package/skills/qa-explore/phases/03-discovery.md +14 -0
  26. package/skills/qa-explore/phases/05-features.md +20 -0
  27. package/skills/qa-explore/phases/06-edge-cases.md +2 -0
  28. package/skills/qa-explore/phases/07-reporting.md +11 -0
  29. package/skills/qa-explore/references/playwright-agents-integration.md +126 -0
  30. package/skills/qa-explore-mobile/SKILL.md +146 -0
  31. package/skills/qa-explore-mobile/phases/00-setup.md +203 -0
  32. package/skills/qa-explore-mobile/phases/01-auth.md +127 -0
  33. package/skills/qa-explore-mobile/phases/02-charter.md +70 -0
  34. package/skills/qa-explore-mobile/phases/03-discovery.md +79 -0
  35. package/skills/qa-explore-mobile/phases/04-journeys.md +49 -0
  36. package/skills/qa-explore-mobile/phases/05-features.md +72 -0
  37. package/skills/qa-explore-mobile/phases/06-edge-cases.md +157 -0
  38. package/skills/qa-explore-mobile/phases/07-reporting.md +123 -0
  39. package/skills/qa-explore-mobile/references/mobile-edges.md +117 -0
  40. package/skills/qa-explore-quick/SKILL.md +7 -0
  41. package/skills/qa-target-setup/SKILL.md +12 -0
package/README.md CHANGED
@@ -74,6 +74,90 @@ npm test
74
74
  /qa-explore-quick https://app.example.com/checkout
75
75
  ```
76
76
 
77
+ ### Mobile session (simulator/emulator)
78
+
79
+ Runs a full exploratory session on an iOS Simulator or Android Emulator — either a
80
+ **native app** (the installed app is the system under test) or a **mobile web app in the
81
+ real device browser** (iOS Simulator Safari / Android Emulator Chrome — the genuine
82
+ engines, which Playwright cannot drive). The mode comes from the target config.
83
+
84
+ #### 1. One-time machine setup
85
+
86
+ ```bash
87
+ # installs everything scriptable: Maestro, JDK 17, Android SDK + Google-Play AVD
88
+ # (qa_pixel_api35), ios-webkit-debug-proxy, and the qa-iphone simulator device
89
+ scripts/setup-mobile.sh # add --android or --ios to scope; --yes for non-interactive
90
+ ```
91
+
92
+ Two iOS steps are genuinely manual (the script prints them if needed):
93
+
94
+ ```bash
95
+ # a) install Xcode from the App Store, then:
96
+ sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
97
+ sudo xcodebuild -license accept
98
+ # b) if no iOS runtime is installed:
99
+ xcodebuild -downloadPlatform iOS
100
+ # then re-run scripts/setup-mobile.sh --ios (creates the qa-iphone simulator)
101
+ ```
102
+
103
+ #### 2. Verify readiness (read-only, run before every first session on a machine)
104
+
105
+ ```bash
106
+ scripts/doctor-mobile.sh # or --ios / --android; fix each ✗ until READY
107
+ ```
108
+
109
+ #### 3. Create a target and run
110
+
111
+ Copy a template from `data/targets/`, rename it, and point it at your app:
112
+
113
+ | Template | What it tests | Driver |
114
+ |----------|---------------|--------|
115
+ | `_example-native-mobile.yml` | An installed iOS/Android app (native mode) | mobile-cli (Maestro) |
116
+ | `_example-sim-ios-safari.yml` | A mobile web app in REAL iOS Simulator Safari | mobile-cli (Maestro) |
117
+ | `_example-sim-android-chrome.yml` | A mobile web app in REAL Android Emulator Chrome | mobile-cli (Maestro) |
118
+ | `_example-mobile-emulation.yml` | A mobile web app via Playwright device emulation (no simulator) | `/qa-explore` (playwright-cli) |
119
+
120
+ ```bash
121
+ /qa-explore-mobile --target my-mobile-target # real sim/emulator (native or web)
122
+ /qa-explore --target my-emulation-target # Playwright mobile emulation
123
+ ```
124
+
125
+ #### 4. Driving the device manually (what the skill does under the hood)
126
+
127
+ ```bash
128
+ # Android: boot the standard AVD # iOS: boot the standard simulator
129
+ ~/Library/Android/sdk/emulator/emulator \
130
+ -avd qa_pixel_api35 -no-snapshot & xcrun simctl boot qa-iphone && open -a Simulator
131
+
132
+ export MOBILE_CLI_STATE=/tmp/my-target-state.json # isolate this session's device/app state
133
+ bin/mcli set-device emulator-5554 # or the iOS sim UDID (xcrun simctl list devices)
134
+ bin/mcli set-app com.android.chrome # or com.apple.mobilesafari, or your app's id
135
+ bin/mcli launch
136
+ bin/mcli open-url https://staging.m.example.com # web mode only
137
+ bin/mcli snapshot # page/app as tappable refs e1, e2, ...
138
+ bin/mcli fill e4 my-username
139
+ bin/mcli snapshot # ALWAYS re-snapshot after the keyboard appears
140
+ bin/mcli click e7
141
+ bin/mcli screenshot /tmp/evidence.png
142
+ bin/mcli logs --errors --since 60
143
+ bin/mcli --help # full command surface
144
+ ```
145
+
146
+ iOS Safari web targets additionally get real JS/DOM access via the WebKit bridge:
147
+
148
+ ```bash
149
+ bin/wk-ios 'document.title' # eval JS in the sim's Safari
150
+ bin/wk-ios 'document.querySelectorAll(".cart_item").length' # exact-DOM assertions
151
+ bin/wk-ios --stop # stop the proxy after the session
152
+ ```
153
+
154
+ Notes that save time:
155
+ - **Never `relaunch-clean` a web target** — it wipes the logged-in browser profile.
156
+ - SSO/MFA logins are done **once, by hand, on the device**; the browser profile persists
157
+ the session. There is no transferable `storage_state` on a real device browser.
158
+ - Use `bin/wadb` for raw adb commands (logcat, `pm`, `am`) — it sets `ANDROID_HOME` for you.
159
+ - Full setup guide + troubleshooting: `docs/MOBILE-SETUP.md`.
160
+
77
161
  ### Generate or regenerate a report
78
162
 
79
163
  ```bash
@@ -134,6 +218,7 @@ const csv = await generateJiraExport('output/sessions/2026-03-28-parabank');
134
218
  | Skill | Purpose |
135
219
  |-------|---------|
136
220
  | `/qa-explore` | Full exploratory testing session (45 min) |
221
+ | `/qa-explore-mobile` | Exploratory session on a simulator/emulator — native apps or mobile web in the real device browser (iOS Safari / Android Chrome) |
137
222
  | `/qa-explore-quick` | Quick focused session on a single page or feature (15 min) |
138
223
  | `/qa-explore-report` | Generate or regenerate report from existing session |
139
224
  | `/qa-explore-feedback` | Post-session feedback capture (false positives, missed bugs) |
package/bin/mcli ADDED
@@ -0,0 +1,16 @@
1
+ #!/bin/bash
2
+ # mcli — env-setting wrapper around mobile-cli.mjs so subagents can call a single
3
+ # bash command without needing to prefix every call with export JAVA_HOME=... etc.
4
+ # (Compound `export ...; cmd ...` calls hit the Claude Code permission system
5
+ # which matches on the first token of the line.)
6
+ # Resolve JDK 17 portably: honor an existing JAVA_HOME, else ask macOS' java_home,
7
+ # else fall back to the Homebrew prefixes (arm64 then Intel). Avoids hardcoding one path.
8
+ if [ -z "${JAVA_HOME:-}" ]; then
9
+ JAVA_HOME="$(/usr/libexec/java_home -v 17 2>/dev/null || true)"
10
+ [ -z "$JAVA_HOME" ] && [ -d /opt/homebrew/opt/openjdk@17 ] && JAVA_HOME=/opt/homebrew/opt/openjdk@17
11
+ [ -z "$JAVA_HOME" ] && [ -d /usr/local/opt/openjdk@17 ] && JAVA_HOME=/usr/local/opt/openjdk@17
12
+ fi
13
+ export JAVA_HOME
14
+ export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
15
+ export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$HOME/.maestro/bin:$PATH"
16
+ exec node "$(dirname "$0")/mobile-cli.mjs" "$@"