@quiesco/core 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@quiesco/core",
3
- "version": "0.3.0",
3
+ "version": "0.4.1",
4
4
  "description": "Quiesco host side: WebSocket server, Driver, device providers (test-runner agnostic)",
5
5
  "license": "MIT",
6
6
  "author": "h2nology",
@@ -50,7 +50,7 @@
50
50
  "ios-runner/QuiescoSystemUI.xcodeproj"
51
51
  ],
52
52
  "dependencies": {
53
- "@quiesco/protocol": "0.3.0",
53
+ "@quiesco/protocol": "0.4.1",
54
54
  "ws": "8.22.1"
55
55
  },
56
56
  "devDependencies": {
@@ -51,9 +51,54 @@ export function newestSource(root: string): { file: string; mtimeMs: number } |
51
51
 
52
52
  const time = (ms: number): string => new Date(ms).toTimeString().slice(0, 8);
53
53
 
54
+ /** Env var `quiesco test` / `quiesco ui` set when they use a Metro they did not start (its URL; issue #19). */
55
+ export const REUSED_DEV_SERVER_ENV = 'QUIESCO_DEV_SERVER_REUSED';
56
+
57
+ /** What explains a bundle the agent did not describe (issue #19). */
58
+ export interface BundleContext {
59
+ /** The Metro the CLI found running and used, not started by Quiesco. */
60
+ reusedDevServer?: string;
61
+ /** Whether the project's metro.config.* uses withQuiesco(); null without a Metro config. */
62
+ metroConfigUsesQuiesco?: boolean | null;
63
+ }
64
+
65
+ /** Whether `root`'s metro.config.* mentions withQuiesco; null when there is no Metro config. */
66
+ export function metroConfigUsesQuiesco(root: string): boolean | null {
67
+ for (const name of ['metro.config.js', 'metro.config.cjs', 'metro.config.mjs', 'metro.config.ts']) {
68
+ let text: string;
69
+ try {
70
+ text = fs.readFileSync(path.join(root, name), 'utf8');
71
+ } catch {
72
+ continue;
73
+ }
74
+ return text.includes('withQuiesco');
75
+ }
76
+ return null;
77
+ }
78
+
79
+ /**
80
+ * Why the bundle is unknown. Only `withQuiesco()` records the bundle, so an unknown one means either the
81
+ * project's Metro config lacks it, or the bundle was not built with this project's config as it is now:
82
+ * a Metro started before an upgrade, by another tool, or without EXPO_PUBLIC_QUIESCO=1.
83
+ */
84
+ function unknownBundleReason(ctx: BundleContext): string {
85
+ if (ctx.metroConfigUsesQuiesco === false || ctx.metroConfigUsesQuiesco === null) return 'no withQuiesco() in metro.config.js';
86
+ if (ctx.reusedDevServer !== undefined) return `the Metro at ${ctx.reusedDevServer} was not started by Quiesco and runs with an unknown config`;
87
+ return 'built without the withQuiesco() in metro.config.js, e.g. before it was added or with an older Quiesco';
88
+ }
89
+
90
+ /**
91
+ * A warning for an unknown bundle from a Metro Quiesco did not start, when the project's config is fine
92
+ * (issue #19): pointing at metro.config.js sent people to the wrong file. Else null.
93
+ */
94
+ export function unknownBundleWarning(bundle: BundleInfo | undefined, ctx: BundleContext): string | null {
95
+ if (bundle !== undefined || ctx.reusedDevServer === undefined || ctx.metroConfigUsesQuiesco !== true) return null;
96
+ return `The app's JS comes from the Metro dev server at ${ctx.reusedDevServer}, which Quiesco did not start, and it does not run with this project's metro.config.js as it is now (started before you upgraded Quiesco or added withQuiesco(), by another tool, or without EXPO_PUBLIC_QUIESCO=1): the app may run old code or the agent may be set up wrong. Restart it with EXPO_PUBLIC_QUIESCO=1 npx expo start, or stop it so that quiesco test starts its own.`;
97
+ }
98
+
54
99
  /** `bundle built 10:02:11, Metro watching files` for the connection log line. */
55
- export function describeBundle(bundle: BundleInfo | undefined): string {
56
- if (bundle === undefined) return 'bundle unknown (no withQuiesco() in metro.config.js)';
100
+ export function describeBundle(bundle: BundleInfo | undefined, ctx: BundleContext = {}): string {
101
+ if (bundle === undefined) return `bundle unknown (${unknownBundleReason(ctx)})`;
57
102
  if (bundle.watching) return `Metro started ${time(bundle.builtAt)}, watching files`;
58
103
  return `bundle built ${time(bundle.builtAt)}, ${bundle.reason === 'CI' ? 'Metro not watching files (CI is set)' : 'a one-off export'}`;
59
104
  }
package/src/config.ts CHANGED
@@ -7,7 +7,7 @@ import path from 'node:path';
7
7
  import { pathToFileURL } from 'node:url';
8
8
 
9
9
  import { DEFAULT_PORT, SyncDefaults } from '@quiesco/protocol';
10
- import type { ActionMode, AgentConfig, GestureSlop, JsonValue, LogLevel, Platform, TrackerName } from '@quiesco/protocol';
10
+ import type { ActionMode, AgentConfig, GestureSlop, JsonValue, LogBoxMode, LogLevel, Platform, TrackerName } from '@quiesco/protocol';
11
11
 
12
12
  import { QuiescoError } from './errors.js';
13
13
  import { toMatcher, toTextMatch } from './matcher.js';
@@ -204,12 +204,20 @@ export interface QuiescoConfig {
204
204
  tags?: Partial<TagNames>;
205
205
  /**
206
206
  * App errors that must not fail the current step (they are logged as warnings instead).
207
- * Matched against the error message; strings match as substrings.
207
+ * Matched against the error message; strings match as substrings. They are also left out of the
208
+ * `console.error`s a failure message lists.
208
209
  */
209
210
  appErrors?: {
210
211
  ignore?: (string | RegExp)[];
211
212
  /** Also ignore the known benign framework reports in DEFAULT_IGNORED_APP_ERRORS. Default true. */
212
213
  ignoreDefaults?: boolean;
214
+ /**
215
+ * React Native's LogBox in dev builds (issue #31). Its toast covers the bottom of the screen, so one
216
+ * `console.error` would make later taps there fail. `clear` (default): clear it on every soft reset;
217
+ * `ignore`: show no LogBox notifications at all (the errors still reach the failure message);
218
+ * `keep`: leave it alone.
219
+ */
220
+ logBox?: LogBoxMode;
213
221
  };
214
222
  }
215
223
 
@@ -275,6 +283,7 @@ export function toAgentConfig(config: QuiescoConfig, gestureSlop?: GestureSlop,
275
283
  logLevel: config.logLevel ?? 'warn',
276
284
  ...(gestures !== undefined ? { gestures } : {}),
277
285
  workerIndex,
286
+ logBox: config.appErrors?.logBox ?? 'clear',
278
287
  };
279
288
  }
280
289
 
@@ -513,11 +513,39 @@ export class AndroidProvider implements DeviceProvider {
513
513
  } else {
514
514
  command = `am start -W -n ${shq(`${this.pkg}/${this.activity}`)} ${extras}`;
515
515
  }
516
- const out = await this.shell(command);
517
- if (/Error:/.test(out)) throw new QuiescoError('DEVICE_ERROR', `am start failed: ${out.trim()}`);
516
+ let out: string;
517
+ try {
518
+ out = await this.shell(command);
519
+ } catch (e) {
520
+ throw await this.launchFailure((e as Error).message);
521
+ }
522
+ if (/Error:/.test(out)) throw await this.launchFailure(out.trim());
518
523
  if (params.url !== undefined) return 'delivered';
519
524
  }
