@flowspec-qa/runner-core 0.2.1 → 0.2.3

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/src/discovery.ts CHANGED
@@ -1,16 +1,44 @@
1
- import { execSync } from 'child_process';
1
+ import { execSync, spawnSync } from 'child_process';
2
2
  import fs from 'fs';
3
+ import os from 'os';
3
4
  import path from 'path';
4
5
  import chalk from 'chalk';
5
- import { XMLParser } from 'fast-xml-parser';
6
6
  import { FlowSpecQAApi } from './api-client.js';
7
7
 
8
+ const sleep = (ms: number) => new Promise(r => setTimeout(r, ms));
9
+
10
+ // ─── ADB path resolution (mirrors devices.ts) ───────────────────────────────
11
+ const ADB_COMMON_PATHS = [
12
+ 'adb',
13
+ '/opt/homebrew/share/android-commandlinetools/platform-tools/adb',
14
+ `${process.env.HOME}/Library/Android/sdk/platform-tools/adb`,
15
+ '/usr/local/share/android-commandlinetools/platform-tools/adb',
16
+ '/usr/local/bin/adb',
17
+ `${process.env.ANDROID_HOME}/platform-tools/adb`,
18
+ `${process.env.ANDROID_SDK_ROOT}/platform-tools/adb`,
19
+ ];
20
+
21
+ function resolveAdb(): string {
22
+ for (const candidate of ADB_COMMON_PATHS) {
23
+ if (!candidate) continue;
24
+ try {
25
+ execSync(`"${candidate}" version`, { stdio: 'ignore', timeout: 2000 });
26
+ return candidate;
27
+ } catch {}
28
+ }
29
+ throw new Error('adb not found. Install Android SDK platform-tools and add to PATH.');
30
+ }
31
+
8
32
  export interface DiscoveryOptions {
9
33
  url: string;
10
34
  framework: 'playwright' | 'maestro';
11
35
  projectId?: string;
12
36
  entityId?: string;
13
37
  outputDir?: string;
38
+ username?: string;
39
+ password?: string;
40
+ /** Android device serial (from `flowspecqa devices`). Required when multiple Android devices are connected. */
41
+ deviceId?: string;
14
42
  }
15
43
 
