@quiesco/core 0.8.1 → 0.10.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 (63) hide show
  1. package/dist/config.d.ts +8 -1
  2. package/dist/config.d.ts.map +1 -1
  3. package/dist/config.js +2 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/device.d.ts.map +1 -1
  6. package/dist/device.js +9 -1
  7. package/dist/device.js.map +1 -1
  8. package/dist/devices/android.d.ts +4 -0
  9. package/dist/devices/android.d.ts.map +1 -1
  10. package/dist/devices/android.js +10 -0
  11. package/dist/devices/android.js.map +1 -1
  12. package/dist/devices/crash.d.ts +24 -0
  13. package/dist/devices/crash.d.ts.map +1 -0
  14. package/dist/devices/crash.js +132 -0
  15. package/dist/devices/crash.js.map +1 -0
  16. package/dist/devices/ios-runner.d.ts +14 -1
  17. package/dist/devices/ios-runner.d.ts.map +1 -1
  18. package/dist/devices/ios-runner.js +49 -8
  19. package/dist/devices/ios-runner.js.map +1 -1
  20. package/dist/devices/ios.d.ts +26 -2
  21. package/dist/devices/ios.d.ts.map +1 -1
  22. package/dist/devices/ios.js +108 -19
  23. package/dist/devices/ios.js.map +1 -1
  24. package/dist/devices/provider.d.ts +13 -0
  25. package/dist/devices/provider.d.ts.map +1 -1
  26. package/dist/devices/provider.js.map +1 -1
  27. package/dist/driver.d.ts +2 -0
  28. package/dist/driver.d.ts.map +1 -1
  29. package/dist/driver.js +10 -5
  30. package/dist/driver.js.map +1 -1
  31. package/dist/errors.d.ts +3 -1
  32. package/dist/errors.d.ts.map +1 -1
  33. package/dist/errors.js.map +1 -1
  34. package/dist/index.d.ts +1 -0
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js.map +1 -1
  37. package/dist/server/ws-server.d.ts +10 -2
  38. package/dist/server/ws-server.d.ts.map +1 -1
  39. package/dist/server/ws-server.js +44 -3
  40. package/dist/server/ws-server.js.map +1 -1
  41. package/dist/session.d.ts +29 -1
  42. package/dist/session.d.ts.map +1 -1
  43. package/dist/session.js +115 -5
  44. package/dist/session.js.map +1 -1
  45. package/dist/timeline.d.ts +10 -1
  46. package/dist/timeline.d.ts.map +1 -1
  47. package/dist/timeline.js +25 -11
  48. package/dist/timeline.js.map +1 -1
  49. package/ios-runner/Runner/SystemUIServer.swift +29 -13
  50. package/package.json +2 -2
  51. package/src/config.ts +10 -1
  52. package/src/device.ts +9 -1
  53. package/src/devices/android.ts +13 -0
  54. package/src/devices/crash.ts +146 -0
  55. package/src/devices/ios-runner.ts +49 -8
  56. package/src/devices/ios.ts +114 -18
  57. package/src/devices/provider.ts +13 -0
  58. package/src/driver.ts +11 -5
  59. package/src/errors.ts +3 -1
  60. package/src/index.ts +1 -0
  61. package/src/server/ws-server.ts +41 -3
  62. package/src/session.ts +119 -9
  63. package/src/timeline.ts +33 -6
@@ -1,4 +1,5 @@
1
1
  /** Device abstraction (requirements.md §6.9). One implementation per platform; platform branches live here. */
2
+ import type { CrashReport } from './crash.js';
2
3
  import type { GestureSlop, HostInput, Orientation, Platform, Rect } from '@quiesco/protocol';
3
4
 
4
5
  import type { Permission } from './permissions.js';
