@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/device.ts CHANGED
@@ -68,6 +68,9 @@ export interface DeviceHost {
68
68
  /** How long sendToBackground / bringToForeground wait for the app to report its new AppState. */
69
69
  const STATE_WAIT_MS = 5_000;
70
70
  const STATE_POLL_MS = 100;
71
+ /** system.tapAt waits at most this long for the system UI to stop moving (issue #87). */
72
+ const SYSTEM_SETTLE_MAX_MS = 2_000;
73
+ const sameBounds = (a: SystemNode, b: SystemNode): boolean => a.bounds.x1 === b.bounds.x1 && a.bounds.y1 === b.bounds.y1 && a.bounds.x2 === b.bounds.x2 && a.bounds.y2 === b.bounds.y2;
71
74
 
72
75
  /** How long a device-state change may take to reach the app (it is read back from the app). */
73
76
  const SETTLE_MS = 8_000;
@@ -162,6 +165,7 @@ export class DeviceApi {
162
165
  if (typeof point !== 'object' || point === null || !Number.isFinite(point.x) || !Number.isFinite(point.y)) throw new TypeError('system.tapAt({ x, y }) needs numbers');
163
166
  const p = this.host.provider;
164
167
  if (p.tapSystemPoint === undefined) throw notSupported('system.tapAt', p.platform, SYSTEM_UI_HINT[p.platform]);
168
+ await this.systemUiSettled(point);
165
169
  await p.tapSystemPoint(point.x, point.y);
166
170
  if (this.host.appState === 'running') await this.host.waitForIdle();
167
171
  },
@@ -641,6 +645,30 @@ export class DeviceApi {
641
645
  return { systemNodes: () => p.systemNodes!(), tapSystemNode: (n) => p.tapSystemNode!(n) };
642
646
  }
643
647
 
648
+ /**
649
+ * Before a touch at a point (system.tapAt): on a platform whose system UI animates in (issue #87), until
650
+ * two reads systemUiSettleMs apart show the same system UI, for at most SYSTEM_SETTLE_MAX_MS.
651
+ */
652
+ private async systemUiSettled(point: { x: number; y: number }): Promise<void> {
653
+ const p = this.host.provider;
654
+ const settleMs = p.systemUiSettleMs;
655
+ if (settleMs === undefined || p.systemNodes === undefined) return;
656
+ // The system UI over the point (iOS: SpringBoard's), not an app's element tree.
657
+ const here: SystemNode = { text: '', id: '', bounds: { x1: point.x, y1: point.y, x2: point.x, y2: point.y } };
658
+ const read = p.systemNodeReread === undefined ? () => p.systemNodes!() : p.systemNodeReread(here);
659
+ if (read === null) return;
660
+ await p.prepareSystemUi?.();
661
+ const shape = async () => JSON.stringify((await read()).map((n) => [n.text, n.id, n.bounds]));
662
+ const until = Date.now() + SYSTEM_SETTLE_MAX_MS;
663
+ let before = await shape();
664
+ while (Date.now() < until) {
665
+ await new Promise((r) => setTimeout(r, settleMs));
666
+ const now = await shape();
667
+ if (now === before) return;
668
+ before = now;
669
+ }
670
+ }
671
+
644
672
  /** Poll the system UI until a node matches (each listing may take a while: uiautomator dumps take ~2 s). */
645
673
  private async findSystemNode(action: string, what: string, pick: (nodes: SystemNode[]) => SystemNode | undefined, opts: SystemWaitOptions): Promise<SystemNode> {
646
674
  const p = this.systemProvider(action);
@@ -648,10 +676,24 @@ export class DeviceApi {
648
676
  // Not counted: starting the system UI runner (issue #64).
649
677
  await this.host.provider.prepareSystemUi?.();
650
678
  const deadline = Date.now() + timeoutMs;
679
+ const settleMs = this.host.provider.systemUiSettleMs;
651
680
  for (;;) {
652
- const nodes = await p.systemNodes();
681
+ let nodes = await p.systemNodes();
653
682
  const node = pick(nodes);
654
- if (node !== undefined) return node;
683
+ if (node !== undefined && settleMs === undefined) return node;
684
+ if (node !== undefined) {
685
+ // Still animating in, a touch is lost (issue #87): only once two reads agree on where it is. One
686
+ // that keeps moving until the deadline is acted on all the same.
687
+ const provider = this.host.provider;
688
+ const reread = provider.systemNodeReread === undefined ? () => p.systemNodes() : provider.systemNodeReread(node);
689
+ if (reread === null) return node;
690
+ await new Promise((r) => setTimeout(r, settleMs));
691
+ nodes = await reread();
692
+ const again = pick(nodes);
693
+ if (again !== undefined && (sameBounds(again, node) || Date.now() >= deadline)) return again;
694
+ this.host.logger.debug(`${action}: ${what} is still moving (${JSON.stringify(node.bounds)} → ${JSON.stringify(again?.bounds ?? null)}); looking again`);
695
+ continue;
696
+ }
655
697
  if (Date.now() >= deadline) {
656
698
  const seen = seenTexts(nodes);
657
699
  throw new QuiescoError('ELEMENT_NOT_FOUND', `${action}: no system UI matching ${what} within ${timeoutMs}ms (on screen outside the app: ${seen.map((t) => JSON.stringify(t)).join(', ') || 'nothing'})`, {
@@ -42,6 +42,8 @@ export const DEV_MENU_PREFS =
42
42
  ' <boolean name="motionGestureEnabled" value="false" />\n' +
43
43
  '</map>\n';
44
44
 
45
+ import { androidCrash } from './crash.js';
46
+ import type { CrashReport } from './crash.js';
45
47
  import fs from 'node:fs/promises';
46
48
  import os from 'node:os';
47
49
  import path from 'node:path';
@@ -229,6 +231,17 @@ export class AndroidProvider implements DeviceProvider {
229
231
  return this.adbRun(['shell', command]);
230
232
  }
231
233
 
234
+ async isAppRunning(): Promise<boolean> {
235
+ return (await this.shell(`pidof ${shq(this.pkg)}`).catch(() => '')).trim() !== '';
236
+ }
237
+
238
+ /** The crash in logcat's crash buffer (times as epoch seconds, so the host's clock can pick the recent one). */
239
+ async crashReport(sinceMs: number): Promise<CrashReport | null> {
240
+ const log = await this.adbRun(['logcat', '-d', '-b', 'crash', '-v', 'threadtime', '-v', 'epoch']).catch(() => '');
241
+ const summary = androidCrash(log, this.pkg, sinceMs);
242
+ return summary === null ? null : { summary };
243
+ }
244
+
232
245
  /** Online devices from `adb devices`. */
233
246
  private async devices(): Promise<string[]> {
234
247
  const { stdout } = await this.exec(this.adb, ['devices']);
@@ -0,0 +1,146 @@
1
+ /**
2
+ * What a crashed app left behind (issue #76): the crash in Android's logcat crash buffer, or an iOS
3
+ * crash report (`.ips` in ~/Library/Logs/DiagnosticReports), cut down to the lines that say why.
4
+ */
5
+ import fs from 'node:fs/promises';
6
+ import path from 'node:path';
7
+
8
+ /** A crash of the app under test. */
9
+ export interface CrashReport {
10
+ /** A few lines: the exception and the top of the crashing thread's stack. */
11
+ summary: string;
12
+ /** The full report on this machine (iOS), to copy into the evidence. */
13
+ file?: string;
14
+ }
15
+
16
+ /** Stack frames in a summary. */
17
+ const FRAMES = 8;
18
+ /** Longer symbols (C++ templates) are cut. */
19
+ const SYMBOL_CHARS = 140;
20
+
21
+ const LOGCAT_LINE = /^\s*(\d+(?:\.\d+)?)\s+(\d+)\s+(\d+)\s+[VDIWEF]\s+([^:]*?)\s*:\s?(.*)$/;
22
+
23
+ interface LogcatLine {
24
+ t: number;
25
+ pid: string;
26
+ tag: string;
27
+ message: string;
28
+ }
29
+
30
+ function parseLogcat(text: string): LogcatLine[] {
31
+ const out: LogcatLine[] = [];
32
+ for (const line of text.split('\n')) {
33
+ const m = LOGCAT_LINE.exec(line);
34
+ if (m !== null) out.push({ t: Number(m[1]), pid: m[2] as string, tag: m[4] as string, message: (m[5] as string).replace(/\r$/, '') });
35
+ }
36
+ return out;
37
+ }
38
+
39
+ /**
40
+ * The app's last crash in `adb logcat -b crash -v threadtime -v epoch` output at or after `sinceMs`
41
+ * (ms since the epoch): a Java / Kotlin `FATAL EXCEPTION` (the exception and its first frames, with
42
+ * the `Caused by` lines), or a native `Fatal signal` with the abort message and the first backtrace
43
+ * frames. Null when the app did not crash there.
44
+ */
45
+ export function androidCrash(logcat: string, pkg: string, sinceMs: number): string | null {
46
+ const lines = parseLogcat(logcat).filter((l) => l.t * 1000 >= sinceMs - 1000);
47
+ // Java: "FATAL EXCEPTION: main", then "Process: <pkg>, PID: <pid>".
48
+ let java: string[] | null = null;
49
+ for (let i = 0; i < lines.length; i++) {
50
+ const l = lines[i] as LogcatLine;
51
+ if (l.tag !== 'AndroidRuntime' || !l.message.startsWith('FATAL EXCEPTION')) continue;
52
+ const next = lines[i + 1];
53
+ if (next === undefined || !next.message.startsWith(`Process: ${pkg},`)) continue;
54
+ const block = lines.slice(i).filter((b) => b.pid === l.pid && b.tag === 'AndroidRuntime').map((b) => b.message);
55
+ // The exception, its first frames, and each "Caused by" with its first frame.
56
+ const kept: string[] = [];
57
+ let frames = 0;
58
+ for (const m of block) {
59
+ const frame = /^\s*at /.test(m);
60
+ if (!frame) frames = 0;
61
+ else if (++frames > (kept.some((k) => k.startsWith('Caused by')) ? 2 : FRAMES)) continue;
62
+ kept.push(m.replace(/^\t/, ' '));
63
+ }
64
+ java = kept;
65
+ }
66
+ if (java !== null) return java.join('\n');
67
+ // Native: libc "Fatal signal 6 (SIGABRT), code -1 (SI_QUEUE) in tid 1 (main), pid 1 (<pkg>)", then the
68
+ // tombstone (tag DEBUG): "Abort message: …", "#00 pc …".
69
+ const signal = [...lines].reverse().find((l) => l.message.startsWith('Fatal signal') && l.message.includes(`(${pkg})`));
70
+ if (signal === undefined) return null;
71
+ const after = lines.slice(lines.indexOf(signal) + 1);
72
+ const abort = after.find((l) => l.message.startsWith('Abort message:'));
73
+ const frames = after.filter((l) => /^\s*#\d+ pc /.test(l.message)).slice(0, FRAMES);
74
+ return [signal.message, ...(abort !== undefined ? [abort.message] : []), ...frames.map((f) => ` ${f.message.trim()}`)].join('\n');
75
+ }
76
+
77
+ interface IpsBody {
78
+ exception?: { type?: string; signal?: string; subtype?: string };
79
+ termination?: { indicator?: string };
80
+ asi?: Record<string, unknown>;
81
+ faultingThread?: number;
82
+ threads?: { frames?: { imageIndex?: number; symbol?: string; imageOffset?: number }[] }[];
83
+ usedImages?: { name?: string }[];
84
+ }
85
+
86
+ /** The header (first line) of an `.ips` report, or null when it is not one. */
87
+ export function ipsHeader(text: string): { bundleID?: string; app_name?: string } | null {
88
+ const end = text.indexOf('\n');
89
+ try {
90
+ return JSON.parse(end < 0 ? text : text.slice(0, end)) as { bundleID?: string; app_name?: string };
91
+ } catch {
92
+ return null;
93
+ }
94
+ }
95
+
96
+ /** An iOS crash report (`.ips`, JSON) as a few lines: exception, termination reason, crashing thread's top frames. */
97
+ export function summarizeIps(text: string): string | null {
98
+ const end = text.indexOf('\n');
99
+ if (end < 0) return null;
100
+ let body: IpsBody;
101
+ try {
102
+ body = JSON.parse(text.slice(end + 1)) as IpsBody;
103
+ } catch {
104
+ return null;
105
+ }
106
+ const lines: string[] = [];
107
+ const e = body.exception;
108
+ if (e?.type !== undefined) lines.push(`${e.type}${e.signal !== undefined ? ` (${e.signal})` : ''}${e.subtype !== undefined ? `: ${e.subtype}` : ''}${body.termination?.indicator !== undefined ? `, ${body.termination.indicator}` : ''}`);
109
+ for (const v of Object.values(body.asi ?? {})) {
110
+ for (const s of Array.isArray(v) ? v : [v]) if (typeof s === 'string' && s.trim() !== '') lines.push(s.trim());
111
+ }
112
+ const n = body.faultingThread;
113
+ const frames = n === undefined ? undefined : body.threads?.[n]?.frames;
114
+ if (frames !== undefined && frames.length > 0) {
115
+ lines.push(`Thread ${n} crashed:`);
116
+ frames.slice(0, FRAMES).forEach((f, i) => {
117
+ const image = (f.imageIndex !== undefined ? body.usedImages?.[f.imageIndex]?.name : undefined) ?? '???';
118
+ const symbol = f.symbol ?? (f.imageOffset !== undefined ? `+${f.imageOffset}` : '');
119
+ lines.push(` ${i} ${image} ${symbol.length > SYMBOL_CHARS ? `${symbol.slice(0, SYMBOL_CHARS)}…` : symbol}`);
120
+ });
121
+ }
122
+ return lines.length > 0 ? lines.join('\n') : null;
123
+ }
124
+
125
+ /** The newest `.ips` report in `dir` for `bundleId` written at or after `sinceMs`. */
126
+ export async function newestIosCrash(dir: string, bundleId: string, sinceMs: number): Promise<CrashReport | null> {
127
+ let names: string[];
128
+ try {
129
+ names = (await fs.readdir(dir)).filter((n) => n.endsWith('.ips'));
130
+ } catch {
131
+ return null;
132
+ }
133
+ const candidates: { file: string; mtime: number }[] = [];
134
+ for (const n of names) {
135
+ const file = path.join(dir, n);
136
+ const stat = await fs.stat(file).catch(() => null);
137
+ if (stat !== null && stat.mtimeMs >= sinceMs - 1000) candidates.push({ file, mtime: stat.mtimeMs });
138
+ }
139
+ candidates.sort((a, b) => b.mtime - a.mtime);
140
+ for (const c of candidates) {
141
+ const text = await fs.readFile(c.file, 'utf8').catch(() => '');
142
+ if (ipsHeader(text)?.bundleID !== bundleId) continue;
143
+ return { summary: summarizeIps(text) ?? 'The crash report could not be read.', file: c.file };
144
+ }
145
+ return null;
146
+ }
@@ -82,12 +82,25 @@ export function screenNodes(screen: RunnerScreen): SystemNode[] {
82
82
  return out;
83
83
  }
84
84
 
85
- /** The button that dismisses a leftover alert with the least effect: cancel, deny, else the first one. */
86
- export function dismissButton(alert: RunnerScreen['alerts'][number]): { frame: number[] } | undefined {
87
- const nodes = screenNodes({ alerts: [alert], others: [] });
88
- const pick = nodes.find((n) => /cancel/i.test(n.id)) ?? nodes.find((n) => n.id === PERMISSION_DENY);
89
- if (pick !== undefined) return { frame: [pick.bounds.x1, pick.bounds.y1, pick.bounds.x2 - pick.bounds.x1, pick.bounds.y2 - pick.bounds.y1] };
90
- return alert.buttons[0];
85
+ /** A system permission alert: no identifiers at all, two or three buttons (see screenNodes). */
86
+ export function isPermissionAlert(alert: RunnerScreen['alerts'][number]): boolean {
87
+ return alert.id === '' && alert.buttons.every((b) => b.id === '') && (alert.buttons.length === 2 || alert.buttons.length === 3);
88
+ }
89
+
90
+ /** `"<title>" [<button>, <button>]`, for messages. */
91
+ export function describeAlert(alert: RunnerScreen['alerts'][number]): string {
92
+ return `${JSON.stringify(alert.label)} [${alert.buttons.map((b) => b.label).join(', ')}]`;
93
+ }
94
+
95
+ /**
96
+ * The button that dismisses a leftover alert with the least effect: cancel, else the first one, with
97
+ * its label. None for a permission alert (issue #86): its "Don't Allow" leaves a denied permission
98
+ * (notifications: until the app is reinstalled), its "Allow" a grant the test did not ask for.
99
+ */
100
+ export function dismissButton(alert: RunnerScreen['alerts'][number]): { frame: number[]; label: string } | undefined {
101
+ if (isPermissionAlert(alert)) return undefined;
102
+ const cancel = alert.buttons.find((b) => /cancel/i.test(b.id));
103
+ return cancel ?? alert.buttons[0];
91
104
  }
92
105
 
93
106
  /** Where the runner sources are: <package>/ios-runner (from dist/devices or src/devices). */
@@ -19,6 +19,8 @@
19
19
  * screen), or opening the Settings app for apps without @quiesco/native; foreground = `simctl launch`
20
20
  * without terminating (the running process is activated, its arguments are ignored).
21
21
  */
22
+ import { newestIosCrash } from './crash.js';
23
+ import type { CrashReport } from './crash.js';
22
24
  import fs from 'node:fs/promises';
23
25
  import os from 'node:os';
24
26
  import path from 'node:path';
@@ -34,7 +36,7 @@ import type { Exec } from './exec.js';
34
36
  import { execCommand } from './exec.js';
35
37
  import { LogBuffer, exited, spawnProcess } from './streams.js';
36
38
  import type { ChildLike, SpawnProcess } from './streams.js';
37
- import { IosSystemRunner, PERMISSION_ALLOW, PERMISSION_DENY, backButton, dismissButton, screenNodes } from './ios-runner.js';
39
+ import { IosSystemRunner, PERMISSION_ALLOW, PERMISSION_DENY, backButton, describeAlert, dismissButton, isPermissionAlert, screenNodes } from './ios-runner.js';
38
40
  import type { RunnerScreen } from './ios-runner.js';
39
41
  import type { Permission } from './permissions.js';
40
42
  import { SERIAL_WORKER } from './provider.js';
@@ -136,6 +138,10 @@ export interface IosProviderOptions {
136
138
  worker?: WorkerInfo;
137
139
  /** How long match() / fail() wait for the app's authentication to start (tests). Default 10 s. */
138
140
  biometricWaitMs?: number;
141
+ /** Where crash reports are written (tests). Default ~/Library/Logs/DiagnosticReports. */
142
+ crashReportDir?: string;
143
+ /** How long crashReport() waits for the report to appear (tests). Default 5 s. */
144
+ crashReportWaitMs?: number;
139
145
  }
140
146
 
141
147
  /** What IosProvider uses of IosSystemRunner. */
@@ -223,7 +229,7 @@ export function uikitNodes(elements: readonly { type: number; label: string; id:
223
229
  }
224
230
 
225
231
  /**
226
- * Whether `frame` ([x, y, w, h]) looks like the "Open" button a locked device shows beside the tapped
232
+ * Whether `frame` ([x, y, w, h]) looks like the "Open" button a locked device (or iOS 27 Notification Center, #82) shows beside the tapped
227
233
  * notification `b`: in its row, on its left, less than half its width.
228
234
  */
229
235
  function revealedOpen(frame: number[], b: { x1: number; x2: number; y1: number; y2: number }): boolean {
@@ -235,9 +241,16 @@ function revealedOpen(frame: number[], b: { x1: number; x2: number; y1: number;
235
241
  /** Darwin notification state BiometricKit_Sim reads for "enrolled" (1 / 0). */
236
242
  const BIOMETRIC_ENROLLMENT = 'com.apple.BiometricKit.enrollmentChanged';
237
243
 
238
- /** openNotification: after BANNER_WAIT_MS (at most half the timeout) without a banner, it looks in Notification Center. */
239
- const BANNER_WAIT_MS = 2_000;
244
+ /**
245
+ * openNotification: after BANNER_WAIT_MS (at most half the timeout) without a banner, it looks in
246
+ * Notification Center. Long enough for a notification scheduled a few seconds ahead to show as a banner:
247
+ * opened earlier, Notification Center receives it, and on iOS 27 a tap on a notification that just
248
+ * arrived there does nothing (2 s: 1 run in 4 failed once the runner was warm, issue #82).
249
+ */
250
+ const BANNER_WAIT_MS = 5_000;
240
251
  const NOTIFICATION_POLL_MS = 250;
252
+ /** System UI slides in for ~430–615 ms: two reads this far apart must agree before a touch (issue #87). */
253
+ const SYSTEM_UI_SETTLE_MS = 250;
241
254
  /** openUrlFromOutside: how long SpringBoard's "Open in …?" confirmation may take to show up. */
242
255
  const OPEN_URL_CONFIRM_MS = 5_000;
243
256
  /**
@@ -266,6 +279,8 @@ export class IosProvider implements DeviceProvider {
266
279
  private readonly logger: Logger;
267
280
  /** XCUITest runner for SpringBoard's UI, started on first use (Phase 6.7 batch C). */
268
281
  private runnerInstance: SystemRunnerLike | null = null;
282
+ /** A runner start in progress: a warm-up (sendToBackground) and a system UI call share it. */
283
+ private runnerStarting: Promise<void> | null = null;
269
284
  /** Phase 6.9 artifacts: the running recorder and log stream. */
270
285
  private recorder: { child: ChildLike; file: string } | null = null;
271
286
  private logStream: ChildLike | null = null;
@@ -483,6 +498,9 @@ export class IosProvider implements DeviceProvider {
483
498
  }
484
499
 
485
500
  async sendToBackground(app: InAppControls): Promise<void> {
501
+ // What follows is often openNotification: a runner that starts only then (7–15 s cold) misses the
502
+ // banner (issue #82). Started in the background; a failure shows up when the runner is used.
503
+ this.startRunner().catch((e: unknown) => this.logger.debug(`warming up the iOS system UI runner failed: ${(e as Error).message}`));
486
504
  if (await app.suspend().catch(() => false)) return;
487
505
  // No @quiesco/native (or an older one): another app in front puts ours in the background too.
488
506
  this.logger.debug('sendToBackground: the app cannot suspend itself; opening the Settings app instead');
@@ -725,9 +743,18 @@ export class IosProvider implements DeviceProvider {
725
743
  */
726
744
  /** Start the system UI runner: system UI waits start their clock after it (a cold start takes 7–15 s, issue #64). */
727
745
  async prepareSystemUi(): Promise<void> {
728
- await this.runner.start?.();
746
+ await this.startRunner();
729
747
  }
730
748
 
749
+ private startRunner(): Promise<void> {
750
+ this.runnerStarting ??= (async () => this.runner.start?.())().finally(() => {
751
+ this.runnerStarting = null;
752
+ });
753
+ return this.runnerStarting;
754
+ }
755
+
756
+ readonly systemUiSettleMs = SYSTEM_UI_SETTLE_MS;
757
+
731
758
  async systemNodes(): Promise<SystemNode[]> {
732
759
  const runner = this.runner;
733
760
  const nodes = screenNodes(await runner.screen());
@@ -739,6 +766,15 @@ export class IosProvider implements DeviceProvider {
739
766
  return nodes;
740
767
  }
741
768
 
769
+ /**
770
+ * SpringBoard's UI (alerts, the Face ID prompt, banners) slides in: read it again. Not a node of an app's
771
+ * element tree: a read of that takes seconds (18 s with a web page in it), the animation is over by then.
772
+ */
773
+ systemNodeReread(node: SystemNode): (() => Promise<SystemNode[]>) | null {
774
+ if (node.app !== undefined) return null;
775
+ return async () => screenNodes(await this.runner.screen());
776
+ }
777
+
742
778
  async tapSystemNode(node: SystemNode): Promise<void> {
743
779
  await this.runner.tap((node.bounds.x1 + node.bounds.x2) / 2, (node.bounds.y1 + node.bounds.y2) / 2);
744
780
  }
@@ -857,28 +893,26 @@ export class IosProvider implements DeviceProvider {
857
893
  taps++;
858
894
  // A stack that expanded shows more matching notifications: look again right away.
859
895
  const expanded = async () => (await find(), shown.filter(matches).length > matching);
860
- if (await this.tapOpened(appState !== undefined, inFront, find, deadline, expanded)) return;
861
- // On a locked device a tap only slides the notification to the right and shows an "Open" button on
862
- // its left (in the device's language): a new, small button, not a notification, left in that row.
863
- // Not one on the right ("Clear", "Options"), nor another notification.
864
- await find();
865
- const revealed = shown.find((o) => !before.has(o.label) && !matches(o) && !o.label.includes(', ') && revealedOpen(o.frame, b));
866
- if (revealed !== undefined) {
867
- const r = screenNodes({ alerts: [], others: [revealed] })[0]!.bounds;
868
- this.logger.warn(`openNotification: tapping "${title}" showed ${JSON.stringify(revealed.label)} (a locked device); tapping it`);
869
- await runner.tap((r.x1 + r.x2) / 2, (r.y1 + r.y2) / 2);
870
- if (await this.tapOpened(appState !== undefined, inFront, find, deadline, async () => false)) return;
871
- }
896
+ // On a locked device, and in Notification Center on iOS 27 (the Cover Sheet), a tap may only slide
897
+ // the notification to the right and show an "Open" button on its left (in the device's language),
898
+ // withdrawn ~3 s later (issue #82): a new, small button, not a notification, left in that row. Not
899
+ // one on the right ("Clear", "Options"), nor another notification. Read from the last `find`.
900
+ const revealed = () => shown.find((o) => !before.has(o.label) && !matches(o) && !o.label.includes(', ') && revealedOpen(o.frame, b));
901
+ if (await this.tapOpened(appState !== undefined, inFront, find, deadline, expanded, revealed, title)) return;
872
902
  this.logger.warn(`openNotification: the app did not come to the front after tapping "${title}"; looking again`);
873
903
  continue;
874
904
  }
875
905
  if (taps > 0 && (await inFront())) return;
876
906
  if (Date.now() > deadline) {
877
- const seen = (await runner.screen().catch(() => ({ alerts: [], others: [] }))).others.map((o) => JSON.stringify(o.label)).slice(0, 8);
907
+ const screen = await runner.screen().catch((): RunnerScreen => ({ alerts: [], others: [] }));
908
+ // A system alert is often the reason (issue #85: the permission prompt, so nothing was scheduled).
909
+ const alerts = screen.alerts.length === 0 ? '' : `; a system alert is up: ${screen.alerts.map(describeAlert).join(', ')}`;
910
+ const seen = `${screen.others.map((o) => JSON.stringify(o.label)).slice(0, 8).join(', ') || 'nothing'}${alerts}`;
878
911
  if (taps > 0) {
879
- throw new QuiescoError('DEVICE_ERROR', `openNotification: tapped "${title}" ${taps} time(s), but the app did not come to the front within ${timeoutMs}ms (seen: ${seen.join(', ') || 'nothing'})`);
912
+ throw new QuiescoError('DEVICE_ERROR', `openNotification: tapped "${title}" ${taps} time(s), but the app did not come to the front within ${timeoutMs}ms (seen: ${seen})`);
880
913
  }
881
- throw new QuiescoError('DEVICE_ERROR', `openNotification: no notification "${title}" in a banner or Notification Center within ${timeoutMs}ms (seen: ${seen.join(', ') || 'nothing'}). Can the app show notifications (system.allowPermission())?`);
914
+ const hint = screen.alerts.some(isPermissionAlert) ? 'Answer the permission alert first (system.allowPermission())' : 'Can the app show notifications (system.allowPermission())?';
915
+ throw new QuiescoError('DEVICE_ERROR', `openNotification: no notification "${title}" in a banner or Notification Center within ${timeoutMs}ms (seen: ${seen}). ${hint}`);
882
916
  }
883
917
  // The banner goes away after a few seconds (also after a tap that missed it); then the notification is in Notification Center.
884
918
  if (!centerOpened && (taps > 0 || Date.now() > start + Math.min(BANNER_WAIT_MS, timeoutMs / 2))) {
@@ -892,27 +926,62 @@ export class IosProvider implements DeviceProvider {
892
926
  /**
893
927
  * Whether a notification tap opened the app: the app is in front within NOTIFICATION_FRONT_MS
894
928
  * (`knowsState`), else (a runner that cannot tell) the notification went away within NOTIFICATION_TAP_CONFIRM_MS.
929
+ * An "Open" button the tap revealed (`revealed`, read after each look) is tapped as soon as two looks
930
+ * agree on where it is, and the wait starts again (issue #82: it is withdrawn ~3 s later).
895
931
  */
896
- private async tapOpened(knowsState: boolean, inFront: () => Promise<boolean>, find: () => Promise<unknown>, deadline: number, expanded: () => Promise<boolean>): Promise<boolean> {
932
+ private async tapOpened(
933
+ knowsState: boolean,
934
+ inFront: () => Promise<boolean>,
935
+ find: () => Promise<unknown>,
936
+ deadline: number,
937
+ expanded: () => Promise<boolean>,
938
+ revealed: () => RunnerScreen['others'][number] | undefined,
939
+ title: string,
940
+ ): Promise<boolean> {
897
941
  // Not past the call's deadline (but one look at least).
898
- const until = Math.min(Date.now() + (knowsState ? NOTIFICATION_FRONT_MS : NOTIFICATION_TAP_CONFIRM_MS), Math.max(deadline, Date.now()));
942
+ const waitUntil = () => Math.min(Date.now() + (knowsState ? NOTIFICATION_FRONT_MS : NOTIFICATION_TAP_CONFIRM_MS), Math.max(deadline, Date.now()));
943
+ let until = waitUntil();
944
+ let openAt: string | undefined;
945
+ let openTapped = false;
899
946
  for (;;) {
900
947
  if (knowsState ? await inFront() : (await find()) === undefined) return true;
901
948
  if (knowsState && (await expanded())) return false;
949
+ const open = openTapped ? undefined : revealed();
950
+ const at = open === undefined ? undefined : JSON.stringify(open.frame);
951
+ if (open !== undefined && at === openAt) {
952
+ const r = screenNodes({ alerts: [], others: [open] })[0]!.bounds;
953
+ this.logger.warn(`openNotification: tapping "${title}" showed ${JSON.stringify(open.label)} (Notification Center on iOS 27, or a locked device); tapping it`);
954
+ await this.runner.tap((r.x1 + r.x2) / 2, (r.y1 + r.y2) / 2);
955
+ openTapped = true;
956
+ until = waitUntil();
957
+ continue;
958
+ }
959
+ openAt = at;
902
960
  if (Date.now() >= until) return false;
903
961
  await new Promise((r) => setTimeout(r, NOTIFICATION_POLL_MS));
904
962
  }
905
963
  }
906
964
 
907
- /** Alerts outlive the app (a relaunch keeps a permission alert up): dismiss what an earlier scenario left. */
965
+ /**
966
+ * Alerts outlive the app (a relaunch keeps a permission alert up): dismiss what an earlier scenario left.
967
+ * Not a permission alert (issue #86): either answer sticks (a denied notification permission only goes
968
+ * away with a reinstall), so the scenario fails, saying which alert is up.
969
+ */
908
970
  private async dismissLeftoverAlerts(): Promise<void> {
909
971
  if (this.runnerInstance?.running !== true) return;
910
972
  for (let i = 0; i < 3; i++) {
911
973
  const alert = (await this.runner.screen().catch(() => null))?.alerts[0];
912
974
  if (alert === undefined) return;
975
+ if (isPermissionAlert(alert)) {
976
+ const message =
977
+ `a system permission alert left by the previous scenario is still up: ${describeAlert(alert)}. Quiesco does not answer it for you ` +
978
+ `(on iOS "Don't Allow" for notifications sticks until the app is reinstalled). Answer it in the scenario that brings it up ` +
979
+ `(app.device.system.allowPermission() / denyPermission()), or grant the permission before the app starts (config \`permissions\`)`;
980
+ throw new QuiescoError('RESET_FAILED', message, { step: 'system alert', message });
981
+ }
913
982
  const button = dismissButton(alert);
914
983
  if (button === undefined) return;
915
- this.logger.warn(`dismissing a system alert left by the previous scenario: ${JSON.stringify(alert.label)}`);
984
+ this.logger.warn(`dismissing a system alert left by the previous scenario: ${describeAlert(alert)}; tapping ${JSON.stringify(button.label)}`);
916
985
  const [x = 0, y = 0, w = 0, h = 0] = button.frame;
917
986
  await this.runner.tap(x + w / 2, y + h / 2).catch(() => undefined);
918
987
  }
@@ -930,7 +999,7 @@ export class IosProvider implements DeviceProvider {
930
999
  if (alert === undefined) break;
931
1000
  const button = dismissButton(alert);
932
1001
  if (button === undefined) break;
933
- this.logger.warn(`dismissing a system alert covering the app: ${JSON.stringify(alert.label)}`);
1002
+ this.logger.warn(`dismissing a system alert covering the app: ${describeAlert(alert)}; tapping ${JSON.stringify(button.label)}`);
934
1003
  const [x = 0, y = 0, w = 0, h = 0] = button.frame;
935
1004
  await this.runner.tap(x + w / 2, y + h / 2).catch(() => undefined);
936
1005
  closed.push(alert.label);
@@ -938,6 +1007,12 @@ export class IosProvider implements DeviceProvider {
938
1007
  return closed;
939
1008
  }
940
1009
 
1010
+ async unansweredSystemAlert(): Promise<string | undefined> {
1011
+ const alert = (await this.runner.screen().catch(() => null))?.alerts.find(isPermissionAlert);
1012
+ if (alert === undefined) return undefined;
1013
+ return `A system permission alert is up over the app: ${describeAlert(alert)}. Quiesco does not answer it for you: answer it in the scenario (app.device.system.allowPermission() / denyPermission())`;
1014
+ }
1015
+
941
1016
  async resetDeviceState(app: InAppControls): Promise<StateChange> {
942
1017
  await this.dismissLeftoverAlerts();
943
1018
  for (const [what, value] of this.changed) {
@@ -1102,6 +1177,25 @@ export class IosProvider implements DeviceProvider {
1102
1177
  if (this.bootedByUs && this.options.device?.shutdown === true) await this.simctl(['shutdown', this.sim.udid]).catch(() => undefined);
1103
1178
  }
1104
1179
 
1180
+ async isAppRunning(): Promise<boolean> {
1181
+ const services = await this.simctl(['spawn', this.udid, 'launchctl', 'list']);
1182
+ return services.split('\n').some((l) => l.includes(`UIKitApplication:${this.bundleId}[`) && /^\d+\s/.test(l));
1183
+ }
1184
+
1185
+ /**
1186
+ * The app's crash report (`.ips`), written by ReportCrash about a second after the crash: waits up to
1187
+ * `crashReportWaitMs` for it.
1188
+ */
1189
+ async crashReport(sinceMs: number): Promise<CrashReport | null> {
1190
+ const dir = this.options.crashReportDir ?? path.join(os.homedir(), 'Library', 'Logs', 'DiagnosticReports');
1191
+ const deadline = Date.now() + (this.options.crashReportWaitMs ?? 5_000);
1192
+ for (;;) {
1193
+ const report = await newestIosCrash(dir, this.bundleId, sinceMs);
1194
+ if (report !== null || Date.now() >= deadline) return report;
1195
+ await new Promise((r) => setTimeout(r, 250));
1196
+ }
1197
+ }
1198
+
1105
1199
  async diagnose(params: LaunchParams): Promise<string[]> {
1106
1200
  const lines = [`The simulator shares the Mac's network: the app connects to ws://localhost:${params.port} directly.`];
1107
1201
  const services = await this.simctl(['spawn', this.udid, 'launchctl', 'list']).catch(() => '');
@@ -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
 
@@ -185,6 +193,21 @@ export interface DeviceProvider {
185
193
  prepareSystemUi?(): Promise<void>;
186
194
  /** System UI on screen now that does not belong to the app (dialogs, prompts), topmost window first. */
187
195
  systemNodes?(): Promise<SystemNode[]>;
196
+ /**
197
+ * System UI slides or fades in here and a touch during that animation is lost (iOS, issue #87): system
198
+ * taps, types and expectVisible act on a match only once two reads this many ms apart agree on where it is.
199
+ */
200
+ readonly systemUiSettleMs?: number;
201
+ /**
202
+ * The settle check's second read (issue #87): only the part of the system UI `node` came from, or null
203
+ * for none (act on it now). Without this method: systemNodes().
204
+ */
205
+ systemNodeReread?(node: SystemNode): (() => Promise<SystemNode[]>) | null;
206
+ /**
207
+ * A system alert over the app that dismissSystemAlerts leaves up (iOS: a permission alert, issue #86),
208
+ * described for an error message; undefined when there is none.
209
+ */
210
+ unansweredSystemAlert?(): Promise<string | undefined>;
188
211
  tapSystemNode?(node: SystemNode): Promise<void>;
189
212
  /**
190
213
  * Tap the field `node` and type `text` into it with the device's input (issues #51): iOS through the