qualiow-exploratory-testing 1.1.0 → 1.3.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 (79) hide show
  1. package/README.md +177 -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/domains/_default.md +181 -0
  8. package/data/domains/ecommerce.md +192 -0
  9. package/data/domains/fintech.md +200 -0
  10. package/data/domains/identity.md +88 -0
  11. package/data/domains/identity.yml +138 -0
  12. package/data/domains/marketing.md +194 -0
  13. package/data/domains/saas.md +197 -0
  14. package/data/knowledge/changelog.yml +86 -0
  15. package/data/knowledge/learned-patterns.md +172 -1
  16. package/data/knowledge/manifest.yml +210 -4
  17. package/data/knowledge/releases/v0.2.0/entries/technique-contract-narrowing.yml +150 -0
  18. package/data/knowledge/releases/v0.2.0/entries/technique-test-suite-audit.yml +116 -0
  19. package/data/knowledge/releases/v0.2.0/release.yml +20 -0
  20. package/data/knowledge/releases/v0.3.0/entries/technique-functional-diff-analysis.yml +119 -0
  21. package/data/knowledge/releases/v0.3.0/entries/technique-llm-output-verification.yml +102 -0
  22. package/data/knowledge/releases/v0.3.0/entries/technique-verification-mode-selection.yml +153 -0
  23. package/data/knowledge/releases/v0.3.0/release.yml +25 -0
  24. package/data/knowledge/releases/v0.4.0/entries/technique-authenticated-api-probing.yml +137 -0
  25. package/data/knowledge/releases/v0.4.0/entries/technique-environment-fingerprinting.yml +113 -0
  26. package/data/knowledge/releases/v0.4.0/entries/technique-silent-failure-audit.yml +86 -0
  27. package/data/knowledge/releases/v0.4.0/entries/technique-ui-api-differential.yml +97 -0
  28. package/data/knowledge/releases/v0.4.0/release.yml +28 -0
  29. package/data/knowledge/releases/v0.5.0/entries/technique-config-surface-verification.yml +77 -0
  30. package/data/knowledge/releases/v0.5.0/entries/technique-derived-value-verification.yml +81 -0
  31. package/data/knowledge/releases/v0.5.0/entries/technique-expected-behaviour-specification.yml +97 -0
  32. package/data/knowledge/releases/v0.5.0/entries/technique-presentation-integrity.yml +78 -0
  33. package/data/knowledge/releases/v0.5.0/entries/technique-release-readiness-verification.yml +110 -0
  34. package/data/knowledge/releases/v0.5.0/release.yml +33 -0
  35. package/data/targets/_example-backend.yml +123 -0
  36. package/data/targets/_example-mobile-emulation.yml +52 -0
  37. package/data/targets/_example-native-mobile.yml +61 -0
  38. package/data/targets/_example-sim-android-chrome.yml +81 -0
  39. package/data/targets/_example-sim-ios-safari.yml +80 -0
  40. package/data/templates/api-probe-matrix.md +99 -0
  41. package/data/templates/coverage-map.md +14 -0
  42. package/data/templates/expected-behaviour.md +93 -0
  43. package/dist/cli/index.js +137 -5
  44. package/dist/cli/index.js.map +1 -1
  45. package/dist/index.d.ts +350 -527
  46. package/dist/index.js +144 -5
  47. package/dist/index.js.map +1 -1
  48. package/docs/BACKEND-VERIFICATION.md +277 -0
  49. package/docs/MOBILE-SETUP.md +92 -0
  50. package/package.json +26 -12
  51. package/scripts/doctor-mobile.sh +143 -0
  52. package/scripts/setup-mobile.sh +213 -0
  53. package/skills/qa-explore/phases/00-setup.md +8 -1
  54. package/skills/qa-explore/phases/01-auth.md +4 -0
  55. package/skills/qa-explore-mobile/SKILL.md +146 -0
  56. package/skills/qa-explore-mobile/phases/00-setup.md +203 -0
  57. package/skills/qa-explore-mobile/phases/01-auth.md +127 -0
  58. package/skills/qa-explore-mobile/phases/02-charter.md +70 -0
  59. package/skills/qa-explore-mobile/phases/03-discovery.md +79 -0
  60. package/skills/qa-explore-mobile/phases/04-journeys.md +49 -0
  61. package/skills/qa-explore-mobile/phases/05-features.md +72 -0
  62. package/skills/qa-explore-mobile/phases/06-edge-cases.md +157 -0
  63. package/skills/qa-explore-mobile/phases/07-reporting.md +123 -0
  64. package/skills/qa-explore-mobile/references/mobile-edges.md +117 -0
  65. package/skills/qa-explore-quick/SKILL.md +6 -0
  66. package/skills/qa-verify-backend/SKILL.md +163 -0
  67. package/skills/qa-verify-backend/phases/00-setup.md +97 -0
  68. package/skills/qa-verify-backend/phases/01-ac-decomposition.md +58 -0
  69. package/skills/qa-verify-backend/phases/02-static-review.md +71 -0
  70. package/skills/qa-verify-backend/phases/03-live-verification.md +62 -0
  71. package/skills/qa-verify-backend/phases/03b-api-verification.md +157 -0
  72. package/skills/qa-verify-backend/phases/04-e2e-trigger.md +66 -0
  73. package/skills/qa-verify-backend/phases/05-reporting.md +135 -0
  74. package/skills/qa-verify-backend/references/api-probes.md +141 -0
  75. package/skills/qa-verify-backend/references/aws-readonly-probes.md +156 -0
  76. package/skills/qa-verify-backend/references/environment-fingerprinting.md +104 -0
  77. package/skills/qa-verify-backend/references/payload-verification.md +112 -0
  78. package/skills/qa-verify-backend/references/release-readiness.md +97 -0
  79. package/skills/qa-verify-backend/references/safety-rules.md +90 -0
