@quiesco/core 0.9.0 → 0.11.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 (58) hide show
  1. package/dist/device.d.ts +5 -0
  2. package/dist/device.d.ts.map +1 -1
  3. package/dist/device.js +48 -3
  4. package/dist/device.js.map +1 -1
  5. package/dist/devices/android.d.ts +4 -0
  6. package/dist/devices/android.d.ts.map +1 -1
  7. package/dist/devices/android.js +10 -0
  8. package/dist/devices/android.js.map +1 -1
  9. package/dist/devices/crash.d.ts +24 -0
  10. package/dist/devices/crash.d.ts.map +1 -0
  11. package/dist/devices/crash.js +132 -0
  12. package/dist/devices/crash.js.map +1 -0
  13. package/dist/devices/ios-runner.d.ts +10 -1
  14. package/dist/devices/ios-runner.d.ts.map +1 -1
  15. package/dist/devices/ios-runner.js +17 -6
  16. package/dist/devices/ios-runner.js.map +1 -1
  17. package/dist/devices/ios.d.ts +28 -1
  18. package/dist/devices/ios.d.ts.map +1 -1
  19. package/dist/devices/ios.js +102 -26
  20. package/dist/devices/ios.js.map +1 -1
  21. package/dist/devices/provider.d.ts +23 -0
  22. package/dist/devices/provider.d.ts.map +1 -1
  23. package/dist/devices/provider.js.map +1 -1
  24. package/dist/driver.d.ts +2 -0
  25. package/dist/driver.d.ts.map +1 -1
  26. package/dist/driver.js +21 -6
  27. package/dist/driver.js.map +1 -1
  28. package/dist/errors.d.ts +3 -1
  29. package/dist/errors.d.ts.map +1 -1
  30. package/dist/errors.js.map +1 -1
  31. package/dist/index.d.ts +1 -0
  32. package/dist/index.d.ts.map +1 -1
  33. package/dist/index.js.map +1 -1
  34. package/dist/server/ws-server.d.ts +4 -2
  35. package/dist/server/ws-server.d.ts.map +1 -1
  36. package/dist/server/ws-server.js +16 -2
  37. package/dist/server/ws-server.js.map +1 -1
  38. package/dist/session.d.ts +29 -1
  39. package/dist/session.d.ts.map +1 -1
  40. package/dist/session.js +117 -7
  41. package/dist/session.js.map +1 -1
  42. package/dist/timeline.d.ts +19 -1
  43. package/dist/timeline.d.ts.map +1 -1
  44. package/dist/timeline.js +57 -16
  45. package/dist/timeline.js.map +1 -1
  46. package/package.json +2 -2
  47. package/src/device.ts +44 -2
  48. package/src/devices/android.ts +13 -0
  49. package/src/devices/crash.ts +146 -0
  50. package/src/devices/ios-runner.ts +19 -6
  51. package/src/devices/ios.ts +119 -25
  52. package/src/devices/provider.ts +23 -0
  53. package/src/driver.ts +20 -6
  54. package/src/errors.ts +3 -1
  55. package/src/index.ts +1 -0
  56. package/src/server/ws-server.ts +14 -2
  57. package/src/session.ts +119 -9
  58. package/src/timeline.ts +64 -11
package/src/driver.ts CHANGED
@@ -43,7 +43,7 @@ import { ElementExpectation, checkRatio } from './expect.js';
43
43
  import type { AgentConnection } from './server/ws-server.js';
44
44
  import type { AppRunState, DeviceApi } from './device.js';
45
45
  import type { SyncApi } from './sync-api.js';
46
- import type { Timeline } from './timeline.js';
46
+ import type { CallTiming, Timeline } from './timeline.js';
47
47
  import { WebView } from './webview.js';
48
48
  import { cropToRect } from './screenshots.js';
49
49
  import type { WebViewHost } from './webview.js';
@@ -67,6 +67,8 @@ export interface DriverOptions {
67
67
  appState?: () => AppRunState;
68
68
  /** Where calls are recorded (Phase 6.9 timeline). */
69
69
  timeline?: Timeline;
70
+ /** A call lost its connection: say whether the app crashed (APP_CRASHED, issue #76), else return the error. */
71
+ explainDisconnect?: (e: QuiescoError) => Promise<QuiescoError>;
70
72
  }
71
73
 
72
74
  /** type({ perCharacter: true }): time between two characters, about a quick typist's (issue #52). */