@@ -115,6 +116,13 @@ export interface DeviceProvider {
115
116
  /** Perform input the agent cannot do itself (system back, opening a URL, web real input). */
116
117
  injectInput?(input: HostInput): Promise<void>;
117
118
  shutdown(): Promise<void>;
119
+ /**
120
+ * Whether the app's process is alive (issue #76/#77): after a disconnect, a dead process means a crash
121
+ * (no point waiting for the app to reconnect). Missing where the platform cannot tell (web).
122
+ */
123
+ isAppRunning?(): Promise<boolean>;
124
+ /** The app's crash at or after `sinceMs` (ms since the epoch): the reason in a few lines, and the report file (issue #76). */
125
+ crashReport?(sinceMs: number): Promise<CrashReport | null>;
118
126
  /** Extra lines for the "app did not connect" message (e.g. adb reverse state). */
119
127
  diagnose?(params: LaunchParams): Promise<string[]>;
120
128
 
@@ -178,6 +186,11 @@ export interface DeviceProvider {
178
186
  * the system brings the app to the front with it. iOS answers the system's "Open in …?" confirmation.
179
187
  */
180
188
  openUrlFromOutside?(url: string): Promise<void>;
189
+ /**
190
+ * Start what reading the system UI needs (iOS: the XCUITest runner, 7–15 s cold). The system UI waits
191
+ * start their clock after it (issue #64).
192
+ */
193
+ prepareSystemUi?(): Promise<void>;
181
194
  /** System UI on screen now that does not belong to the app (dialogs, prompts), topmost window first. */
182
195
  systemNodes?(): Promise<SystemNode[]>;
183
196
  tapSystemNode?(node: SystemNode): Promise<void>;
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). */
@@ -85,7 +87,7 @@ const DIALOG: unique symbol = Symbol('dialog');
85
87
  const HOST_MARGIN_MS = 5_000;
86
88
  /** How many of a scenario's `console.error`s the driver keeps. */
87
89
  const MAX_APP_LOG_ERRORS = 50;
88
- /** Upper bound of steps of scrollToEdge / scrollToIndex in the agent (each may take the call timeout). */
90
+ /** Upper bound of steps of scrollToEdge / scrollToIndex / scrollTo in the agent (each may take the call timeout). */
89
91
  const MAX_SCROLL_STEPS = 60;
90
92
 
91
93
  export class Driver {
@@ -523,7 +525,7 @@ export class Driver {
523
525
  this.checkAppRunning(spec.type);
524
526
  const params: ParamsOf<AgentMethods['action']> = { action: spec, mode: opts.mode ?? (await this.mode()), ...syncParams(opts) };
525
527
  // Multi-step scrolls give every step the full timeout in the agent (bounded number of steps).
526
- const steps = spec.type === 'scrollToEdge' || spec.type === 'scrollToIndex' ? MAX_SCROLL_STEPS : 1;
528
+ const steps = spec.type === 'scrollToEdge' || spec.type === 'scrollToIndex' || spec.type === 'scrollTo' ? MAX_SCROLL_STEPS : 1;
527
529
  // A JS dialog the action opens (web alert / confirm / prompt) blocks the page — its scripts, the agent
528
530
  // and Playwright's input — until the test answers it: the action is done once the dialog is up.
529
531
  const dialog = this.watchDialog();
@@ -663,12 +665,16 @@ export class Driver {
663
665
  } catch (e) {
664
666
  // A page reload / relaunch dropped the connection mid-call: read-only calls are safe to repeat
665
667
  // 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();
668
+ if (e instanceof QuiescoError && e.errorName === 'AGENT_DISCONNECTED') {
669
+ // send() waits for the app to reconnect, and fails at once when it crashed (issue #77).
670
+ if (RETRYABLE.has(method)) return send();
671
+ if (this.options.explainDisconnect !== undefined) throw await this.options.explainDisconnect(e);
672
+ }
667
673
  throw e;
668
674
  }
669
675
  };
670
676
  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);
677
+ const run = timeline === undefined || !TIMELINED.has(method) ? attempt() : timeline.measure(method, describeCall(method, params), attempt, (r) => r as CallTiming);
672
678
  try {
673
679
  return await run;
674
680
  } catch (e) {
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';
@@ -9,7 +9,7 @@
9
9
  import { EventEmitter } from 'node:events';
10
10
  import type { AddressInfo } from 'node:net';
11
11
 
12
- import { CloseCode, ErrorCode, JsonRpcErrorCode, PROTOCOL_VERSION } from '@quiesco/protocol';
12
+ import { CloseCode, ErrorCode, HOST_TICK, HOST_TICK_MS, JsonRpcErrorCode, PROTOCOL_VERSION } from '@quiesco/protocol';
13
13
  import type { AgentConfig, AgentEvents, AgentMethods, HostMethods, ParamsOf, Platform, ResultOf } from '@quiesco/protocol';
14
14
  import { WebSocketServer } from 'ws';
15
15
  import type { WebSocket } from 'ws';
@@ -36,6 +36,7 @@ export class AgentConnection extends EventEmitter<{
36
36
  private nextId = 1;
37
37
  private readonly pending = new Map<number, Pending>();
38
38
  private _closed = false;
39
+ private ticker: ReturnType<typeof setInterval> | null = null;
39
40
 
40
41
  constructor(
41
42
  private readonly socket: WebSocket,
@@ -72,9 +73,35 @@ export class AgentConnection extends EventEmitter<{
72
73
  }, timeoutMs);
73
74
  this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer, method });
74
75
  this.socket.send(JSON.stringify({ jsonrpc: '2.0', id, method, params }));
76
+ this.startTicks();
75
77
  });