@@ -0,0 +1,573 @@
1
+ #!/usr/bin/env node
2
+ // mobile-cli — Maestro-backed shim mimicking the playwright-cli command surface
3
+ // used by qualiow exploratory testing skills, adapted for iOS/Android.
4
+ //
5
+ // State persists in $MOBILE_CLI_STATE (default ~/.mobile-cli/state.json):
6
+ // { device, platform, appId, refs: { e1: {id, text, x, y, bounds, class} }, capturedAt }
7
+ //
8
+ // Commands:
9
+ // set-device <udid|emulator-5554> persist target device
10
+ // set-app <bundleOrPackage> persist app id
11
+ // info show resolved state
12
+ // launch cold-start the app
13
+ // stop force-stop the app
14
+ // relaunch-clean stop+clear+launch (android only)
15
+ // snapshot [--full] write refs, print ref'd tree
16
+ // click <ref> tap element by ref
17
+ // fill <ref> <text...> tap then inputText
18
+ // press <key> BACK | ENTER | HOME
19
+ // screenshot <path> save PNG
20
+ // logs [--since <sec>] [--errors] dump device logs (logcat / simctl log)
21
+ // logs-clear clear device log buffer (android)
22
+ // deep-link <url> open a deep link in the app
23
+ // open-url <url> open a URL in the device browser (alias of deep-link)
24
+ // running which activity / app is foreground
25
+ // record-start <path> begin video recording
26
+ // record-stop stop video recording
27
+
28
+ import { execFileSync, execSync, spawn } from 'node:child_process';
29
+ import { createWriteStream, existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
30
+ import { homedir } from 'node:os';
31
+ import { dirname, join } from 'node:path';
32
+
33
+ const STATE_PATH = process.env.MOBILE_CLI_STATE || join(homedir(), '.mobile-cli', 'state.json');
34
+ const REC_PID_PATH = STATE_PATH.replace(/\.json$/, '.rec.pid');
35
+
36
+ // Maestro prints an analytics banner on first run, corrupting parsed output
37
+ // (e.g. the hierarchy JSON). Opt out for every maestro child process.
38
+ process.env.MAESTRO_CLI_NO_ANALYTICS = process.env.MAESTRO_CLI_NO_ANALYTICS || '1';
39
+
40
+ function loadState() {
41
+ if (!existsSync(STATE_PATH)) return {};
42
+ try { return JSON.parse(readFileSync(STATE_PATH, 'utf8')); } catch { return {}; }
43
+ }
44
+ function saveState(s) {
45
+ mkdirSync(dirname(STATE_PATH), { recursive: true });
46
+ writeFileSync(STATE_PATH, JSON.stringify(s, null, 2));
47
+ }
48
+
49
+ function run(cmd, args, opts = {}) {
50
+ return execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], ...opts });
51
+ }
52
+ function runOk(cmd, args, opts = {}) {
53
+ try { return { ok: true, out: run(cmd, args, opts) }; }
54
+ catch (e) { return { ok: false, out: e.stdout?.toString() || '', err: e.stderr?.toString() || e.message }; }
55
+ }
56
+
57
+ function platformFromDevice(device) {
58
+ // emulator-* or NNNN.NNNN.NNNN style or starts with 'R' → android adb; UDID with hyphens → ios
59
+ if (!device) return null;
60
+ if (device.startsWith('emulator-') || /^[0-9A-F]{8}$/i.test(device) || device.length < 16) return 'android';
61
+ return 'ios';
62
+ }
63
+
64
+ function reqDevice(s) {
65
+ if (!s.device) throw new Error('No device set. Run: mobile-cli set-device <udid|emulator-5554>');
66
+ return s;
67
+ }
68
+ function reqApp(s) {
69
+ reqDevice(s);
70
+ if (!s.appId) throw new Error('No app set. Run: mobile-cli set-app <bundleId|package>');
71
+ return s;
72
+ }
73
+
74
+ // ---- maestro wrapper ----
75
+ function maestro(state, args) {
76
+ reqDevice(state);
77
+ return runOk('maestro', ['--device', state.device, ...args]);
78
+ }
79
+
80
+ // ---- snapshot: parse maestro hierarchy → ref-numbered text tree ----
81
+ function parseBounds(b) {
82
+ // "[x1,y1][x2,y2]"
83
+ const m = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/.exec(b || '');
84
+ if (!m) return null;
85
+ const [, x1, y1, x2, y2] = m.map(Number);
86
+ return { x1, y1, x2, y2, cx: Math.round((x1 + x2) / 2), cy: Math.round((y1 + y2) / 2), w: x2 - x1, h: y2 - y1 };
87
+ }
88
+
89
+ // IDs to exclude as system chrome (status bar, navigation bar, notifications).
90
+ const SYSTEM_ID_PREFIXES = [
91
+ 'com.android.systemui:',
92
+ 'com.google.android.apps.nexuslauncher:',
93
+ 'android:id/statusBar',
94
+ 'android:id/navigationBarBackground',
95
+ ];
96
+ function isSystemChrome(id) {
97
+ return id && SYSTEM_ID_PREFIXES.some(p => id.startsWith(p));
98
+ }
99
+
100
+ // Text patterns of dev-only chrome the app renders on top of every screen.
101
+ // These traps confuse exploratory agents (one accidental tap = lost in the debug menu).
102
+ const DEV_CHROME_TEXT_PATTERNS = [
103
+ /^Debug tools$/i, // floating bug button (app/sections/debug-menu trigger)
104
+ ];
105
+ function isDevChrome(text) {
106
+ return text && DEV_CHROME_TEXT_PATTERNS.some(p => p.test(text.trim()));
107
+ }
108
+
109
+ // ---- browser-target snapshot tuning ----
110
+ // When the "app under test" is actually a mobile browser driving a web app, the a11y
111
+ // tree is dominated by the browser's own shell (address bar, tabs, toolbar, on-screen
112
+ // keyboard) plus a few wrapper containers around the rendered page. The web content we
113
+ // care about lives *inside* those wrappers, so we treat two kinds of nodes specially.
114
+ // All of this is gated on the app id being a known browser so native-app snapshots are
115
+ // completely unaffected (backward-compatible).
116
+ const BROWSER_APP_IDS = [
117
+ 'com.apple.mobilesafari', // iOS Safari
118
+ 'com.android.chrome', // Android Chrome
119
+ 'org.mozilla.firefox', // Firefox (android)
120
+ 'com.microsoft.emmx', // Edge (android)
121
+ ];
122
+ function isBrowserApp(appId) {
123
+ return !!appId && BROWSER_APP_IDS.includes(appId);
124
+ }
125
+
126
+ // Pass-through wrappers: the browser nests the live web page a few layers deep
127
+ // (iOS Safari: SafariWindow > TabDocument > WebView > <page>). We never emit these as
128
+ // their own ref, but we DO keep walking into them so the page content surfaces.
129
+ const BROWSER_PASSTHROUGH_ID_PREFIXES = [
130
+ // iOS Safari
131
+ 'SafariWindow',
132
+ 'TabDocument',
133
+ 'WebView',
134
+ // Android Chrome — wrappers around the rendered page compositor
135
+ 'com.android.chrome:id/coordinator',
136
+ 'com.android.chrome:id/compositor_view_holder',
137
+ 'com.android.chrome:id/content',
138
+ ];
139
+ function isBrowserPassthrough(id) {
140
+ return id && BROWSER_PASSTHROUGH_ID_PREFIXES.some(p => id.startsWith(p));
141
+ }
142
+
143
+ // Browser-own UI subtrees (address/URL bar, tab bar, toolbar, reload/menu buttons,
144
+ // on-screen keyboard, input accessory, dimming overlays). None of this is app-under-test
145
+ // content — prune the whole subtree like system chrome so web snapshots aren't drowned.
146
+ const BROWSER_CHROME_ID_PREFIXES = [
147
+ // iOS Safari
148
+ 'CapsuleViewController', // the entire URL/address bar cluster
149
+ 'CapsuleNavigationBar',
150
+ 'TabBarItemTitle',
151
+ 'BackButton',
152
+ 'ReloadButton',
153
+ 'MoreMenuButton',
154
+ 'PageFormatMenuButton',
155
+ 'AdditionalDimmingOverlay',
156
+ 'Toolbar',
157
+ 'inputView',
158
+ 'SystemInputAssistantView',
159
+ 'UIKeyboardLayout',
160
+ 'UIKeyboard',
161
+ 'kb-autofill-key',
162
+ // Android Chrome
163
+ 'com.android.chrome:id/toolbar',
164
+ 'com.android.chrome:id/url_bar',
165
+ 'com.android.chrome:id/tab_switcher_button',
166
+ 'com.android.chrome:id/menu_button',
167
+ 'com.android.chrome:id/control_container',
168
+ 'com.android.chrome:id/toolbar_container',
169
+ 'com.android.chrome:id/bottom_container',
170
+ 'com.android.chrome:id/location_bar',
171
+ 'com.android.chrome:id/omnibox',
172
+ 'com.android.chrome:id/message', // promo/infobar bubbles ("Open tabs to visit…")
173
+ 'com.android.chrome:id/infobar',
174
+ ];
175
+ function isBrowserChrome(id) {
176
+ return id && BROWSER_CHROME_ID_PREFIXES.some(p => id.startsWith(p));
177
+ }
178
+
179
+ function isInteresting(attrs) {
180
+ if (!attrs) return false;
181
+ const cls = attrs.class || '';
182
+ const id = attrs['resource-id'] || '';
183
+ if (isSystemChrome(id)) return false;
184
+ const text = attrs.text || attrs.accessibilityText || attrs.hintText || attrs.label || '';
185
+ if (isDevChrome(text)) return false;
186
+ const clickable = attrs.clickable === 'true' || attrs.clickable === true;
187
+ if (id) return true;
188
+ if (clickable && text) return true;
189
+ if (/EditText|TextField|Button|CheckBox|Switch|TextView/i.test(cls) && (text || clickable)) return true;
190
+ if (text && text.length > 0 && text.length < 200) return true; // visible text
191
+ return false;
192
+ }
193
+
194
+ function summarizeClass(cls) {
195
+ if (!cls) return '?';
196
+ if (/EditText|TextField/i.test(cls)) return 'Input';
197
+ if (/Button/i.test(cls)) return 'Button';
198
+ if (/CheckBox/i.test(cls)) return 'Checkbox';
199
+ if (/Switch/i.test(cls)) return 'Switch';
200
+ if (/ImageView|Image\b/i.test(cls)) return 'Image';
201
+ if (/TextView|StaticText|Label/i.test(cls)) return 'Text';
202
+ if (/ViewGroup|Layout|Stack|Scroll/i.test(cls)) return 'Group';
203
+ return cls.split('.').pop() || cls;
204
+ }
205
+
206
+ function snapshot(state, opts = {}) {
207
+ const r = maestro(state, ['hierarchy']);
208
+ if (!r.ok) throw new Error('maestro hierarchy failed:\n' + r.err);
209
+ let json;
210
+ // Tolerate any banner/log lines maestro prints before the JSON payload.
211
+ const jsonStart = r.out.indexOf('{');
212
+ const raw = jsonStart >= 0 ? r.out.slice(jsonStart) : r.out;
213
+ try { json = JSON.parse(raw); } catch (e) { throw new Error('hierarchy not JSON:\n' + r.out.slice(0, 200)); }
214
+
215
+ const refs = {};
216
+ const lines = [];
217
+ let n = 0;
218
+ const browser = isBrowserApp(state.appId);
219
+
220
+ function walk(node, depth) {
221
+ if (!node) return;
222
+ const a = node.attributes || {};
223
+ const id = (a['resource-id'] || '').trim();
224
+ if (isSystemChrome(id)) return; // skip whole systemui/launcher subtrees
225
+ if (browser && isBrowserChrome(id)) return; // skip the browser's own URL bar / toolbar / keyboard subtrees
226
+ const aText = (a.text || a.accessibilityText || a.hintText || a.label || '').trim();
227
+ if (isDevChrome(aText)) return; // skip Debug tools floater and similar dev-only chrome
228
+ const bounds = parseBounds(a.bounds);
229
+ const text = aText;
230
+ const kind = summarizeClass(a.class);
231
+ let show = opts.full ? !!bounds : isInteresting(a);
232
+ // Browser page-wrapper nodes (SafariWindow/TabDocument/WebView): don't emit the
233
+ // wrapper itself, but keep walking so the web content inside surfaces.
234
+ if (browser && isBrowserPassthrough(id)) show = false;
235
+ if (show && bounds && bounds.w > 0 && bounds.h > 0) {
236
+ n += 1;
237
+ const ref = 'e' + n;
238
+ refs[ref] = {
239
+ id,
240
+ text,
241
+ class: a.class || '',
242
+ clickable: a.clickable === 'true',
243
+ x: bounds.cx, y: bounds.cy,
244
+ bounds: [bounds.x1, bounds.y1, bounds.x2, bounds.y2],
245
+ kind,
246
+ };
247
+ const idPart = id ? ` id=${id}` : '';
248
+ const textPart = text ? ` "${text.replace(/\s+/g, ' ').slice(0, 80)}"` : '';
249
+ const indent = ' '.repeat(Math.min(depth, 6));
250
+ lines.push(`${indent}- [${ref}] ${kind}${textPart}${idPart}`);
251
+ }
252
+ for (const child of node.children || []) walk(child, depth + (show ? 1 : 0));
253
+ }
254
+ walk(json, 0);
255
+
256
+ state.refs = refs;
257
+ state.capturedAt = new Date().toISOString();
258
+ saveState(state);
259
+ return { tree: lines.join('\n'), count: n };
260
+ }
261
+
262
+ function getRef(state, ref) {
263
+ if (!state.refs || !state.refs[ref]) throw new Error(`Unknown ref '${ref}'. Run snapshot first.`);
264
+ return state.refs[ref];
265
+ }
266
+
267
+ // ---- maestro flow runner (one-shot YAML) ----
268
+ // Maestro CLI has no `input` / `tap-by-id` one-shot commands, so we write a tiny flow
269
+ // to /tmp and run it via `maestro test`. Startup is ~3-5s, but avoids char-by-char IME
270
+ // re-renders that adb input text triggers on React Native TextInputs.
271
+ function runFlow(state, commandsYaml) {
272
+ reqApp(state);
273
+ const tmpPath = `/tmp/_mcli_flow_${process.pid}_${Date.now()}.yaml`;
274
+ const yaml = `appId: ${state.appId}\n---\n${commandsYaml}\n`;
275
+ writeFileSync(tmpPath, yaml);
276
+ try {
277
+ return runOk('maestro', ['--device', state.device, 'test', tmpPath]);
278
+ } finally {
279
+ try { unlinkSync(tmpPath); } catch {}
280
+ }
281
+ }
282
+
283
+ // ---- actions ----
284
+ function tap(state, ref) {
285
+ const r = getRef(state, ref);
286
+ if (state.platform === 'android') {
287
+ return runOk('adb', ['-s', state.device, 'shell', 'input', 'tap', String(r.x), String(r.y)]);
288
+ }
289
+ // iOS sim — simctl has no `io tap`, and current Maestro CLIs have no one-shot
290
+ // `tap` command either; run a tiny tapOn-point flow instead.
291
+ return runFlow(state, `- tapOn:\n point: "${r.x},${r.y}"`);
292
+ }
293
+
294
+ // Tap by testID directly via Maestro — no snapshot required first.
295
+ function tapById(state, id) {
296
+ return runFlow(state, `- tapOn:\n id: "${id}"`);
297
+ }
298
+
299
+ function fill(state, ref, text) {
300
+ const tapRes = tap(state, ref);
301
+ if (!tapRes.ok) return tapRes;
302
+ sleep(250);
303
+ // Use Maestro flow for text input on both platforms — avoids React Native
304
+ // per-char re-render hell that makes adb input text crawl on long strings.
305
+ // Maestro startup ≈ adb-input-text cost at ~15+ chars, faster above that.
306
+ const escaped = String(text).replace(/"/g, '\\"');
307
+ return runFlow(state, `- inputText: "${escaped}"`);
308
+ }
309
+
310
+ // Fill by testID — combines tapById + inputText into one Maestro flow (one startup, not two).
311
+ function fillById(state, id, text) {
312
+ const escaped = String(text).replace(/"/g, '\\"');
313
+ return runFlow(state, `- tapOn:\n id: "${id}"\n- inputText: "${escaped}"`);
314
+ }
315
+
316
+ // Wait until a text substring appears in the visible hierarchy, or timeout.
317
+ // Polls every 1s. Returns { ok: true, elapsed_ms } on hit, { ok: false } on timeout.
318
+ function waitText(state, substring, timeoutSec = 10) {
319
+ const deadline = Date.now() + timeoutSec * 1000;
320
+ const start = Date.now();
321
+ while (Date.now() < deadline) {
322
+ const r = maestro(state, ['hierarchy']);
323
+ if (r.ok && r.out.includes(substring)) {
324
+ return { ok: true, out: `found "${substring}" after ${Date.now() - start}ms` };
325
+ }
326
+ sleep(1000);
327
+ }
328
+ return { ok: false, err: `timeout: "${substring}" not seen in ${timeoutSec}s` };
329
+ }
330
+
331
+ function press(state, key) {
332
+ const map = { BACK: 'KEYCODE_BACK', ENTER: 'KEYCODE_ENTER', HOME: 'KEYCODE_HOME', TAB: 'KEYCODE_TAB', ESCAPE: 'KEYCODE_ESCAPE' };
333
+ const k = map[key.toUpperCase()];
334
+ if (!k) throw new Error(`Unknown key: ${key}. One of: ${Object.keys(map).join(', ')}`);
335
+ if (state.platform === 'android') {
336
+ return runOk('adb', ['-s', state.device, 'shell', 'input', 'keyevent', k]);
337
+ }
338
+ // iOS sim: no hardware keys, but Maestro can synthesize Enter (submit the focused
339
+ // field) and Home. BACK still has no iOS equivalent — use an in-app back control.
340
+ const iosKey = { ENTER: 'Enter', HOME: 'Home' }[key.toUpperCase()];
341
+ if (iosKey) return runFlow(state, `- pressKey: ${iosKey}`);
342
+ throw new Error(`press ${key} not supported on iOS sim. Use a UI back button via snapshot+click.`);
343
+ }
344
+
345
+ // Clear the text of an already-filled input: tap it, then Maestro eraseText.
346
+ function clearField(state, ref) {
347
+ const tapRes = tap(state, ref);
348
+ if (!tapRes.ok) return tapRes;
349
+ sleep(250);
350
+ return runFlow(state, `- eraseText: 200`); // erase up to 200 chars from the focused field
351
+ }
352
+
353
+ function launch(state) {
354
+ reqApp(state);
355
+ if (state.platform === 'android') {
356
+ // Resolve the launcher activity and am start it — the classic `monkey -p <pkg>`
357
+ // hack breaks on newer images (API 35 emulator mangles the args). Fall back to
358
+ // monkey only if resolution fails.
359
+ const res = runOk('adb', ['-s', state.device, 'shell', 'cmd', 'package', 'resolve-activity', '--brief', '-c', 'android.intent.category.LAUNCHER', state.appId]);
360
+ const comp = (res.out || '').trim().split('\n').pop()?.trim();
361
+ if (res.ok && comp && comp.includes('/')) {
362
+ return runOk('adb', ['-s', state.device, 'shell', 'am', 'start', '-n', comp]);
363
+ }
364
+ return runOk('adb', ['-s', state.device, 'shell', 'monkey', '-p', state.appId, '-c', 'android.intent.category.LAUNCHER', '1']);
365
+ }
366
+ return runOk('xcrun', ['simctl', 'launch', state.device, state.appId]);
367
+ }
368
+ function stop(state) {
369
+ reqApp(state);
370
+ if (state.platform === 'android') return runOk('adb', ['-s', state.device, 'shell', 'am', 'force-stop', state.appId]);
371
+ return runOk('xcrun', ['simctl', 'terminate', state.device, state.appId]);
372
+ }
373
+ function relaunchClean(state) {
374
+ reqApp(state);
375
+ if (state.platform !== 'android') throw new Error('relaunch-clean is android-only (use stop+launch on ios).');
376
+ stop(state);
377
+ runOk('adb', ['-s', state.device, 'shell', 'pm', 'clear', state.appId]);
378
+ return launch(state);
379
+ }
380
+ function screenshot(state, path) {
381
+ reqApp(state);
382
+ if (state.platform === 'android') {
383
+ const tmp = '/sdcard/_mobile_cli_shot.png';
384
+ runOk('adb', ['-s', state.device, 'shell', 'screencap', '-p', tmp]);
385
+ const r = runOk('adb', ['-s', state.device, 'pull', tmp, path]);
386
+ runOk('adb', ['-s', state.device, 'shell', 'rm', tmp]);
387
+ return r;
388
+ }
389
+ return runOk('xcrun', ['simctl', 'io', state.device, 'screenshot', path]);
390
+ }
391
+ function deepLink(state, url) {
392
+ reqApp(state);
393
+ if (state.platform === 'android') {
394
+ return runOk('adb', ['-s', state.device, 'shell', 'am', 'start', '-W', '-a', 'android.intent.action.VIEW', '-d', url, state.appId]);
395
+ }
396
+ return runOk('xcrun', ['simctl', 'openurl', state.device, url]);
397
+ }
398
+ function running(state) {
399
+ reqDevice(state);
400
+ if (state.platform === 'android') {
401
+ return runOk('adb', ['-s', state.device, 'shell', 'dumpsys', 'window'], {}).out
402
+ .split('\n').filter(l => /mCurrentFocus|mFocusedApp/.test(l)).join('\n');
403
+ }
404
+ return run('xcrun', ['simctl', 'listapps', state.device]).slice(0, 400);
405
+ }
406
+
407
+ function logs(state, args) {
408
+ reqDevice(state);
409
+ const errors = args.includes('--errors');
410
+ const sinceIdx = args.indexOf('--since');
411
+ const since = sinceIdx >= 0 ? parseInt(args[sinceIdx + 1], 10) : 60;
412
+ if (state.platform === 'android') {
413
+ // logcat with time filter; need to compute -T <time>
414
+ const t = new Date(Date.now() - since * 1000);
415
+ const ts = `${String(t.getMonth() + 1).padStart(2, '0')}-${String(t.getDate()).padStart(2, '0')} ${String(t.getHours()).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}:${String(t.getSeconds()).padStart(2, '0')}.000`;
416
+ const lvl = errors ? '*:E' : '*:W';
417
+ const out = runOk('adb', ['-s', state.device, 'logcat', '-d', '-T', ts, lvl]).out || '';
418
+ return out.split('\n').slice(-400).join('\n');
419
+ }
420
+ const out = runOk('xcrun', ['simctl', 'spawn', state.device, 'log', 'show', '--last', `${since}s`, '--predicate', `processImagePath contains "${state.appId || ''}"`]).out || '';
421
+ return out.split('\n').slice(-400).join('\n');
422
+ }
423
+ function logsClear(state) {
424
+ reqDevice(state);
425
+ if (state.platform === 'android') return runOk('adb', ['-s', state.device, 'logcat', '-c']);
426
+ return { ok: true, out: '(ios log buffer not clearable)' };
427
+ }
428
+
429
+ function recordStart(state, path) {
430
+ reqDevice(state);
431
+ if (existsSync(REC_PID_PATH)) throw new Error('Recording already in progress.');
432
+ let proc;
433
+ if (state.platform === 'android') {
434
+ // screenrecord runs on device, then we pull. simpler: use adb screenrecord directly piped to file (max 3min)
435
+ proc = spawn('adb', ['-s', state.device, 'exec-out', 'screenrecord', '--output-format=h264', '-'], {
436
+ stdio: ['ignore', 'pipe', 'inherit'],
437
+ });
438
+ const w = createWriteStream(path);
439
+ proc.stdout.pipe(w);
440
+ } else {
441
+ proc = spawn('xcrun', ['simctl', 'io', state.device, 'recordVideo', path], { stdio: 'ignore', detached: true });
442
+ }
443
+ writeFileSync(REC_PID_PATH, String(proc.pid));
444
+ proc.unref();
445
+ return { ok: true, out: `recording pid=${proc.pid}` };
446
+ }
447
+ function recordStop() {
448
+ if (!existsSync(REC_PID_PATH)) throw new Error('No recording in progress.');
449
+ const pid = parseInt(readFileSync(REC_PID_PATH, 'utf8'), 10);
450
+ try { process.kill(pid, 'SIGINT'); } catch {}
451
+ unlinkSync(REC_PID_PATH);
452
+ return { ok: true, out: `stopped pid=${pid}` };
453
+ }
454
+
455
+ function sleep(ms) {
456
+ try { execSync(`sleep ${(ms / 1000).toFixed(3)}`); } catch {}
457
+ }
458
+
459
+ // ---- main ----
460
+ function main() {
461
+ const [, , cmd, ...args] = process.argv;
462
+ if (!cmd || cmd === '--help' || cmd === '-h') {
463
+ console.log(`mobile-cli — Maestro-backed shim for native iOS/Android exploratory testing
464
+
465
+ Commands:
466
+ set-device <udid> e.g. emulator-5554 OR iOS sim UDID
467
+ set-app <appId> e.g. com.apple.mobilesafari | com.android.chrome | io.example.app
468
+ info
469
+ launch | stop | relaunch-clean
470
+ snapshot [--full]
471
+ click <ref> ref = e1, e2, ... from last snapshot
472
+ fill <ref> <text...> tap then enter text (uses Maestro flow — fast on long text)
473
+ clear <ref> tap then erase the field's existing text (Maestro eraseText)
474
+ tap-id <testID> tap by testID directly (skips snapshot — saves a hierarchy call)
475
+ fill-id <testID> <text...> tap by id + inputText in one Maestro flow (fastest combo)
476
+ wait-text <substring> [timeout-sec] poll hierarchy for text to appear, default 10s
477
+ press <BACK|ENTER|HOME|TAB|ESCAPE> (iOS: ENTER + HOME via Maestro; BACK is Android-only)
478
+ screenshot <path>
479
+ logs [--since <sec>] [--errors]
480
+ logs-clear
481
+ deep-link <url>
482
+ open-url <url> open a URL in the device browser (Safari/Chrome) — alias of deep-link
483
+ running
484
+ record-start <path> | record-stop
485
+ `);
486
+ process.exit(0);
487
+ }
488
+ const state = loadState();
489
+ try {
490
+ switch (cmd) {
491
+ case 'set-device': {
492
+ state.device = args[0];
493
+ state.platform = platformFromDevice(args[0]);
494
+ saveState(state);
495
+ console.log(`device=${state.device} platform=${state.platform}`);
496
+ return;
497
+ }
498
+ case 'set-app': {
499
+ reqDevice(state);
500
+ state.appId = args[0];
501
+ saveState(state);
502
+ console.log(`appId=${state.appId}`);
503
+ return;
504
+ }
505
+ case 'info': {
506
+ console.log(JSON.stringify({ device: state.device, platform: state.platform, appId: state.appId, refs: Object.keys(state.refs || {}).length, capturedAt: state.capturedAt }, null, 2));
507
+ return;
508
+ }
509
+ case 'launch': { const r = launch(state); process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err); return; }
510
+ case 'stop': { const r = stop(state); process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err); return; }
511
+ case 'relaunch-clean': { const r = relaunchClean(state); process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err); return; }
512
+ case 'snapshot': {
513
+ const full = args.includes('--full');
514
+ const { tree, count } = snapshot(state, { full });
515
+ console.log(tree);
516
+ console.log(`\n(${count} refs captured)`);
517
+ return;
518
+ }
519
+ case 'click': {
520
+ const r = tap(state, args[0]);
521
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `tapped ${args[0]}`); return;
522
+ }
523
+ case 'tap-id': {
524
+ const r = tapById(state, args[0]);
525
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `tapped id=${args[0]}`); return;
526
+ }
527
+ case 'fill': {
528
+ const ref = args[0]; const text = args.slice(1).join(' ');
529
+ const r = fill(state, ref, text);
530
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `filled ${ref}`); return;
531
+ }
532
+ case 'clear': {
533
+ const r = clearField(state, args[0]);
534
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `cleared ${args[0]}`); return;
535
+ }
536
+ case 'fill-id': {
537
+ const id = args[0]; const text = args.slice(1).join(' ');
538
+ const r = fillById(state, id, text);
539
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `filled id=${id}`); return;
540
+ }
541
+ case 'wait-text': {
542
+ const r = waitText(state, args[0], args[1] ? parseInt(args[1], 10) : 10);
543
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err); return;
544
+ }
545
+ case 'press': {
546
+ const r = press(state, args[0]);
547
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `pressed ${args[0]}`); return;
548
+ }
549
+ case 'screenshot': {
550
+ const r = screenshot(state, args[0]);
551
+ process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `saved ${args[0]}`); return;
552
+ }
553
+ case 'logs': console.log(logs(state, args)); return;
554
+ case 'logs-clear': { const r = logsClear(state); console.log(r.out || r.err); return; }
555
+ case 'deep-link': { const r = deepLink(state, args[0]); process.exitCode = r.ok ? 0 : 1; console.log(r.out || r.err || `opened ${args[0]}`); return; }
556
+ // open-url — ergonomic alias of deep-link for browser targets. simctl openurl /
557
+ // am start VIEW already opens any http(s) URL in the device browser; the URL does
558
+ // not need to be registered as an app-scoped deep link.
559
+ case 'open-url': { const r = deepLink(state, args[0]); process.exitCode = r.ok ? 0 : 1; console.log(r.ok ? `opened ${args[0]}` : (r.err || r.out)); return; }
560
+ case 'running': console.log(running(state)); return;
561
+ case 'record-start': { const r = recordStart(state, args[0]); console.log(r.out); return; }
562
+ case 'record-stop': { const r = recordStop(); console.log(r.out); return; }
563
+ default:
564
+ console.error(`Unknown command: ${cmd}. Run with --help.`);
565
+ process.exit(2);
566
+ }
567
+ } catch (e) {
568
+ console.error(`mobile-cli error: ${e.message}`);
569
+ process.exit(1);
570
+ }
571
+ }
572
+
573
+ main();
package/bin/wadb ADDED
@@ -0,0 +1,6 @@
1
+ #!/bin/bash
2
+ # wadb — wrapped adb for subagents. Sets ANDROID_HOME so PATH lookup of adb works
3
+ # regardless of caller env. Use for direct adb commands (logcat, pm clear, am start, etc.)
4
+ # that aren't covered by mcli.
5
+ export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
6
+ exec "$ANDROID_HOME/platform-tools/adb" "$@"
package/bin/wk-ios ADDED
@@ -0,0 +1,58 @@
1
+ #!/usr/bin/env bash
2
+ # wk-ios — turn-key WebKit DOM bridge for the iOS Simulator's Safari.
3
+ #
4
+ # WHY: Maestro/mobile-cli read the native XCUITest a11y tree, which collapses Safari's
5
+ # web content into unlabeled nodes. The DOM itself is fully addressable via WebKit's
6
+ # Remote Inspector. This wrapper wires up ios-webkit-debug-proxy (iwdp) against the
7
+ # running Simulator and evaluates JS in the frontmost Safari page — same power as
8
+ # `playwright-cli eval` on desktop, but on the REAL iOS engine.
9
+ #
10
+ # USAGE:
11
+ # bin/wk-ios "<js-expression>" # evaluate JS in the sim's Safari, print result
12
+ # bin/wk-ios --url # just print the page WebSocket URL
13
+ # bin/wk-ios --stop # stop the background iwdp proxy
14
+ #
15
+ # REQUIRES: brew install ios-webkit-debug-proxy ; a booted iOS Simulator with Safari
16
+ # on a page (open one via: bin/mcli set-app com.apple.mobilesafari; bin/mcli open-url <url>).
17
+ set -euo pipefail
18
+
19
+ HERE="$(cd "$(dirname "$0")" && pwd)"
20
+ IWDP_LOG="${TMPDIR:-/tmp}/wk-ios-iwdp.log"
21
+ IWDP_PIDFILE="${TMPDIR:-/tmp}/wk-ios-iwdp.pid"
22
+
23
+ stop_proxy() {
24
+ if [[ -f "$IWDP_PIDFILE" ]]; then kill "$(cat "$IWDP_PIDFILE")" 2>/dev/null || true; rm -f "$IWDP_PIDFILE"; fi
25
+ pkill -f "ios_webkit_debug_proxy .*webinspectord_sim" 2>/dev/null || true
26
+ }
27
+
28
+ if [[ "${1:-}" == "--stop" ]]; then stop_proxy; echo "iwdp stopped"; exit 0; fi
29
+
30
+ command -v ios_webkit_debug_proxy >/dev/null || { echo "missing: brew install ios-webkit-debug-proxy" >&2; exit 1; }
31
+
32
+ # 1) Find the simulator's web inspector unix socket.
33
+ SOCK="$(lsof -U 2>/dev/null | grep -oE '/private/var/tmp/[^ ]+webinspectord_sim.socket' | head -1 || true)"
34
+ [[ -n "$SOCK" ]] || { echo "no webinspectord_sim socket — is a Simulator booted with Safari open?" >&2; exit 1; }
35
+
36
+ # 2) Ensure iwdp is running against that socket.
37
+ if ! curl -s http://localhost:9221/json >/dev/null 2>&1; then
38
+ ios_webkit_debug_proxy -F -s "unix:$SOCK" > "$IWDP_LOG" 2>&1 &
39
+ echo $! > "$IWDP_PIDFILE"
40
+ for i in $(seq 1 20); do curl -s http://localhost:9221/json >/dev/null 2>&1 && break; sleep 0.25; done
41
+ fi
42
+
43
+ # 3) Resolve the frontmost page's WebSocket URL (device is assigned port 9222).
44
+ # Retry briefly: right after iwdp starts, :9221 answers before the per-device
45
+ # page list on :9222 is populated.
46
+ WS=""
47
+ for i in $(seq 1 20); do
48
+ WS="$(curl -s http://localhost:9222/json 2>/dev/null | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d[0]["webSocketDebuggerUrl"] if d else "")' 2>/dev/null || true)"
49
+ [[ -n "$WS" ]] && break
50
+ sleep 0.25
51
+ done
52
+ [[ -n "$WS" ]] || { echo "no inspectable Safari page found on :9222 (open a URL in the sim Safari first)" >&2; exit 1; }
53
+
54
+ if [[ "${1:-}" == "--url" ]]; then echo "$WS"; exit 0; fi
55
+ [[ $# -ge 1 ]] || { echo "usage: wk-ios \"<js-expression>\" | --url | --stop" >&2; exit 2; }
56
+
57
+ # 4) Evaluate via the Target-wrapped WebKit protocol bridge.
58
+ WK_WS="$WS" node "$HERE/wkeval.mjs" "$1"