@@ -561,8 +563,11 @@ export class Driver {
561
563
  const covered = e instanceof QuiescoError && (e.errorName === 'ELEMENT_OBSCURED' || (e.errorName === 'ELEMENT_NOT_FOUND' && e.data['reason'] === 'not-in-window'));
562
564
  if (!covered || dismiss === undefined) throw e;
563
565
  const closed = await dismiss().catch(() => [] as string[]);
564
- if (closed.length === 0) throw e;
565
- return this.call('action', params, timeoutMs, steps);
566
+ if (closed.length > 0) return this.call('action', params, timeoutMs, steps);
567
+ // One Quiesco leaves up (a permission alert, issue #86) is the likely reason: say so.
568
+ const unanswered = await this.options.provider.unansweredSystemAlert?.().catch(() => undefined);
569
+ if (unanswered === undefined) throw e;
570
+ throw new QuiescoError(e.errorName, `${e.message}\n${unanswered}`, e.data as never);
566
571
  }
567
572
  }
568
573
 
@@ -663,12 +668,16 @@ export class Driver {
663
668
  } catch (e) {
664
669
  // A page reload / relaunch dropped the connection mid-call: read-only calls are safe to repeat
665
670
  // once the app is back (requirements.md §6.2: reconnecting is not an error).
666
- if (e instanceof QuiescoError && e.errorName === 'AGENT_DISCONNECTED' && RETRYABLE.has(method)) return send();
671
+ if (e instanceof QuiescoError && e.errorName === 'AGENT_DISCONNECTED') {
672
+ // send() waits for the app to reconnect, and fails at once when it crashed (issue #77).
673
+ if (RETRYABLE.has(method)) return send();
674
+ if (this.options.explainDisconnect !== undefined) throw await this.options.explainDisconnect(e);
675
+ }
667
676
  throw e;
668
677
  }
669
678
  };
670
679
  const timeline = this.options.timeline;
671
- const run = timeline === undefined || !TIMELINED.has(method) ? attempt() : timeline.measure(method, describeCall(method, params), attempt, (r) => (r as { syncMs?: number }).syncMs);
680
+ const run = timeline === undefined || !TIMELINED.has(method) ? attempt() : timeline.measure(method, describeCall(method, params), attempt, (r) => r as CallTiming);
672
681
  try {
673
682
  return await run;
674
683
  } catch (e) {
@@ -727,6 +736,10 @@ export class Driver {
727
736
  this.logErrors.push(l.message);
728
737
  if (this.logErrors.length > MAX_APP_LOG_ERRORS) this.logErrors.shift();
729
738
  });