76
78
  }
77
79
 
80
+ /**
81
+ * While a call is pending, a `tick` notification every HOST_TICK_MS: the agent checks its wait for idle
82
+ * again on each one, also when the app's JS timers are paused in the background (issue #66).
83
+ */
84
+ private startTicks(): void {
85
+ if (this.ticker !== null) return;
86
+ this.ticker = setInterval(() => {
87
+ if (this.pending.size === 0 || this._closed) {
88
+ this.stopTicks();
89
+ return;
90
+ }
91
+ try {
92
+ this.socket.send(JSON.stringify({ jsonrpc: '2.0', method: HOST_TICK }));
93
+ } catch {
94
+ // The socket is closing: onClosed rejects the pending calls.
95
+ }
96
+ }, HOST_TICK_MS);
97
+ this.ticker.unref?.();
98
+ }
99
+
100
+ private stopTicks(): void {
101
+ if (this.ticker !== null) clearInterval(this.ticker);
102
+ this.ticker = null;
103
+ }
104
+
78
105
  close(code: number = CloseCode.NORMAL, reason = ''): void {
79
106
  this.socket.close(code, reason);
80
107
  this.onClosed(code, reason);
@@ -99,6 +126,7 @@ export class AgentConnection extends EventEmitter<{
99
126
  onClosed(code: number, reason: string): void {
100
127
  if (this._closed) return;
101
128
  this._closed = true;
129
+ this.stopTicks();
102
130
  for (const [, p] of this.pending) {
103
131
  clearTimeout(p.timer);
104
132
  p.reject(new QuiescoError('AGENT_DISCONNECTED', `The app disconnected while handling ${p.method} (close code ${code})`, { method: p.method, code }));
@@ -188,23 +216,33 @@ export class QuiescoServer {
188
216
 
189
217
  /**
190
218
  * Resolves with the current connection, or the next one for this session. `exclude` skips a
191
- * connection that is about to go away (the old app process during a hard reset).
219
+ * connection that is about to go away (the old app process during a hard reset). `signal`: stop
220
+ * waiting (rejects with its reason).
192
221
  */
193
- waitForConnection(sessionId: string, timeoutMs: number, describeTimeout: () => string, exclude: AgentConnection | null = null): Promise<AgentConnection> {
222
+ waitForConnection(sessionId: string, timeoutMs: number, describeTimeout: () => string, exclude: AgentConnection | null = null, signal?: AbortSignal): Promise<AgentConnection> {
194
223
  const s = this.sessions.get(sessionId);
195
224
  if (s === undefined) return Promise.reject(new Error(`unknown session ${sessionId}`));
196
225
  const current = this.connection(sessionId);
197
226
  if (current !== null && current !== exclude) return Promise.resolve(current);
198
227
  return new Promise((resolve, reject) => {
228
+ const onAbort = (): void => {
229
+ clearTimeout(timer);
230
+ s.waiters = s.waiters.filter((w) => w !== waiter);
231
+ reject(signal?.reason);
232
+ };
199
233
  const waiter = (c: AgentConnection): void => {
200
234
  clearTimeout(timer);
235
+ signal?.removeEventListener('abort', onAbort);
201
236
  resolve(c);
202
237
  };
203
238
  const timer = setTimeout(() => {
204
239
  s.waiters = s.waiters.filter((w) => w !== waiter);
240
+ signal?.removeEventListener('abort', onAbort);
205
241
  reject(new QuiescoError('CONNECT_TIMEOUT', describeTimeout(), { sessionId, timeoutMs, port: this._port }));
206
242
  }, timeoutMs);
207
243
  s.waiters.push(waiter);
244
+ if (signal?.aborted === true) onAbort();
245
+ else signal?.addEventListener('abort', onAbort, { once: true });
208
246
  });
209
247
  }
210
248
 
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,9 +16,17 @@ 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
+
20
30
  export class Timeline {
21
31
  private entries: TimelineEntry[] = [];
22
32
  private started = Date.now();
@@ -36,15 +46,17 @@ export class Timeline {
36
46
  }
37
47
 
38
48
  /** Measure `fn` as one entry. */
39
- async measure<T>(method: string, label: string, fn: () => Promise<T>, syncMs?: (r: T) => number | undefined): Promise<T> {
49
+ async measure<T>(method: string, label: string, fn: () => Promise<T>, timing?: (r: T) => CallTiming | undefined): Promise<T> {
40
50
  const start = Date.now();
41
51
  try {
42
52
  const r = await fn();
43
- const s = syncMs?.(r);
44
- this.add({ method, label, start, end: Date.now(), ...(s !== undefined ? { syncMs: s } : {}) });
53
+ const t = timing?.(r);
54
+ this.add({ method, label, start, end: Date.now(), ...(t?.syncMs !== undefined ? { syncMs: t.syncMs } : {}), ...(t?.steps !== undefined && t.steps.length > 0 ? { steps: t.steps } : {}) });
45
55
  return r;
46
56
  } catch (e) {
47
- this.add({ method, label, start, end: Date.now(), error: e instanceof Error ? e.message : String(e) });
57
+ // A multi-step action that failed still reports its steps (issue #78).
58
+ const steps = (e as { data?: { steps?: unknown } } | null)?.data?.steps;
59
+ this.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
60
  throw e;
49
61
  }
50
62
  }
@@ -59,7 +71,13 @@ export class Timeline {
59
71
  const events: Record<string, unknown>[] = [{ name: 'process_name', ph: 'M', pid: 1, tid: 1, args: { name: `Quiesco: ${this.name}` } }];
60
72
  for (const e of this.entries) {
61
73
  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) {
74
+ if (e.steps !== undefined) {
75
+ e.steps.forEach((s, i) => {
76
+ const ts = us(e.start + s.atMs);
77
+ 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 } });
78
+ 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 });
79
+ });
80
+ } else if (e.syncMs !== undefined && e.syncMs > 0) {
63
81
  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
82
  }
65
83
  }
@@ -76,7 +94,15 @@ export class Timeline {
76
94
  const sync = e.syncMs !== undefined ? Math.min(100, (e.syncMs / Math.max(1, e.end - e.start)) * 100) : 0;
77
95
  const cls = e.error !== undefined ? 'row failed' : 'row';
78
96
  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>`;
97
+ const steps = (e.steps ?? [])
98
+ .map((s, i) => {
99
+ const sLeft = ((e.start + s.atMs - this.started) / total) * 100;
100
+ const sWidth = Math.max(0.2, (s.ms / total) * 100);
101
+ const sSync = Math.min(100, (s.syncMs / Math.max(1, s.ms)) * 100);
102
+ 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>`;
103
+ })
104
+ .join('');
105
+ 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
106
  })
81
107
  .join('\n');
82
108
  return `<!doctype html><html><head><meta charset="utf-8"><title>${esc(this.name)} — Quiesco timeline</title><style>
@@ -84,6 +110,7 @@ body{font:13px system-ui,sans-serif;margin:16px;color:#222}h1{font-size:16px}
84
110
  .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
111
  .name{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font-family:ui-monospace,monospace}.ms{color:#666;text-align:right}
86
112
  .track{position:relative;height:12px;background:#f4f4f4}.bar{position:absolute;top:0;height:12px;background:#6b8de3}.sync{height:12px;background:#b9c9f3}
113
+ .step .name{padding-left:16px;color:#555}.step .bar{background:#9aa9cc}
87
114
  .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
115
  </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>
89
116
  ${rows}