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.
- package/README.md +85 -0
- package/bin/mcli +16 -0
- package/bin/mobile-cli.mjs +573 -0
- package/bin/wadb +6 -0
- package/bin/wk-ios +58 -0
- package/bin/wkeval.mjs +44 -0
- package/data/knowledge/learned-patterns.md +85 -0
- package/data/knowledge/manifest.yml +2 -1
- package/data/targets/_example-mobile-emulation.yml +52 -0
- package/data/targets/_example-native-mobile.yml +61 -0
- package/data/targets/_example-sim-android-chrome.yml +81 -0
- package/data/targets/_example-sim-ios-safari.yml +80 -0
- package/dist/cli/index.js +156 -33
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +260 -527
- package/dist/index.js +142 -12
- package/dist/index.js.map +1 -1
- package/docs/MOBILE-SETUP.md +92 -0
- package/package.json +33 -11
- package/scripts/doctor-mobile.sh +143 -0
- package/scripts/setup-mobile.sh +213 -0
- package/skills/qa-explore/SKILL.md +2 -1
- package/skills/qa-explore/phases/00-setup.md +22 -1
- package/skills/qa-explore/phases/01-auth.md +4 -0
- package/skills/qa-explore/phases/03-discovery.md +14 -0
- package/skills/qa-explore/phases/05-features.md +20 -0
- package/skills/qa-explore/phases/06-edge-cases.md +2 -0
- package/skills/qa-explore/phases/07-reporting.md +11 -0
- package/skills/qa-explore/references/playwright-agents-integration.md +126 -0
- package/skills/qa-explore-mobile/SKILL.md +146 -0
- package/skills/qa-explore-mobile/phases/00-setup.md +203 -0
- package/skills/qa-explore-mobile/phases/01-auth.md +127 -0
- package/skills/qa-explore-mobile/phases/02-charter.md +70 -0
- package/skills/qa-explore-mobile/phases/03-discovery.md +79 -0
- package/skills/qa-explore-mobile/phases/04-journeys.md +49 -0
- package/skills/qa-explore-mobile/phases/05-features.md +72 -0
- package/skills/qa-explore-mobile/phases/06-edge-cases.md +157 -0
- package/skills/qa-explore-mobile/phases/07-reporting.md +123 -0
- package/skills/qa-explore-mobile/references/mobile-edges.md +117 -0
- package/skills/qa-explore-quick/SKILL.md +7 -0
- package/skills/qa-target-setup/SKILL.md +12 -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"
|