739
+ // Steps of the running call, in the timeline before the call returns (issue #84).
740
+ conn.on('step', (s) => {
741
+ if (this.watched === conn) this.options.timeline?.step(s);
742
+ });
730
743
  conn.on('appError', (e) => {
731
744
  if (this.watched !== conn) return;
732
745
  if (this.options.ignoreAppErrors?.some((re) => re.test(e.message)) === true) {
@@ -743,7 +756,8 @@ export class Driver {
743
756
  function describeCall(method: string, params: unknown): string {
744
757
  const p = (params ?? {}) as Record<string, unknown>;
745
758
  const spec = (p['action'] ?? p['assertion']) as Record<string, unknown> | undefined;
746
- const matcher = spec?.['matcher'] ?? p['matcher'];
759
+ // scrollTo: the element it looks for.
760
+ const matcher = spec?.['matcher'] ?? spec?.['target'] ?? p['matcher'];
747
761
  const what = spec !== undefined ? String(spec['type']) : method === 'backdoor' ? String(p['name']) : '';
748
762
  const m = matcher === undefined ? '' : JSON.stringify(matcher);
749
763
  return [what, m.length > 120 ? `${m.slice(0, 117)}...` : m].filter((x) => x !== '').join(' ');
package/src/errors.ts CHANGED
@@ -13,7 +13,9 @@ export type HostErrorName =
13
13
  /** The app was sent to the background by the test; bring it to the foreground first. */
14
14
  | 'APP_IN_BACKGROUND'
15
15
  /** A web page is blocked on a JS dialog (alert / confirm / prompt); answer it with app.device.system.tap first. */
16
- | 'DIALOG_OPEN';
16
+ | 'DIALOG_OPEN'
17
+ /** The app's process died (issue #76): the message carries the crash's reason when the device kept one. */
18
+ | 'APP_CRASHED';
17
19
 
18
20
  /**
19
21
  * Every failure surfaced by @quiesco/core. Agent errors keep their protocol code and structured data
package/src/index.ts CHANGED
@@ -25,6 +25,7 @@ export { AndroidProvider } from './devices/android.js';
25
25
  export { IosProvider, IOS_DEV_MENU_ARGS } from './devices/ios.js';
26
26
  export type { IosProviderOptions } from './devices/ios.js';
27
27
  export type { ColorScheme, DeviceProvider, InAppControls, LaunchParams, LaunchUrlHandling, NotificationSpec, StateChange, StatusBarOptions, SystemNode, WorkerInfo } from './devices/provider.js';
28
+ export type { CrashReport } from './devices/crash.js';
28
29
  export type { SystemQuery, SystemWaitOptions } from './system-ui.js';
29
30
  export { DeviceApi } from './device.js';
30
31
  export type { AppRunState, RelaunchOptions } from './device.js';
@@ -31,6 +31,7 @@ interface Pending {
31
31
  export class AgentConnection extends EventEmitter<{
32
32
  log: [AgentEvents['log']];
33
33
  appError: [AgentEvents['error']];
34
+ step: [AgentEvents['step']];
34
35
  close: [code: number, reason: string];
35
36
  }> {
36
37
  private nextId = 1;
@@ -120,6 +121,7 @@ export class AgentConnection extends EventEmitter<{
120
121
  }
121
122
  if (msg.method === 'log') this.emit('log', msg.params as AgentEvents['log']);
122
123
  else if (msg.method === 'error') this.emit('appError', msg.params as AgentEvents['error']);
124
+ else if (msg.method === 'step') this.emit('step', msg.params as AgentEvents['step']);
123
125
  }
124
126
 
125
127
  /** @internal */
@@ -216,23 +218,33 @@ export class QuiescoServer {
216
218
 
217
219
  /**
218
220
  * Resolves with the current connection, or the next one for this session. `exclude` skips a
219
- * connection that is about to go away (the old app process during a hard reset).
221
+ * connection that is about to go away (the old app process during a hard reset). `signal`: stop
222
+ * waiting (rejects with its reason).
220
223
  */
221
- waitForConnection(sessionId: string, timeoutMs: number, describeTimeout: () => string, exclude: AgentConnection | null = null): Promise<AgentConnection> {
224
+ waitForConnection(sessionId: string, timeoutMs: number, describeTimeout: () => string, exclude: AgentConnection | null = null, signal?: AbortSignal): Promise<AgentConnection> {
222
225
  const s = this.sessions.get(sessionId);
223
226
  if (s === undefined) return Promise.reject(new Error(`unknown session ${sessionId}`));
224
227
  const current = this.connection(sessionId);
225
228
  if (current !== null && current !== exclude) return Promise.resolve(current);
226
229
  return new Promise((resolve, reject) => {
230
+ const onAbort = (): void => {
231
+ clearTimeout(timer);
232
+ s.waiters = s.waiters.filter((w) => w !== waiter);
233
+ reject(signal?.reason);
234
+ };
227
235
  const waiter = (c: AgentConnection): void => {
228
236
  clearTimeout(timer);
237
+ signal?.removeEventListener('abort', onAbort);
229
238
  resolve(c);
230
239
  };
231
240
  const timer = setTimeout(() => {
232
241
  s.waiters = s.waiters.filter((w) => w !== waiter);
242
+ signal?.removeEventListener('abort', onAbort);
233
243
  reject(new QuiescoError('CONNECT_TIMEOUT', describeTimeout(), { sessionId, timeoutMs, port: this._port }));
234
244
  }, timeoutMs);
235
245
  s.waiters.push(waiter);
246
+ if (signal?.aborted === true) onAbort();
247
+ else signal?.addEventListener('abort', onAbort, { once: true });
236
248
  });
237
249
  }
238
250
 
package/src/session.ts CHANGED
@@ -4,6 +4,8 @@
4
4
  * → dispose (AfterAll). Nothing here knows about Cucumber.
5
5
  */
6
6
  import { randomUUID } from 'node:crypto';
7
+ import fs from 'node:fs';
8
+ import path from 'node:path';
7
9
 
8
10
  import type { AgentConfig, AgentMethods, Platform, ResultOf, TrackerState, TreeNode } from '@quiesco/protocol';
9
11
 
@@ -35,7 +37,16 @@ import { tagNames } from './tags.js';
35
37
  export const FIRST_LAUNCH_CONNECT_FACTOR = 3;
36
38
 
37
39
  /** Errors of the per-scenario reset after which the app is started again instead of failing the scenario. */
38
- const RESTART_ON: ReadonlySet<string> = new Set(['CONNECT_TIMEOUT', 'AGENT_DISCONNECTED', 'AGENT_TIMEOUT']);
40
+ /** Issue #74. */
41
+ export const NATIVE_MODULES_NOT_WRAPPED =
42
+ "sync.trackers: { 'native-module': true }, but the app's build does not wrap native modules, so the tracker counts nothing. Build it with withQuiesco(config, { nativeModules: true }) in metro.config.js (or EXPO_PUBLIC_QUIESCO_NATIVE_MODULES=1) and restart Metro.";
43
+
44
+ const RESTART_ON: ReadonlySet<string> = new Set(['CONNECT_TIMEOUT', 'AGENT_DISCONNECTED', 'AGENT_TIMEOUT', 'APP_CRASHED']);
45
+
46
+ /** While waiting for the app to reconnect, how often its process is checked (issue #77). */
47
+ const CRASH_POLL_MS = 500;
48
+ /** After a call lost its connection, how long to watch for a crash (the process takes a moment to die). */
49
+ const CRASH_CHECK_MS = 5_000;
39
50
 
40
51
  /**
41
52
  * How long a launch waits for the app. The session's first launch comes right after installing the app
@@ -59,6 +70,8 @@ export interface SessionOptions {
59
70
  * (`server.port + index`) and artifacts directory. Default: the only worker.
60
71
  */
61
72
  worker?: WorkerInfo;
73
+ /** How often the app's process is checked while waiting for it to reconnect (issue #77; tests). Default 500 ms. */
74
+ crashPollMs?: number;
62
75
  }
63
76
 
64
77
  export interface Evidence {
@@ -69,6 +82,8 @@ export interface Evidence {
69
82
  idle?: TrackerState[];
70
83
  /** Why a piece could not be collected. */
71
84
  errors: string[];
85
+ /** The app crashed (issue #76): element tree, list and idle state are not collected. */
86
+ crash?: QuiescoError;
72
87
  }
73
88
 
74
89
  export interface ScenarioInfo {
@@ -138,6 +153,7 @@ export class Session {
138
153
  readonly launchParams: LaunchParams,
139
154
  private readonly logger: Logger,
140
155
  readonly worker: WorkerInfo = SERIAL_WORKER,
156
+ private readonly crashPollMs = CRASH_POLL_MS,
141
157
  ) {
142
158
  this.defaultArgs = config.launchArgs === undefined ? {} : checkLaunchArgs(config.launchArgs, 'config launchArgs');
143
159
  this.artifacts = new Artifacts({ ...(config.artifacts !== undefined ? { config: config.artifacts } : {}), provider, logger, worker });
@@ -145,6 +161,7 @@ export class Session {
145
161
  timeline: this.artifacts.timeline,
146
162
  provider,
147
163
  connection: () => this.currentConnection(),
164
+ explainDisconnect: (e) => this.explainDisconnect(e),
148
165
  defaultTimeoutMs: toAgentConfig(config).sync.timeoutMs,
149
166
  ...(config.actions?.mode !== undefined ? { mode: config.actions.mode } : {}),
150
167
  ignoreAppErrors: ignoredAppErrors(config),
@@ -177,7 +194,7 @@ export class Session {
177
194
  const sessionId = randomUUID();
178
195
  // JS-only builds cannot read launch parameters and say `sessionId: null`; accept them for this session.
179
196
  server.expectSession(sessionId, { acceptAnonymous: true });
180
- const session = new Session(config, provider, server, { port, sessionId }, logger, worker);
197
+ const session = new Session(config, provider, server, { port, sessionId }, logger, worker, options.crashPollMs);
181
198
  try {
182
199
  await provider.boot();
183
200
  await provider.install();
@@ -196,6 +213,14 @@ export class Session {
196
213
  * `reset.default: 'hard'`).
197
214
  */
198
215
  async beforeScenario(info: ScenarioInfo = {}): Promise<void> {
216
+ if (this.crash !== null) {
217
+ // Issue #77: the app crashed in the previous scenario; no point waiting for it to reconnect.
218
+ this.logger.warn(`the app crashed in the previous scenario; starting it again`);
219
+ await this.provider.terminate().catch(() => undefined);
220
+ this.appState = 'terminated';
221
+ await this.launch({}, { recovering: true });
222
+ this.appState = 'running';
223
+ }
199
224
  try {
200
225
  await this.resetForScenario(info);
201
226
  } catch (e) {
@@ -268,6 +293,14 @@ export class Session {
268
293
  if (ev.tree !== undefined) evidence.push({ data: JSON.stringify({ elementTree: ev.tree }, null, 2), mediaType: 'application/json', fileName: 'element-tree.json' });
269
294
  if (ev.idle !== undefined) evidence.push({ data: JSON.stringify({ idleState: ev.idle }, null, 2), mediaType: 'application/json', fileName: 'idle-state.json' });
270
295
  if (ev.errors.length > 0) evidence.push({ data: `Quiesco could not collect: ${ev.errors.join('; ')}`, mediaType: 'text/plain', fileName: 'evidence-errors.txt' });
296
+ if (ev.crash !== undefined) {
297
+ evidence.push({ data: `${ev.crash.message}\n`, mediaType: 'text/plain', fileName: 'crash.txt' });
298
+ const report = ev.crash.data['report'];
299
+ if (typeof report === 'string') {
300
+ const data = await fs.promises.readFile(report).catch(() => null);
301
+ if (data !== null) evidence.push({ data, mediaType: 'text/plain', fileName: path.basename(report) });
302
+ }
303
+ }
271
304
  // Issue #31: what the app logged with console.error in this scenario, oldest first.
272
305
  const logged = this.driver.appLogErrors;
273
306
  if (logged.length > 0) evidence.push({ data: `${logged.join('\n\n')}\n`, mediaType: 'text/plain', fileName: 'app-errors.txt' });
@@ -275,9 +308,22 @@ export class Session {
275
308
  return this.artifacts.endScenario({ failed: result.failed, evidence });
276
309
  }
277
310
 
278
- /** Best effort: each piece is collected independently, failures are listed in `errors`. */
311
+ /**
312
+ * Best effort: each piece is collected independently, failures are listed in `errors`. After a crash
313
+ * only what does not need the app (issue #77), and the crash.
314
+ */
279
315
  async collectEvidence(): Promise<Evidence> {
280
316
  const ev: Evidence = { errors: [] };
317
+ // A lost connection: find out now whether the app crashed, rather than per piece.
318
+ if (this.crash === null && this.connection?.closed === true) await this.currentConnection().catch(() => undefined);
319
+ if (this.crash !== null) {
320
+ ev.crash = this.crash;
321
+ await this.provider.screenshot().then(
322
+ (b) => void (ev.screenshot = b),
323
+ (e: unknown) => ev.errors.push(`screenshot: ${(e as Error).message}`),
324
+ );
325
+ return ev;
326
+ }
281
327
  await Promise.all([
282
328
  this.provider.screenshot().then(
283
329
  async (b) => (ev.screenshot = await this.framed(b)),
@@ -342,6 +388,15 @@ export class Session {
342
388
  /** The unknown-bundle warning (issue #19) is given once per session, not on every reconnect. */
343
389
  private unknownBundleWarned = false;
344
390
 
391
+ private nativeModulesWarned = false;
392
+
393
+ /** Issue #74: the config turns the native-module tracker on, but the app's build does not wrap native modules. Once per session. */
394
+ private checkNativeModules(conn: AgentConnection): void {
395
+ if (this.nativeModulesWarned || conn.info.nativeModulesWrapped !== false || this.config.sync?.trackers?.['native-module'] !== true) return;
396
+ this.nativeModulesWarned = true;
397
+ this.logger.warn(NATIVE_MODULES_NOT_WRAPPED);
398
+ }
399
+
345
400
  /** Issue #3: say when the app's JS bundle cannot have the project's latest changes. Once per bundle. */
346
401
  private checkBundle(conn: AgentConnection): void {
347
402
  const bundle = conn.info.bundle;
@@ -370,20 +425,73 @@ export class Session {
370
425
  const c = this.connection;
371
426
  if (c !== null && !c.closed) return c;
372
427
  const timeoutMs = this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
373
- const conn = await this.server.waitForConnection(
374
- this.launchParams.sessionId,
375
- timeoutMs,
376
- () => `The app disconnected and did not reconnect within ${timeoutMs}ms (did it crash or get closed?)`,
377
- c,
378
- );
428
+ const conn = await this.waitForApp(timeoutMs, () => `The app disconnected and did not reconnect within ${timeoutMs}ms (did it crash or get closed?)`, c);
379
429
  this.adopt(conn);
380
430
  return conn;
381
431
  }
382
432
 
433
+ /** When the app was last started: crash reports from before then are not about it (issue #76). */
434
+ private launchedAt = Date.now();
435
+ /** The app's process died since it was started (issue #76 / #77); cleared by the next launch. */
436
+ private crash: QuiescoError | null = null;
437
+
438
+ /**
439
+ * Wait for the app to (re)connect; fail with APP_CRASHED as soon as its process is gone (issue #77),
440
+ * instead of waiting out the connect timeout.
441
+ */
442
+ private async waitForApp(timeoutMs: number, describeTimeout: () => string, exclude: AgentConnection | null, method?: string): Promise<AgentConnection> {
443
+ if (this.crash !== null) throw this.crash;
444
+ const isRunning = this.provider.isAppRunning?.bind(this.provider);
445
+ if (isRunning === undefined) return this.server.waitForConnection(this.launchParams.sessionId, timeoutMs, describeTimeout, exclude);
446
+ const stop = new AbortController();
447
+ const watch = async (): Promise<never> => {
448
+ for (;;) {
449
+ await new Promise((r) => setTimeout(r, this.crashPollMs));
450
+ if (stop.signal.aborted) throw stop.signal.reason;
451
+ // Unknown (the device did not answer): keep waiting for the reconnect.
452
+ if (!(await isRunning().catch(() => true)) && !stop.signal.aborted) throw await this.crashed(method);
453
+ }
454
+ };
455
+ const watching = watch();
456
+ try {
457
+ return await Promise.race([this.server.waitForConnection(this.launchParams.sessionId, timeoutMs, describeTimeout, exclude, stop.signal), watching]);
458
+ } finally {
459
+ stop.abort(new Error('stopped'));
460
+ watching.catch(() => undefined);
461
+ }
462
+ }
463
+
464
+ /** The app's process is gone: an APP_CRASHED error with the crash report's summary (issue #76), kept until the next launch. */
465
+ private async crashed(method?: string): Promise<QuiescoError> {
466
+ if (this.crash !== null) return this.crash;
467
+ const report = (await this.provider.crashReport?.(this.launchedAt).catch(() => null)) ?? null;
468
+ const during = method !== undefined ? ` while handling ${method}` : '';
469
+ const message =
470
+ report === null
471
+ ? `The app crashed${during}: its process is gone (the device kept no crash report)`
472
+ : `The app crashed${during}:\n${report.summary.replace(/^/gm, ' ')}${report.file !== undefined ? `\nCrash report: ${report.file}` : ''}`;
473
+ this.crash = new QuiescoError('APP_CRASHED', message, { ...(method !== undefined ? { method } : {}), ...(report !== null ? { summary: report.summary } : {}), ...(report?.file !== undefined ? { report: report.file } : {}) });
474
+ return this.crash;
475
+ }
476
+
477
+ /** A call lost its connection (issue #76): APP_CRASHED when the app's process dies, else the error as it was. */
478
+ private async explainDisconnect(e: QuiescoError): Promise<QuiescoError> {
479
+ if (this.provider.isAppRunning === undefined) return e;
480
+ const method = typeof e.data['method'] === 'string' ? e.data['method'] : undefined;
481
+ try {
482
+ const conn = await this.waitForApp(Math.min(CRASH_CHECK_MS, this.config.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS), () => '', this.connection, method);
483
+ this.adopt(conn);
484
+ return e;
485
+ } catch (err) {
486
+ return err instanceof QuiescoError && err.errorName === 'APP_CRASHED' ? err : e;
487
+ }
488
+ }
489
+
383
490
  private adopt(conn: AgentConnection): void {
384
491
  if (this.connection === conn) return;
385
492
  this.connection = conn;
386
493
  this.checkBundle(conn);
494
+ this.checkNativeModules(conn);
387
495
  conn.on('log', (l) => this.logger[l.level](`[app] ${l.message}`));
388
496
  this.driver.attach(conn);
389
497
  }
@@ -461,6 +569,8 @@ export class Session {
461
569
  private async launch(extra: { args?: LaunchArgs; url?: string } = {}, how: { recovering?: boolean } = {}): Promise<LaunchUrlHandling | void> {
462
570
  const previous = this.connection;
463
571
  const params = this.paramsFor(extra);
572
+ this.launchedAt = Date.now();
573
+ this.crash = null;
464
574
  const urlHandling = await this.provider.launch(params);
465
575
  // A start after the app was lost is as slow as the first (Android is still busy compiling it).
466
576
  const timeoutMs = launchConnectTimeout(this.config, { first: previous === null || how.recovering === true });
package/src/timeline.ts CHANGED
@@ -2,7 +2,9 @@
2
2
  * Timeline of a scenario (Phase 6.9): every call the test made on the app, how long it took and how much
3
3
  * of it was spent waiting for the app to be idle (as the agent reports it), with the error of a failed
4
4
  * call. Written as a Chrome trace (chrome://tracing, Perfetto) and a self-contained HTML summary.
5
+ * Multi-step actions (scrollTo) carry their steps, nested in the call (issue #78).
5
6
  */
7
+ import type { StepTiming } from '@quiesco/protocol';
6
8
 
7
9
  export interface TimelineEntry {
8
10
  /** The agent method (`action`, `assert`, ...) or a device call (`device.relaunch`). */
@@ -14,17 +16,34 @@ export interface TimelineEntry {
14
16
  end: number;
15
17
  /** Of which waiting for idle in the agent. */
16
18
  syncMs?: number;
19
+ /** The steps of a multi-step action, `atMs` from `start` (issue #78). */
20
+ steps?: StepTiming[];
17
21
  error?: string;
18
22
  }
19
23
 
24
+ /** What a call's result (or error data) says about its timing. */
25
+ export interface CallTiming {
26
+ syncMs?: number;
27
+ steps?: StepTiming[];
28
+ }
29
+
30
+ /** What a call still running when the timeline is written says (issue #84). */
31
+ export const STILL_RUNNING = 'still running when the scenario ended (the test ended it first: its timeout?)';
32
+
20
33
  export class Timeline {
21
34
  private entries: TimelineEntry[] = [];
35
+ /** Calls not returned yet, with the steps the agent reported so far (issue #84). */
36
+ private running: TimelineEntry[] = [];
37
+ /** Bumped by reset: a call of an earlier scenario that returns late does not land in this one. */
38
+ private generation = 0;
22
39
  private started = Date.now();
23
40
  private name = '';
24
41
 
25
42
  /** Start a new scenario's timeline. */
26
43
  reset(name: string): void {
27
44
  this.entries = [];
45
+ this.running = [];
46
+ this.generation++;
28
47
  this.started = Date.now();
29
48
  this.name = name;
30
49
  }
@@ -36,30 +55,54 @@ export class Timeline {
36
55
  }
37
56
 
38
57
  /** Measure `fn` as one entry. */
39
- async measure<T>(method: string, label: string, fn: () => Promise<T>, syncMs?: (r: T) => number | undefined): Promise<T> {
58
+ async measure<T>(method: string, label: string, fn: () => Promise<T>, timing?: (r: T) => CallTiming | undefined): Promise<T> {
40
59
  const start = Date.now();
60
+ const running: TimelineEntry = { method, label, start, end: start, steps: [] };
61
+ this.running.push(running);
62
+ const generation = this.generation;
63
+ const add = (entry: TimelineEntry): void => {
64
+ if (generation === this.generation) this.add(entry);
65
+ };
41
66
  try {
42
67
  const r = await fn();
43
- const s = syncMs?.(r);
44
- this.add({ method, label, start, end: Date.now(), ...(s !== undefined ? { syncMs: s } : {}) });
68
+ const t = timing?.(r);
69
+ add({ method, label, start, end: Date.now(), ...(t?.syncMs !== undefined ? { syncMs: t.syncMs } : {}), ...(t?.steps !== undefined && t.steps.length > 0 ? { steps: t.steps } : {}) });
45
70
  return r;
46
71
  } catch (e) {
47
- this.add({ method, label, start, end: Date.now(), error: e instanceof Error ? e.message : String(e) });
72
+ // A multi-step action that failed still reports its steps (issue #78).
73
+ const steps = (e as { data?: { steps?: unknown } } | null)?.data?.steps;
74
+ add({ method, label, start, end: Date.now(), ...(Array.isArray(steps) && steps.length > 0 ? { steps: steps as StepTiming[] } : {}), error: e instanceof Error ? e.message : String(e) });
48
75
  throw e;
76
+ } finally {
77
+ this.running = this.running.filter((r) => r !== running);
49
78
  }
50
79
  }
51
80
 
81
+ /** A step of the running call (calls to the agent run one at a time), reported before it returns (issue #84). */
82
+ step(s: StepTiming): void {
83
+ this.running.at(-1)?.steps?.push(s);
84
+ }
85
+
86
+ /** The calls, then those still running (ending now, with the steps so far). */
52
87
  get all(): readonly TimelineEntry[] {
53
- return this.entries;
88
+ if (this.running.length === 0) return this.entries;
89
+ const now = Date.now();
90
+ return [...this.entries, ...this.running.map(({ steps, ...r }) => ({ ...r, end: now, ...(steps !== undefined && steps.length > 0 ? { steps: [...steps] } : {}), error: STILL_RUNNING }))];
54
91
  }
55
92
 
56
93
  /** Chrome trace event format: complete events ("X"), sync waits nested inside their calls. */
57
94
  toTrace(): string {
58
95
  const us = (t: number): number => Math.round((t - this.started) * 1000);
59
96
  const events: Record<string, unknown>[] = [{ name: 'process_name', ph: 'M', pid: 1, tid: 1, args: { name: `Quiesco: ${this.name}` } }];
60
- for (const e of this.entries) {
97
+ for (const e of this.all) {
61
98
  events.push({ name: `${e.method} ${e.label}`.trim(), cat: e.method, ph: 'X', ts: us(e.start), dur: Math.max(1, us(e.end) - us(e.start)), pid: 1, tid: 1, args: e.error !== undefined ? { error: e.error } : {} });
62
- if (e.syncMs !== undefined && e.syncMs > 0) {
99
+ if (e.steps !== undefined) {
100
+ e.steps.forEach((s, i) => {
101
+ const ts = us(e.start + s.atMs);
102
+ events.push({ name: `step ${i + 1} ${s.label}`.trim(), cat: 'step', ph: 'X', ts, dur: Math.max(1, s.ms * 1000), pid: 1, tid: 1, args: { syncMs: s.syncMs } });
103
+ if (s.syncMs > 0) events.push({ name: 'wait for idle', cat: 'sync', ph: 'X', ts: ts + Math.max(0, s.ms - s.syncMs) * 1000, dur: Math.max(1, s.syncMs * 1000), pid: 1, tid: 1 });
104
+ });
105
+ } else if (e.syncMs !== undefined && e.syncMs > 0) {
63
106
  events.push({ name: 'wait for idle', cat: 'sync', ph: 'X', ts: us(e.start), dur: Math.max(1, Math.round(e.syncMs * 1000)), pid: 1, tid: 1 });
64
107
  }
65
108
  }
@@ -68,15 +111,24 @@ export class Timeline {
68
111
 
69
112
  /** One page: a bar per call (sync wait shaded), failed calls in red with their message. */
70
113
  toHtml(): string {
71
- const total = Math.max(1, ...this.entries.map((e) => e.end - this.started));
72
- const rows = this.entries
114
+ const entries = this.all;
115
+ const total = Math.max(1, ...entries.map((e) => e.end - this.started));
116
+ const rows = entries
73
117
  .map((e) => {
74
118
  const left = ((e.start - this.started) / total) * 100;
75
119
  const width = Math.max(0.3, ((e.end - e.start) / total) * 100);
76
120
  const sync = e.syncMs !== undefined ? Math.min(100, (e.syncMs / Math.max(1, e.end - e.start)) * 100) : 0;
77
121
  const cls = e.error !== undefined ? 'row failed' : 'row';
78
122
  const err = e.error !== undefined ? `<div class="err">${esc(e.error)}</div>` : '';
79
- return `<div class="${cls}"><div class="name">${esc(`${e.method} ${e.label}`)}</div><div class="ms">${e.end - e.start} ms${e.syncMs !== undefined ? ` (idle wait ${Math.round(e.syncMs)} ms)` : ''}</div><div class="track"><div class="bar" style="left:${left.toFixed(2)}%;width:${width.toFixed(2)}%"><div class="sync" style="width:${sync.toFixed(1)}%"></div></div></div>${err}</div>`;
123
+ const steps = (e.steps ?? [])
124
+ .map((s, i) => {
125
+ const sLeft = ((e.start + s.atMs - this.started) / total) * 100;
126
+ const sWidth = Math.max(0.2, (s.ms / total) * 100);
127
+ const sSync = Math.min(100, (s.syncMs / Math.max(1, s.ms)) * 100);
128
+ return `<div class="row step"><div class="name">step ${i + 1} ${esc(s.label)}</div><div class="ms">${s.ms} ms (idle wait ${s.syncMs} ms)</div><div class="track"><div class="bar" style="left:${sLeft.toFixed(2)}%;width:${sWidth.toFixed(2)}%"><div class="sync" style="width:${sSync.toFixed(1)}%"></div></div></div></div>`;
129
+ })
130
+ .join('');
131
+ return `<div class="${cls}"><div class="name">${esc(`${e.method} ${e.label}`)}</div><div class="ms">${e.end - e.start} ms${e.syncMs !== undefined ? ` (idle wait ${Math.round(e.syncMs)} ms)` : ''}</div><div class="track"><div class="bar" style="left:${left.toFixed(2)}%;width:${width.toFixed(2)}%"><div class="sync" style="width:${sync.toFixed(1)}%"></div></div></div>${err}</div>${steps}`;
80
132
  })
81
133
  .join('\n');
82
134
  return `<!doctype html><html><head><meta charset="utf-8"><title>${esc(this.name)} — Quiesco timeline</title><style>
@@ -84,8 +136,9 @@ body{font:13px system-ui,sans-serif;margin:16px;color:#222}h1{font-size:16px}
84
136
  .row{display:grid;grid-template-columns:minmax(200px,2fr) 140px 3fr;gap:8px;align-items:center;padding:2px 0;border-bottom:1px solid #eee}
85
137
  .name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-family:ui-monospace,monospace}.ms{color:#666;text-align:right}
86
138
  .track{position:relative;height:12px;background:#f4f4f4}.bar{position:absolute;top:0;height:12px;background:#6b8de3}.sync{height:12px;background:#b9c9f3}
139
+ .step .name{padding-left:16px;color:#555}.step .bar{background:#9aa9cc}
87
140
  .failed .bar{background:#d9534f}.failed .name{color:#c00}.err{grid-column:1/-1;color:#c00;white-space:pre-wrap;font-family:ui-monospace,monospace;font-size:12px;padding:4px 0 6px}
88
- </style></head><body><h1>${esc(this.name)}</h1><p>${this.entries.length} calls, ${total} ms. Light part of a bar: waiting for the app to be idle.</p>
141
+ </style></head><body><h1>${esc(this.name)}</h1><p>${entries.length} calls, ${total} ms. Light part of a bar: waiting for the app to be idle.</p>
89
142
  ${rows}
90
143
  </body></html>`;
91
144
  }