520
525
 
526
+ /**
527
+ * Why `am start` failed, in words (issue #34): the package is not installed (the build has another
528
+ * applicationId than apps.android.package), or the dev client's scheme does not open it.
529
+ */
530
+ private async launchFailure(detail: string): Promise<QuiescoError> {
531
+ const installed = (await this.shell(`pm path ${shq(this.pkg)}`).catch(() => '')).includes('package:');
532
+ const scheme = this.options.app.devClient?.scheme;
533
+ let cause: string | undefined;
534
+ if (!installed) {
535
+ cause =
536
+ `${this.pkg} (apps.android.package) is not installed on ${this.serial ?? 'the device'}. The app at apps.android.binaryPath may have ` +
537
+ 'another applicationId: expo prebuild takes it from expo.android.package in app.json. npx quiesco doctor compares them.';
538
+ } else if (scheme !== undefined) {
539
+ const resolved = await this.shell(`cmd package resolve-activity --brief -a android.intent.action.VIEW -d ${shq(`${scheme}://expo-development-client`)} ${shq(this.pkg)}`).catch(() => '');
540
+ if (!resolved.includes(`${this.pkg}/`)) {
541
+ cause =
542
+ `${this.pkg} is installed but does not open ${scheme}:// links. devClient.scheme must be one of the app's schemes ` +
543
+ '(expo.scheme in app.json, then build again), and the app must be a development build (expo-dev-client).';
544
+ }
545
+ }
546
+ return new QuiescoError('DEVICE_ERROR', `The app could not be started${cause !== undefined ? `: ${cause}` : ''}\n am start: ${detail}`, { package: this.pkg, installed });
547
+ }
548
+
521
549
  private get activity(): string {
522
550
  return this.options.app.activity ?? '.MainActivity';
523
551
  }
package/src/driver.ts CHANGED
@@ -20,15 +20,17 @@ import type {
20
20
  JsonValue,
21
21
  KeyName,
22
22
  ParamsOf,
23
+ Platform,
23
24
  Point,
24
25
  ResultOf,
25
26
  Speed,
27
+ TextMatch,
26
28
  TimedPoint,
27
29
  TrackerState,
28
30
  TreeNode,
29
31
  } from '@quiesco/protocol';
30
32
 
31
- import { QuiescoError } from './errors.js';
33
+ import { QuiescoError, captureCallSite, withCallSite } from './errors.js';
32
34
  import { findNonJson } from './json.js';
33
35
  import type { Logger } from './logger.js';
34
36
  import { silentLogger } from './logger.js';
@@ -78,11 +80,15 @@ const DIALOG: unique symbol = Symbol('dialog');
78
80
 
79
81
  /** Extra wall-clock time on top of the agent-side timeout before the host gives up on a reply. */
80
82
  const HOST_MARGIN_MS = 5_000;
83
+ /** How many of a scenario's `console.error`s the driver keeps. */
84
+ const MAX_APP_LOG_ERRORS = 50;
81
85
  /** Upper bound of steps of scrollToEdge / scrollToIndex in the agent (each may take the call timeout). */
82
86
  const MAX_SCROLL_STEPS = 60;
83
87
 
84
88
  export class Driver {
85
89
  private readonly appErrors: AgentEvents['error'][] = [];
90
+ /** `console.error`s the app logged in this scenario (issue #31), oldest first, at most MAX_APP_LOG_ERRORS. */
91
+ private readonly logErrors: string[] = [];
86
92
  private appErrorListeners = new Set<(e: AgentEvents['error']) => void>();
87
93
  private watched: AgentConnection | null = null;
88
94
  private warnedJsMode = false;
@@ -95,6 +101,14 @@ export class Driver {
95
101
  this.logger = options.logger ?? silentLogger;
96
102
  }
97
103
 
104
+ /**
105
+ * The platform under test (issue #22), for steps or drivers that do the same thing differently per
106
+ * platform. Scenarios for one platform only are better tagged (@ios, @android, @web).
107
+ */
108
+ get platform(): Platform {
109
+ return this.options.provider.platform;
110
+ }
111
+
98
112
  /** `app.device.*`: relaunch, terminate, background / foreground, install, screenshots (Phase 6.5). */
99
113
  get device(): DeviceApi {
100
114
  return this.requireLifecycle().device;
@@ -385,8 +399,14 @@ export class Driver {
385
399
  return this.assert({ type: 'notChecked', matcher: toMatcher(target) }, opts);
386
400
  }
387
401
  /** Input text, switch state, slider / picker value or accessibilityValue equals (or matches) `expected`. */
388
- expectValue(target: MatcherInput, expected: JsonValue | RegExp, opts?: CallOptions): Promise<ElementSummary[]> {
389
- return this.assert({ type: 'value', matcher: toMatcher(target), expected: expected instanceof RegExp ? toTextMatch(expected) : expected }, opts);
402
+ /**
403
+ * The element's value. A date / time picker's value is what it shows, in the device's local time:
404
+ * "2031-12-24" (mode date), "20:15" (time), "2031-12-24T20:15" (datetime), seconds when not 0; a Date
405
+ * matches when those parts agree.
406
+ */
407
+ expectValue(target: MatcherInput, expected: JsonValue | RegExp | Date, opts?: CallOptions): Promise<ElementSummary[]> {
408
+ const value = expected instanceof RegExp ? toTextMatch(expected) : expected instanceof Date ? toControlValue(expected) : expected;
409
+ return this.assert({ type: 'value', matcher: toMatcher(target), expected: value as JsonValue | TextMatch }, opts);
390
410
  }
391
411
  expectLabel(target: MatcherInput, expected: TextQuery, opts?: CallOptions): Promise<ElementSummary[]> {
392
412
  return this.assert({ type: 'label', matcher: toMatcher(target), expected: toTextMatch(expected) }, opts);
@@ -609,8 +629,10 @@ export class Driver {
609
629
  * the background, suspend, configure). Not part of the test API.
610
630
  */
611
631
  async request<M extends keyof AgentMethods>(method: M, params: ParamsOf<AgentMethods[M]>, timeoutMs?: number, steps = 1): Promise<ResultOf<AgentMethods[M]>> {
632
+ // Taken before the first await, so the test's own frames (the step, its driver class) are in it.
633
+ const site = captureCallSite();
612
634
  const pending = this.takeAppError();
613
- if (pending !== null) throw pending;
635
+ if (pending !== null) throw withCallSite(pending, site);
614
636
  const send = async (): Promise<ResultOf<AgentMethods[M]>> => {
615
637
  const conn = await this.options.connection();
616
638
  this.attach(conn);
@@ -631,11 +653,38 @@ export class Driver {
631
653
  try {
632
654
  return await run;
633
655
  } catch (e) {
634
- if (e instanceof QuiescoError) this.lastFailure = e;
656
+ if (e instanceof QuiescoError) {
657
+ this.addLogErrors(e);
658
+ withCallSite(e, site);
659
+ this.lastFailure = e;
660
+ }
635
661
  throw e;
636
662
  }
637
663
  }
638
664
 
665
+ /** The `console.error`s the app logged since the scenario began (issue #31). */
666
+ get appLogErrors(): readonly string[] {
667
+ return this.logErrors;
668
+ }
669
+
670
+ /** A new scenario: forget the app's `console.error`s of the last one. */
671
+ clearAppLogErrors(): void {
672
+ this.logErrors.length = 0;
673
+ }
674
+
675
+ /**
676
+ * A failure in a scenario where the app logged errors names the last one (issue #31): it is often the
677
+ * cause (e.g. a navigation warning before an element disappeared), and a LogBox toast it opened may cover
678
+ * the screen. All of them go in `data.appLogErrors`.
679
+ */
680
+ private addLogErrors(e: QuiescoError): void {
681
+ const n = this.logErrors.length;
682
+ if (n === 0 || e.errorName === 'APP_ERROR' || e.data['appLogErrors'] !== undefined) return;
683
+ const last = (this.logErrors[n - 1] as string).split('\n')[0] as string;
684
+ e.message += `\n The app logged ${n === 1 ? 'a console.error' : `${n} console.errors`} in this scenario; the last: ${last.length > 300 ? `${last.slice(0, 300)}…` : last}`;
685
+ e.data['appLogErrors'] = [...this.logErrors];
686
+ }
687
+
639
688
  /** Fail as soon as the app reports an uncaught error. */
640
689
  private race<T>(p: Promise<T>): Promise<T> {
641
690
  return new Promise<T>((resolve, reject) => {
@@ -653,6 +702,12 @@ export class Driver {
653
702
  attach(conn: AgentConnection): void {
654
703
  if (this.watched === conn) return;
655
704
  this.watched = conn;
705
+ conn.on('log', (l) => {
706
+ if (this.watched !== conn || l.level !== 'error') return;
707
+ if (this.options.ignoreAppErrors?.some((re) => re.test(l.message)) === true) return;
708
+ this.logErrors.push(l.message);
709
+ if (this.logErrors.length > MAX_APP_LOG_ERRORS) this.logErrors.shift();
710
+ });
656
711
  conn.on('appError', (e) => {
657
712
  if (this.watched !== conn) return;
658
713
  if (this.options.ignoreAppErrors?.some((re) => re.test(e.message)) === true) {
package/src/errors.ts CHANGED
@@ -39,3 +39,38 @@ export class QuiescoError extends Error {
39
39
  return new QuiescoError(name, error.message, data, error.code);
40
40
  }
41
41
  }
42
+
43
+ /** This package's own source / build directory (frames from here are plumbing to a test author). */
44
+ const OWN_DIR = new URL('.', import.meta.url).href;
45
+ const OWN_PATH = decodeURIComponent(new URL('.', import.meta.url).pathname);
46
+
47
+ /** A stack frame that tells a test author nothing: Quiesco's own code, the `ws` library, Node internals. */
48
+ function isInternalFrame(frame: string): boolean {
49
+ return frame.includes(OWN_DIR) || frame.includes(OWN_PATH) || /[\\/]node_modules[\\/](?:\.pnpm[\\/][^\\/]+[\\/]node_modules[\\/])?ws[\\/]/.test(frame) || /\((?:node:|internal\/)|at (?:node:|internal\/)/.test(frame);
50
+ }
51
+
52
+ /**
53
+ * The stack of the caller, taken where a driver call starts (issue #32). Errors that arrive later (an RPC
54
+ * error response, a timeout, an app error) are created on a WebSocket / timer callback, whose stack
55
+ * has only the transport's frames; {@link withCallSite} gives them this one instead.
56
+ */
57
+ export function captureCallSite(): Error {
58
+ const limit = Error.stackTraceLimit;
59
+ Error.stackTraceLimit = 50;
60
+ try {
61
+ return new Error('call site');
62
+ } finally {
63
+ Error.stackTraceLimit = limit;
64
+ }
65
+ }
66
+
67
+ /**
68
+ * Point `error`'s stack at the code that made the call: the frames of `site` without Quiesco's own,
69
+ * `ws`'s and Node's. Keeps the error's stack when nothing would be left (e.g. a call made by Quiesco itself).
70
+ */
71
+ export function withCallSite<E extends Error>(error: E, site: Error): E {
72
+ const frames = (site.stack ?? '').split('\n').filter((l) => /^\s+at /.test(l) && !isInternalFrame(l));
73
+ if (frames.length === 0) return error;
74
+ Object.defineProperty(error, 'stack', { value: `${error.name}: ${error.message}\n${frames.join('\n')}`, writable: true, configurable: true });
75
+ return error;
76
+ }
package/src/index.ts CHANGED
@@ -16,6 +16,7 @@ export { Session, createSession, createProvider } from './session.js';
16
16
  export { Lifecycle, titleTags } from './lifecycle.js';
17
17
  export type { AfterResult, LifecycleOptions, ScenarioResult } from './lifecycle.js';
18
18
  export { attachToRunningApp } from './attach.js';
19
+ export { REUSED_DEV_SERVER_ENV } from './bundle-check.js';
19
20
  export type { AttachOptions, AttachedApp } from './attach.js';
20
21
  export { DEFAULT_TAGS, flattenTags, runsOnPlatform, tagNames } from './tags.js';
21
22
  export type { ScenarioTags, TagNames } from './tags.js';
package/src/session.ts CHANGED
@@ -16,7 +16,8 @@ import type { DeviceProvider, LaunchParams, LaunchUrlHandling, WorkerInfo } from
16
16
  import { DeviceApi } from './device.js';
17
17
  import type { AppRunState, DeviceHost } from './device.js';
18
18
  import { Artifacts } from './artifacts.js';
19
- import { describeBundle, staleBundleWarning } from './bundle-check.js';
19
+ import { REUSED_DEV_SERVER_ENV, describeBundle, metroConfigUsesQuiesco, staleBundleWarning, unknownBundleWarning } from './bundle-check.js';
20
+ import type { BundleContext } from './bundle-check.js';
20
21
  import type { Attachment, ScenarioArtifacts } from './artifacts.js';
21
22
  import { Driver } from './driver.js';
22
23
  import { failureRects, highlight } from './screenshots.js';
@@ -125,6 +126,11 @@ export class Session {
125
126
  private offline = false;
126
127
  private readonly defaultArgs: LaunchArgs;
127
128
 
129
+ /** The platform under test (issue #22). */
130
+ get platform(): Platform {
131
+ return this.provider.platform;
132
+ }
133
+
128
134
  private constructor(
129
135
  readonly config: QuiescoConfig,
130
136
  readonly provider: DeviceProvider,
@@ -245,6 +251,7 @@ export class Session {
245
251
  */
246
252
  async startScenario(info: ScenarioInfo = {}): Promise<void> {
247
253
  this.driver.lastFailure = null;
254
+ this.driver.clearAppLogErrors();
248
255
  await this.artifacts.beginScenario(info.name ?? 'scenario');
249
256
  }
250
257
 
@@ -261,6 +268,9 @@ export class Session {
261
268
  if (ev.tree !== undefined) evidence.push({ data: JSON.stringify({ elementTree: ev.tree }, null, 2), mediaType: 'application/json', fileName: 'element-tree.json' });
262
269
  if (ev.idle !== undefined) evidence.push({ data: JSON.stringify({ idleState: ev.idle }, null, 2), mediaType: 'application/json', fileName: 'idle-state.json' });
263
270
  if (ev.errors.length > 0) evidence.push({ data: `Quiesco could not collect: ${ev.errors.join('; ')}`, mediaType: 'text/plain', fileName: 'evidence-errors.txt' });
271
+ // Issue #31: what the app logged with console.error in this scenario, oldest first.
272
+ const logged = this.driver.appLogErrors;
273
+ if (logged.length > 0) evidence.push({ data: `${logged.join('\n\n')}\n`, mediaType: 'text/plain', fileName: 'app-errors.txt' });
264
274
  }
265
275
  return this.artifacts.endScenario({ failed: result.failed, evidence });
266
276
  }
@@ -324,12 +334,24 @@ export class Session {
324
334
  private readonly projectRoot = process.cwd();
325
335
  /** Bundles already checked (by build time): a reconnect of the same bundle is not checked again. */
326
336
  private readonly checkedBundles = new Set<number>();
337
+ /** The unknown-bundle warning (issue #19) is given once per session, not on every reconnect. */
338
+ private unknownBundleWarned = false;
327
339
 
328
340
  /** Issue #3: say when the app's JS bundle cannot have the project's latest changes. Once per bundle. */
329
341
  private checkBundle(conn: AgentConnection): void {
330
342
  const bundle = conn.info.bundle;
331
- this.logger.debug(`app JS: ${describeBundle(bundle)}`);
332
- if (bundle === undefined || this.checkedBundles.has(bundle.builtAt)) return;
343
+ const reused = process.env[REUSED_DEV_SERVER_ENV];
344
+ const context: BundleContext = { metroConfigUsesQuiesco: metroConfigUsesQuiesco(this.projectRoot), ...(reused !== undefined && reused !== '' ? { reusedDevServer: reused } : {}) };
345
+ this.logger.debug(`app JS: ${describeBundle(bundle, context)}`);
346
+ if (bundle === undefined) {
347
+ const warning = this.unknownBundleWarned ? null : unknownBundleWarning(bundle, context);
348
+ if (warning !== null) {
349
+ this.unknownBundleWarned = true;
350
+ this.logger.warn(warning);
351
+ }
352
+ return;
353
+ }
354
+ if (this.checkedBundles.has(bundle.builtAt)) return;
333
355
  this.checkedBundles.add(bundle.builtAt);
334
356
  const warning = staleBundleWarning(bundle, this.projectRoot);
335
357
  if (warning !== null) this.logger.warn(warning);