16
44
  export interface DiscoveryResult {
@@ -63,41 +91,287 @@ export const discoveryEngine = {
63
91
  return result;
64
92
  },
65
93
 
94
+ /** Capture maestro hierarchy from current screen and return parsed JSON */
95
+ async _captureHierarchy(env?: NodeJS.ProcessEnv): Promise<any> {
96
+ const rawOutput = execSync('maestro hierarchy', {
97
+ encoding: 'utf8',
98
+ stdio: ['ignore', 'pipe', 'pipe'],
99
+ env: env ?? process.env,
100
+ });
101
+ const lines = rawOutput.split('\n');
102
+ const jsonStart = lines.findIndex(l => l.trim().startsWith('{'));
103
+ const jsonStr = jsonStart >= 0 ? lines.slice(jsonStart).join('\n') : rawOutput;
104
+ return JSON.parse(jsonStr);
105
+ },
106
+
107
+ /** Execute a Maestro YAML flow (written to a temp file) */
108
+ _runMaestroFlow(appId: string, steps: string[], env?: NodeJS.ProcessEnv): boolean {
109
+ const yaml = `appId: ${appId}\n---\n${steps.join('\n')}\n`;
110
+ const tmpFile = path.join(os.tmpdir(), `discovery_flow_${Date.now()}.yaml`);
111
+ fs.writeFileSync(tmpFile, yaml);
112
+ try {
113
+ const result = spawnSync('maestro', ['test', tmpFile], {
114
+ encoding: 'utf8',
115
+ timeout: 120000,
116
+ stdio: ['ignore', 'pipe', 'pipe'],
117
+ env: env ?? process.env,
118
+ });
119
+ fs.unlinkSync(tmpFile);
120
+ return result.status === 0;
121
+ } catch {
122
+ try { fs.unlinkSync(tmpFile); } catch {}
123
+ return false;
124
+ }
125
+ },
126
+
66
127
  async discoverMobile(options: DiscoveryOptions): Promise<DiscoveryResult> {
67
- console.log(chalk.gray('📱 Capturing real Maestro hierarchy...'));
128
+ const appId = options.url;
129
+ const username = options.username || '';
130
+ const password = options.password || '';
131
+ const adb = resolveAdb();
132
+ // -s flag for device targeting when serial is provided
133
+ const adbS = options.deviceId ? `"${adb}" -s ${options.deviceId}` : `"${adb}"`;
134
+ // Maestro device env var
135
+ const maestroEnv = options.deviceId
136
+ ? { ...process.env, MAESTRO_DEVICE_ID: options.deviceId }
137
+ : process.env;
138
+
139
+ console.log(chalk.gray(`📱 Starting multi-screen autonomous discovery${options.deviceId ? ` on device ${options.deviceId}` : ''}...`));
140
+
141
+ const allScreens: { name: string; elements: any[]; hierarchy: any }[] = [];
142
+
68
143
  try {
69
- const hierarchyXml = execSync('maestro hierarchy', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
70
-
71
- const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: '@_' });
72
- const jsonObj = parser.parse(hierarchyXml);
73
-
74
- const elements = this.extractMaestroSelectors(jsonObj);
75
-
76
- const planContent = `# Discovery Plan: Mobile App (${options.url})
77
- Generated: ${new Date().toISOString()}
144
+ // ── Reset app state ───────────────────────────────────────────────
145
+ console.log(chalk.gray(' 🔄 Resetting app state...'));
146
+ try { execSync(`${adbS} shell am force-stop ${appId}`, { stdio: 'ignore' }); } catch {}
147
+ try { execSync(`${adbS} shell pm clear ${appId}`, { stdio: 'ignore' }); } catch {}
148
+ await sleep(1000);
149
+
150
+ // ── Screen 1: Launch & capture Login ─────────────────────────────
151
+ console.log(chalk.gray(' 📸 Screen 1/3 — Login...'));
152
+ execSync(`${adbS} shell monkey -p ${appId} -c android.intent.category.LAUNCHER 1`, { stdio: 'ignore' });
153
+ await sleep(2500);
154
+
155
+ const loginHierarchy = await this._captureHierarchy(maestroEnv);
156
+ const loginElements = this.extractMaestroSelectors(loginHierarchy);
157
+ allScreens.push({ name: 'Login', elements: loginElements, hierarchy: loginHierarchy });
158
+ console.log(chalk.green(` ✅ Login: ${loginElements.length} elements`));
159
+
160
+ // ── Error state: Login — submit empty to reveal tv_error ─────────
161
+ console.log(chalk.gray(' 📸 Screen 1 error state — empty submit...'));
162
+ const emptyLoginOk = this._runMaestroFlow(appId, [
163
+ `- tapOn:\n id: "btn_login"`,
164
+ `- waitForAnimationToEnd:\n timeout: 1500`,
165
+ ], maestroEnv);
166
+ if (emptyLoginOk) {
167
+ const loginErrorHierarchy = await this._captureHierarchy(maestroEnv);
168
+ const loginErrorAll = this.extractMaestroSelectors(loginErrorHierarchy);
169
+ const knownLoginIds = new Set(loginElements.map(e => e.id));
170
+ const loginErrorNew = loginErrorAll.filter(e => !knownLoginIds.has(e.id));
171
+ if (loginErrorNew.length > 0) {
172
+ allScreens.push({ name: 'Login (Error State)', elements: loginErrorNew, hierarchy: loginErrorHierarchy });
173
+ console.log(chalk.green(` ✅ Login error state: ${loginErrorNew.length} new elements (e.g. ${loginErrorNew.map(e => e.id).join(', ')})`));
174
+ }
175
+ }
78
176
 
79
- ## Screen Intelligence
80
- Managed by Maestro Autonomous Engine.
177
+ // ── Navigate to Screen 2: Accounts (via login) ───────────────────
178
+ if (username && password) {
179
+ console.log(chalk.gray(' 🔐 Logging in to discover authenticated screens...'));
180
+
181
+ // Run login steps — no success assertion here (extendedWaitUntil is flaky).
182
+ // We verify login success afterward by inspecting the hierarchy.
183
+ this._runMaestroFlow(appId, [
184
+ // clearState must be a property of launchApp, not a standalone command
185
+ `- launchApp:\n clearState: true`,
186
+ `- waitForAnimationToEnd`,
187
+ `- tapOn:\n id: "et_username"`,
188
+ `- eraseText: 50`,
189
+ `- inputText: "${username}"`,
190
+ `- waitForAnimationToEnd`,
191
+ // Dismiss keyboard so et_password is not covered on smaller screens
192
+ `- hideKeyboard`,
193
+ `- tapOn:\n id: "et_password"`,
194
+ `- eraseText: 30`,
195
+ `- inputText: "${password}"`,
196
+ `- waitForAnimationToEnd`,
197
+ // Dismiss keyboard so btn_login is not covered
198
+ `- hideKeyboard`,
199
+ `- tapOn:\n id: "btn_login"`,
200
+ `- waitForAnimationToEnd`,
201
+ ], maestroEnv);
202
+
203
+ // Give the app extra time to complete the login network request & navigate
204
+ await sleep(3000);
205
+
206
+ // Verify login success by checking what screen we're on
207
+ let postLoginHierarchy: any;
208
+ try { postLoginHierarchy = await this._captureHierarchy(maestroEnv); } catch { postLoginHierarchy = null; }
209
+ const postLoginElements = postLoginHierarchy ? this.extractMaestroSelectors(postLoginHierarchy) : [];
210
+ const loginSuccess = postLoginElements.some(e => e.id === 'tv_welcome' || e.id === 'tv_total_balance');
211
+
212
+ if (loginSuccess) {
213
+ console.log(chalk.gray(' 📸 Screen 2/3 — Accounts...'));
214
+ await sleep(1500);
215
+ const accountsHierarchy = await this._captureHierarchy(maestroEnv);
216
+ const accountsElements = this.extractMaestroSelectors(accountsHierarchy);
217
+ allScreens.push({ name: 'Accounts', elements: accountsElements, hierarchy: accountsHierarchy });
218
+ console.log(chalk.green(` ✅ Accounts: ${accountsElements.length} elements`));
219
+
220
+ // ── Navigate to Screen 3: Transfer ─────────────────────────
221
+ console.log(chalk.gray(' 📸 Screen 3/3 — Transfer...'));
222
+ const navSuccess = this._runMaestroFlow(appId, [
223
+ `- tapOn:\n id: "btn_transfer"`,
224
+ `- waitForAnimationToEnd`,
225
+ // No text assertion — Transfer screen title is unknown until discovery runs
226
+ ], maestroEnv);
227
+
228
+ if (navSuccess) {
229
+ await sleep(1200);
230
+ const transferHierarchy = await this._captureHierarchy(maestroEnv);
231
+ const transferElements = this.extractMaestroSelectors(transferHierarchy);
232
+ allScreens.push({ name: 'Transfer', elements: transferElements, hierarchy: transferHierarchy });
233
+ console.log(chalk.green(` ✅ Transfer: ${transferElements.length} elements`));
234
+
235
+ // ── Error state: Transfer — submit empty amount ─────────
236
+ console.log(chalk.gray(' 📸 Transfer error state — empty amount submit...'));
237
+ const emptyTransferOk = this._runMaestroFlow(appId, [
238
+ `- tapOn:\n id: "btn_confirm"`,
239
+ `- waitForAnimationToEnd:\n timeout: 1500`,
240
+ ], maestroEnv);
241
+ if (emptyTransferOk) {
242
+ const transferErrorHierarchy = await this._captureHierarchy(maestroEnv);
243
+ const transferErrorAll = this.extractMaestroSelectors(transferErrorHierarchy);
244
+ const knownTransferIds = new Set(transferElements.map(e => e.id));
245
+ const transferErrorNew = transferErrorAll.filter(e => !knownTransferIds.has(e.id));
246
+ if (transferErrorNew.length > 0) {
247
+ allScreens.push({ name: 'Transfer (Error State)', elements: transferErrorNew, hierarchy: transferErrorHierarchy });
248
+ console.log(chalk.green(` ✅ Transfer error state: ${transferErrorNew.length} new elements (e.g. ${transferErrorNew.map(e => e.id).join(', ')})`));
249
+ }
250
+ }
251
+ } else {
252
+ console.log(chalk.yellow(' ⚠️ Transfer screen not reachable — skipping'));
253
+ }
254
+ } else {
255
+ console.log(chalk.yellow(' ⚠️ Login failed — only Login screen captured'));
256
+ }
257
+ }
81
258
 
82
- ### Interactive Elements Map
259
+ // ── Build comprehensive discovery plan ────────────────────────────
260
+ const totalElements = allScreens.reduce((sum, s) => sum + s.elements.length, 0);
261
+
262
+ const screenSections = allScreens.map(screen => `
263
+ ### Screen: ${screen.name}
83
264
  | Element Type | Text/Content | testID / Identifier |
84
265
  |--------------|--------------|---------------------|
85
- ${elements.map(e => `| ${e.type} | ${e.text} | \`${e.id}\` |`).join('\n')}
266
+ ${screen.elements.map(e => `| ${e.type} | ${e.text} | \`${e.id}\` |`).join('\n') || '| — | No interactive elements found | — |'}
267
+ `).join('\n');
268
+
269
+ const planContent = `# Discovery Plan: Mobile App (${appId})
270
+ Generated: ${new Date().toISOString()}
271
+
272
+ ## App Overview
273
+ - **App ID**: ${appId}
274
+ - **Screens discovered**: ${allScreens.length}
275
+ - **Total interactive elements**: ${totalElements}
276
+ - **Framework**: Maestro (Android native)
277
+ - **Device**: Physical device (ADB)
278
+
279
+ ## Screen Intelligence
280
+ ${screenSections}
281
+
282
+ ## Suggested Test Flows
283
+
284
+ ### Flow 1 — Login con credenciales válidas
285
+ 1. Ingresar email en \`et_username\`
286
+ 2. Ingresar contraseña en \`et_password\`
287
+ 3. Tap \`btn_login\`
288
+ 4. Verificar pantalla de cuentas visible
289
+
290
+ ### Flow 2 — Login con credenciales inválidas
291
+ 1. Ingresar email incorrecto
292
+ 2. Ingresar contraseña incorrecta
293
+ 3. Tap \`btn_login\`
294
+ 4. Verificar mensaje de error visible
295
+
296
+ ### Flow 3 — Consulta de saldo
297
+ 1. Login exitoso
298
+ 2. Verificar \`tv_total_balance\` visible
299
+ 3. Verificar \`card_checking\` y \`card_savings\` presentes
300
+
301
+ ### Flow 4 — Transferencia exitosa
302
+ 1. Login → tap \`btn_transfer\`
303
+ 2. Ingresar monto en \`et_amount\`
304
+ 3. Ingresar destinatario en \`et_recipient\`
305
+ 4. Tap \`btn_confirm\`
306
+ 5. Verificar mensaje de éxito
307
+
308
+ ### Flow 5 — Transferencia con monto inválido
309
+ 1. Login → tap \`btn_transfer\`
310
+ 2. Dejar monto vacío
311
+ 3. Tap \`btn_confirm\`
312
+ 4. Verificar mensaje de error
313
+
314
+ ### Flow 6 — Logout
315
+ 1. Login exitoso
316
+ 2. Tap \`btn_logout\`
317
+ 3. Verificar redirección a Login screen
86
318
 
87
319
  ## UI Health
88
- - Total interactive nodes detected: ${elements.length}
89
- - Screen structure complexity: Medium
320
+ - Total interactive nodes detected: ${totalElements}
321
+ - Screens mapped: ${allScreens.map(s => s.name).join(', ')}
322
+ - Screen structure complexity: ${totalElements > 15 ? 'High' : totalElements > 8 ? 'Medium' : 'Low'}
90
323
  `;
91
324
 
92
- return { planContent, rawScanData: jsonObj };
93
- } catch (error) {
94
- return {
95
- planContent: `# Discovery Plan: Mobile App
96
- Status: FAIL (Maestro CLI not detected or no device running).
97
- Please ensure an emulator is open and Maestro is installed.
98
- `,
99
- rawScanData: { error: 'Mobile environment not ready' }
100
- };
325
+ return {
326
+ planContent,
327
+ rawScanData: {
328
+ screens: allScreens.map(s => ({ name: s.name, elements: s.elements })),
329
+ total: totalElements,
330
+ appId,
331
+ framework: 'maestro',
332
+ },
333
+ };
334
+
335
+ } catch (error: any) {
336
+ console.log(chalk.red(` ❌ Discovery error: ${error.message}`));
337
+ return {
338
+ planContent: `# Discovery Plan: Mobile App (${appId})\nStatus: FAIL\nError: ${error.message}\n`,
339
+ rawScanData: { error: error.message },
340
+ };
341
+ }
342
+ },
343
+
344
+ async handleLogin(page: any, username: string, password: string): Promise<boolean> {
345
+ try {
346
+ const passwordField = page.locator('input[type="password"]').first();
347
+ const count = await passwordField.count();
348
+ if (count === 0) return false;
349
+
350
+ console.log(chalk.gray('🔐 Login form detected — filling credentials...'));
351
+
352
+ const usernameField = page.locator(
353
+ 'input[type="email"], input[name="email"], input[name="username"], input[name="user"], ' +
354
+ 'input[placeholder*="correo" i], input[placeholder*="email" i], input[placeholder*="usuario" i]'
355
+ ).first();
356
+
357
+ await usernameField.fill(username);
358
+ await passwordField.fill(password);
359
+
360
+ const submitBtn = page.locator(
361
+ 'button[type="submit"], input[type="submit"], ' +
362
+ 'button:has-text("Ingresar"), button:has-text("Login"), ' +
363
+ 'button:has-text("Sign in"), button:has-text("Entrar"), button:has-text("Iniciar")'
364
+ ).first();
365
+
366
+ await submitBtn.click();
367
+ await page.waitForLoadState('networkidle', { timeout: 10000 }).catch(() => {});
368
+ await page.waitForTimeout(600);
369
+
370
+ console.log(chalk.green('✅ Login successful — continuing discovery on authenticated page...'));
371
+ return true;
372
+ } catch (err: any) {
373
+ console.log(chalk.yellow(`⚠️ Login attempt failed: ${err.message}`));
374
+ return false;
101
375
  }
102
376
  },
