@quiesco/core 0.9.0 → 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 (49) hide show
  1. package/dist/device.js +0 -1
  2. package/dist/devices/android.d.ts +4 -0
  3. package/dist/devices/android.d.ts.map +1 -1
  4. package/dist/devices/android.js +10 -0
  5. package/dist/devices/android.js.map +1 -1
  6. package/dist/devices/crash.d.ts +24 -0
  7. package/dist/devices/crash.d.ts.map +1 -0
  8. package/dist/devices/crash.js +132 -0
  9. package/dist/devices/crash.js.map +1 -0
  10. package/dist/devices/ios.d.ts +11 -0
  11. package/dist/devices/ios.d.ts.map +1 -1
  12. package/dist/devices/ios.js +19 -0
  13. package/dist/devices/ios.js.map +1 -1
  14. package/dist/devices/provider.d.ts +8 -0
  15. package/dist/devices/provider.d.ts.map +1 -1
  16. package/dist/devices/provider.js.map +1 -1
  17. package/dist/driver.d.ts +2 -0
  18. package/dist/driver.d.ts.map +1 -1
  19. package/dist/driver.js +8 -3
  20. package/dist/driver.js.map +1 -1
  21. package/dist/errors.d.ts +3 -1
  22. package/dist/errors.d.ts.map +1 -1
  23. package/dist/errors.js.map +1 -1
  24. package/dist/index.d.ts +1 -0
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js.map +1 -1
  27. package/dist/server/ws-server.d.ts +3 -2
  28. package/dist/server/ws-server.d.ts.map +1 -1
  29. package/dist/server/ws-server.js +14 -2
  30. package/dist/server/ws-server.js.map +1 -1
  31. package/dist/session.d.ts +29 -1
  32. package/dist/session.d.ts.map +1 -1
  33. package/dist/session.js +117 -7
  34. package/dist/session.js.map +1 -1
  35. package/dist/timeline.d.ts +10 -1
  36. package/dist/timeline.d.ts.map +1 -1
  37. package/dist/timeline.js +25 -11
  38. package/dist/timeline.js.map +1 -1
  39. package/package.json +2 -2
  40. package/src/devices/android.ts +13 -0
  41. package/src/devices/crash.ts +146 -0
  42. package/src/devices/ios.ts +25 -0
  43. package/src/devices/provider.ts +8 -0
  44. package/src/driver.ts +9 -3
  45. package/src/errors.ts +3 -1
  46. package/src/index.ts +1 -0
  47. package/src/server/ws-server.ts +12 -2
  48. package/src/session.ts +119 -9
  49. package/src/timeline.ts +33 -6
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}