103
377
 
@@ -113,6 +387,12 @@ Please ensure an emulator is open and Maestro is installed.
113
387
 
114
388
  try {
115
389
  await page.goto(options.url, { waitUntil: 'networkidle' });
390
+
391
+ // ── Handle login if credentials provided ────────────────────────
392
+ if (options.username && options.password) {
393
+ await this.handleLogin(page, options.username, options.password);
394
+ }
395
+
116
396
  const title = await page.title();
117
397
 
118
398
  // ── Phase 1: Extract DOM elements ────────────────────────────────
@@ -237,33 +517,47 @@ ${elements.slice(0, 20).map((e: any) => {
237
517
  },
238
518
 
239
519
  extractMaestroSelectors(node: any): any[] {
240
- let elements: any[] = [];
241
-
520
+ const elements: any[] = [];
521
+ const INTERACTIVE_CLASSES = [
522
+ 'android.widget.Button',
523
+ 'android.widget.EditText',
524
+ 'android.widget.CheckBox',
525
+ 'android.widget.RadioButton',
526
+ 'android.widget.Switch',
527
+ 'android.widget.ImageButton',
528
+ 'android.widget.TextView',
529
+ ];
530
+
242
531
  const traverse = (current: any) => {
243
- if (!current) return;
244
-
245
- const attrs = current;
246
- if (attrs['@_resource-id'] || attrs['@_text'] || attrs['@_content-desc']) {
247
- if (['android.widget.Button', 'android.widget.EditText', 'android.view.ViewGroup'].includes(attrs['@_class'])) {
248
- elements.push({
249
- type: attrs['@_class'].split('.').pop(),
250
- text: attrs['@_text'] || attrs['@_content-desc'] || 'N/A',
251
- id: attrs['@_resource-id'] || 'N/A'
252
- });
253
- }
532
+ if (!current || typeof current !== 'object') return;
533
+
534
+ // maestro hierarchy JSON format: { attributes: {...}, children: [...] }
535
+ const attrs = current.attributes || {};
536
+ const resourceId: string = attrs['resource-id'] || '';
537
+ const text: string = attrs['text'] || attrs['accessibilityText'] || attrs['hintText'] || '';
538
+ const cls: string = attrs['class'] || '';
539
+ const clickable: boolean = attrs['clickable'] === 'true';
540
+
541
+ // Only include app-specific elements (skip Android system UI)
542
+ const isAppElement = resourceId && !resourceId.startsWith('android:id/') && !resourceId.startsWith('com.android.');
543
+ const isInteractive = INTERACTIVE_CLASSES.includes(cls) || clickable;
544
+
545
+ if (isAppElement && isInteractive) {
546
+ elements.push({
547
+ type: cls.split('.').pop() || cls,
548
+ text: text || 'N/A',
549
+ id: resourceId.includes('/') ? resourceId.split('/')[1] : resourceId,
550
+ });
254
551
  }
255
552
 
256
- // Handle children
257
- if (current.node) {
258
- if (Array.isArray(current.node)) {
259
- current.node.forEach(traverse);
260
- } else {
261
- traverse(current.node);
262
- }
553
+ // Recurse into children
554
+ const children = current.children || [];
555
+ for (const child of children) {
556
+ traverse(child);
263
557
  }
264
558
  };
265
559
 
266
560
  traverse(node);
267
- return elements.slice(0, 15);
561
+ return elements.slice(0, 30);
268
562
  }
269
563
  };
package/src/executor.ts CHANGED
@@ -1,8 +1,17 @@
1
1
  import { execa, ExecaError } from 'execa';
2
2
  import chalk from 'chalk';
3
3
  import path from 'path';
4
- import { existsSync } from 'fs';
4
+ import { existsSync, mkdtempSync, cpSync } from 'fs';
5
+ import { tmpdir } from 'os';
5
6
  import type { TestResultItem } from './api-client.js';
7
+ import type { DeviceInfo } from './devices.js';
8
+
9
+ // ─── Multi-device result ─────────────────────────────────────────────────────
10
+
11
+ export interface DeviceResult {
12
+ device: DeviceInfo;
13
+ execution: ExecutionResult;
14
+ }
6
15
 
7
16
  export interface ExecutionOptions {
8
17
  env?: Record<string, string>; // Environment vars (base URLs, tokens — stay local, never uploaded)
@@ -244,6 +253,33 @@ export async function executeMaestro(
244
253
  let content = fsMod.readFileSync(fp, 'utf8');
245
254
  let changed = false;
246
255
 
256
+ // ── Maestro compatibility shim ──────────────────────────────
257
+ // Fix invalid commands generated by the AI that Maestro does not support
258
+
259
+ // Ensure clearState: true so each test starts from a clean session.
260
+ // Without it, app state persists between tests (SharedPreferences)
261
+ // causing subsequent tests to skip the login screen entirely.
262
+ if (/^- launchApp\s*$/m.test(content)) {
263
+ content = content.replace(/^- launchApp\s*$/gm, '- launchApp:\n clearState: true');
264
+ changed = true;
265
+ }
266
+
267
+ if (content.includes('- typeText:')) {
268
+ // `typeText` → `inputText` (correct Maestro command)
269
+ content = content.replace(/^- typeText:/gm, '- inputText:');
270
+ changed = true;
271
+ }
272
+ if (content.includes('- clearText')) {
273
+ // `clearText` → `eraseText: 50` (erases up to 50 chars from focused field)
274
+ content = content.replace(/^- clearText\s*$/gm, '- eraseText: 50');
275
+ changed = true;
276
+ }
277
+ if (content.includes('- toggleAirplaneMode')) {
278
+ // `toggleAirplaneMode` is not a valid Maestro command — skip gracefully
279
+ content = content.replace(/^- toggleAirplaneMode\s*$/gm, '# toggleAirplaneMode skipped — not supported in this Maestro version');
280
+ changed = true;
281
+ }
282
+
247
283
  if (isExpoGo) {
248
284
  // Expo Go is handled below in a separate two-pass approach
249
285
  changed = true; // placeholder, actual processing below
@@ -292,6 +328,35 @@ export async function executeMaestro(
292
328
  content = content.replace(/(inputText:.*?\n)/g, '$1- waitForAnimationToEnd\n');
293
329
  changed = true;
294
330
  }
331
+
332
+ // ── Keyboard dismiss shim ────────────────────────────────────
333
+ // On Android the soft keyboard covers fields below the focused input.
334
+ // After every inputText → waitForAnimationToEnd sequence, inject
335
+ // `- hideKeyboard` so the next tapOn can reach the covered element.
336
+ // hideKeyboard is a no-op when the keyboard is not shown.
337
+ if (content.includes('- inputText:')) {
338
+ const kbLines = content.split('\n');
339
+ const kbPatched: string[] = [];
340
+ let afterInputText = false;
341
+ for (const kbLine of kbLines) {
342
+ const kbTrimmed = kbLine.trim();
343
+ if (kbTrimmed === '- waitForAnimationToEnd' && afterInputText) {
344
+ kbPatched.push(kbLine);
345
+ kbPatched.push('- hideKeyboard');
346
+ afterInputText = false;
347
+ changed = true;
348
+ } else {
349
+ kbPatched.push(kbLine);
350
+ if (kbTrimmed.startsWith('- inputText:')) {
351
+ afterInputText = true;
352
+ } else if (kbTrimmed !== '' && !kbTrimmed.startsWith('#') && !kbTrimmed.startsWith('- waitForAnimationToEnd')) {
353
+ afterInputText = false;
354
+ }
355
+ }
356
+ }
357
+ content = kbPatched.join('\n');
358
+ }
359
+
295
360
  if (content.includes('Cypress.env')) {
296
361
  content = content.replace(/Cypress.env\(.*?\)/g, "test_password");
297
362
  changed = true;
@@ -412,7 +477,12 @@ export async function executeMaestro(
412
477
  }
413
478
  } catch (e) {}
414
479
 
480
+ // Device targeting: --device flag must come BEFORE the 'test' subcommand
481
+ const deviceId = options.env?._FLOWSPECQA_DEVICE_ID;
482
+ const maestroBaseArgs = deviceId ? ['--device', deviceId] : [];
483
+
415
484
  const args = [
485
+ ...maestroBaseArgs,
416
486
  'test',
417
487
  '--format', 'junit',
418
488
  '--output', reportPath,
@@ -488,6 +558,75 @@ export async function executeMaestro(
488
558
  return { exitCode, results, startedAt, finishedAt, stdout, stderr };
489
559
  }
490
560
 
561
+ /**
562
+ * Run a Maestro suite in parallel across multiple connected devices.
563
+ * Each device gets an isolated copy of the suite directory so reports
564
+ * don't collide. Results are returned per-device, in the same order
565
+ * as the input devices array.
566
+ */
567
+ export async function executeMaestroMultiDevice(
568
+ suiteDir: string,
569
+ devices: DeviceInfo[],
570
+ options: ExecutionOptions = {}
571
+ ): Promise<DeviceResult[]> {
572
+ if (devices.length === 0) return [];
573
+ if (devices.length === 1) {
574
+ const execution = await _executeMaestroOnDevice(suiteDir, devices[0], options);
575
+ return [{ device: devices[0], execution }];
576
+ }
577
+
578
+ // Run all devices in parallel — each gets its own temp dir copy
579
+ const tasks = devices.map(async (device): Promise<DeviceResult> => {
580
+ // Isolated copy so JUnit XML reports don't overwrite each other
581
+ const deviceDir = mkdtempSync(path.join(tmpdir(), `flowspecqa_${device.id}_`));
582
+ try {
583
+ cpSync(suiteDir, deviceDir, { recursive: true });
584
+ const execution = await _executeMaestroOnDevice(deviceDir, device, options);
585
+ return { device, execution };
586
+ } finally {
587
+ // best-effort cleanup
588
+ try { (await import('fs')).rmSync(deviceDir, { recursive: true, force: true }); } catch {}
589
+ }
590
+ });
591
+
592
+ return Promise.all(tasks);
593
+ }
594
+
595
+ /**
596
+ * Run Maestro on a single specific device (Android or iOS).
597
+ * Passes --device flag to Maestro CLI to target the correct device.
598
+ */
599
+ async function _executeMaestroOnDevice(
600
+ suiteDir: string,
601
+ device: DeviceInfo,
602
+ options: ExecutionOptions
603
+ ): Promise<ExecutionResult> {
604
+ // Patch options.env with the correct APP_ID for this platform if available
605
+ const patchedOptions: ExecutionOptions = {
606
+ ...options,
607
+ env: {
608
+ ...options.env,
609
+ // Allow per-platform APP_ID override: ANDROID_APP_ID / IOS_APP_ID
610
+ ...(device.platform === 'android' && options.env?.ANDROID_APP_ID
611
+ ? { APP_ID: options.env.ANDROID_APP_ID }
612
+ : {}),
613
+ ...(device.platform === 'ios' && options.env?.IOS_APP_ID
614
+ ? { APP_ID: options.env.IOS_APP_ID }
615
+ : {}),
616
+ },
617
+ };
618
+
619
+ // Inject --device flag into the Maestro args by temporarily patching
620
+ // the executor. We achieve this by setting the MAESTRO_DEVICE_ID env
621
+ // which executeMaestro reads via the deviceId option field.
622
+ patchedOptions.env = {
623
+ ...patchedOptions.env,
624
+ _FLOWSPECQA_DEVICE_ID: device.id,
625
+ };
626
+
627
+ return executeMaestro(suiteDir, patchedOptions);
628
+ }
629
+
491
630
  /**
492
631
  * Parse Maestro JUnit XML report into TestResultItem[].
493
632
  * Format: <testsuite><testcase name="..." time="2.3"><failure message="..."/></testcase></testsuite>
package/src/index.ts CHANGED
@@ -3,7 +3,8 @@ export { config, type RunnerConfig } from './config.js';
3
3
  export { login, logout, getAuthStatus, getBearerToken, type AuthStatus } from './auth.js';
4
4
  export { apiClient, FlowSpecQAApi, type Project, type Suite, type IngestResult, type RunResultPayload, type TestResultItem } from './api-client.js';
5
5
  export { downloadSuite, listCachedSuites, evictSuite, type LocalSuite } from './suite-manager.js';
6
- export { executePlaywright, executeCypress, executeMaestro, type ExecutionOptions, type ExecutionResult } from './executor.js';
6
+ export { executePlaywright, executeCypress, executeMaestro, executeMaestroMultiDevice, type ExecutionOptions, type ExecutionResult, type DeviceResult } from './executor.js';
7
+ export { detectAllDevices, detectAndroidDevices, detectIosDevices, readyDevices, type DeviceInfo } from './devices.js';
7
8
  export { sanitizeResults, assertNoSecrets } from './result-sanitizer.js';
8
9
  export { uploadResults, type UploadOptions } from './uploader.js';
9
10
  export { discoveryEngine, type DiscoveryOptions, type DiscoveryResult } from './discovery.js';