@quiesco/protocol 0.0.0-stage → 0.1.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.
Files changed (68) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +10 -2
  3. package/dist/actions.d.ts +238 -0
  4. package/dist/actions.d.ts.map +1 -0
  5. package/dist/actions.js +2 -0
  6. package/dist/actions.js.map +1 -0
  7. package/dist/assertions.d.ts +74 -0
  8. package/dist/assertions.d.ts.map +1 -0
  9. package/dist/assertions.js +2 -0
  10. package/dist/assertions.js.map +1 -0
  11. package/dist/config.d.ts +54 -0
  12. package/dist/config.d.ts.map +1 -0
  13. package/dist/config.js +2 -0
  14. package/dist/config.js.map +1 -0
  15. package/dist/constants.d.ts +43 -0
  16. package/dist/constants.d.ts.map +1 -0
  17. package/dist/constants.js +42 -0
  18. package/dist/constants.js.map +1 -0
  19. package/dist/element.d.ts +49 -0
  20. package/dist/element.d.ts.map +1 -0
  21. package/dist/element.js +2 -0
  22. package/dist/element.js.map +1 -0
  23. package/dist/errors.d.ts +106 -0
  24. package/dist/errors.d.ts.map +1 -0
  25. package/dist/errors.js +26 -0
  26. package/dist/errors.js.map +1 -0
  27. package/dist/events.d.ts +19 -0
  28. package/dist/events.d.ts.map +1 -0
  29. package/dist/events.js +2 -0
  30. package/dist/events.js.map +1 -0
  31. package/dist/index.d.ts +13 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +13 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/json.d.ts +6 -0
  36. package/dist/json.d.ts.map +1 -0
  37. package/dist/json.js +2 -0
  38. package/dist/json.js.map +1 -0
  39. package/dist/matcher.d.ts +44 -0
  40. package/dist/matcher.d.ts.map +1 -0
  41. package/dist/matcher.js +22 -0
  42. package/dist/matcher.js.map +1 -0
  43. package/dist/messages.d.ts +49 -0
  44. package/dist/messages.d.ts.map +1 -0
  45. package/dist/messages.js +2 -0
  46. package/dist/messages.js.map +1 -0
  47. package/dist/methods.d.ts +256 -0
  48. package/dist/methods.d.ts.map +1 -0
  49. package/dist/methods.js +2 -0
  50. package/dist/methods.js.map +1 -0
  51. package/dist/webview.d.ts +9 -0
  52. package/dist/webview.d.ts.map +1 -0
  53. package/dist/webview.js +31 -0
  54. package/dist/webview.js.map +1 -0
  55. package/package.json +47 -3
  56. package/src/actions.ts +107 -0
  57. package/src/assertions.ts +29 -0
  58. package/src/config.ts +54 -0
  59. package/src/constants.ts +46 -0
  60. package/src/element.ts +51 -0
  61. package/src/errors.ts +61 -0
  62. package/src/events.ts +11 -0
  63. package/src/index.ts +12 -0
  64. package/src/json.ts +3 -0
  65. package/src/matcher.ts +59 -0
  66. package/src/messages.ts +55 -0
  67. package/src/methods.ts +140 -0
  68. package/src/webview.ts +30 -0
@@ -0,0 +1,31 @@
1
+ /**
2
+ * WebView pages (Phase 6.8): the script Quiesco installs in a WebView's pages to know when they are busy.
3
+ * The agent registers it to run at document start of every later load (native WebViews) and the host's
4
+ * page-state script runs it in the current page too; it is idempotent.
5
+ *
6
+ * It counts the page's fetch / XMLHttpRequest calls still running in `window.__quiescoPending`.
7
+ */
8
+ export const WEBVIEW_HOOK = `(function () {
9
+ if (window.__quiescoHook) return;
10
+ window.__quiescoHook = true;
11
+ window.__quiescoPending = 0;
12
+ var done = function () { window.__quiescoPending = Math.max(0, window.__quiescoPending - 1); };
13
+ if (typeof window.fetch === 'function') {
14
+ var f = window.fetch;
15
+ window.fetch = function () {
16
+ window.__quiescoPending++;
17
+ var p;
18
+ try { p = f.apply(this, arguments); } catch (e) { done(); throw e; }
19
+ return p.then(function (r) { done(); return r; }, function (e) { done(); throw e; });
20
+ };
21
+ }
22
+ if (typeof XMLHttpRequest === 'function') {
23
+ var send = XMLHttpRequest.prototype.send;
24
+ XMLHttpRequest.prototype.send = function () {
25
+ window.__quiescoPending++;
26
+ this.addEventListener('loadend', done);
27
+ try { return send.apply(this, arguments); } catch (e) { done(); throw e; }
28
+ };
29
+ }
30
+ })();`;
31
+ //# sourceMappingURL=webview.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"webview.js","sourceRoot":"","sources":["../src/webview.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;MAsBtB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
2
  "name": "@quiesco/protocol",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.1",
4
+ "description": "Shared protocol types and constants between the Quiesco host and agent",
5
+ "license": "MIT",
6
+ "author": "h2nology",
7
+ "keywords": [
8
+ "quiesco",
9
+ "e2e",
10
+ "testing",
11
+ "expo",
12
+ "react-native",
13
+ "protocol",
14
+ "json-rpc"
15
+ ],
16
+ "homepage": "https://github.com/h2nology/quiesco/tree/main/packages/protocol#readme",
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/h2nology/quiesco.git",
20
+ "directory": "packages/protocol"
21
+ },
22
+ "bugs": {
23
+ "url": "https://github.com/h2nology/quiesco/issues"
24
+ },
25
+ "engines": {
26
+ "node": ">=24"
27
+ },
28
+ "publishConfig": {
29
+ "access": "public"
30
+ },
31
+ "type": "module",
32
+ "main": "./dist/index.js",
33
+ "types": "./dist/index.d.ts",
34
+ "exports": {
35
+ ".": {
36
+ "types": "./dist/index.d.ts",
37
+ "import": "./dist/index.js"
38
+ }
39
+ },
40
+ "files": [
41
+ "dist",
42
+ "src"
43
+ ],
44
+ "dependencies": {},
45
+ "react-native": "./src/index.ts",
46
+ "scripts": {
47
+ "build": "tsc -b",
48
+ "test": "vitest run"
49
+ }
6
50
  }
package/src/actions.ts ADDED
@@ -0,0 +1,107 @@
1
+ import type { Matcher } from './matcher.js';
2
+
3
+ export type ActionMode = 'native' | 'js';
4
+ export type Direction = 'up' | 'down' | 'left' | 'right';
5
+ export type Speed = 'slow' | 'normal' | 'fast';
6
+
7
+ /** A point: in an element's own coordinates (`point`) or in window coordinates (`tapAt`), logical units. */
8
+ export interface Point {
9
+ x: number;
10
+ y: number;
11
+ }
12
+
13
+ /** Keys of the software keyboard that `pressKey` can send. */
14
+ export type KeyName = 'enter' | 'backspace';
15
+
16
+ /** Edges for `scrollToEdge`. */
17
+ export type Edge = 'top' | 'bottom' | 'left' | 'right';
18
+
19
+ /** A finger's position at a time: ms from the start of the gesture. */
20
+ export interface TimedPoint {
21
+ x: number;
22
+ y: number;
23
+ t: number;
24
+ }
25
+
26
+ /** A date in JSON: ISO 8601 (`Date.prototype.toISOString()`). */
27
+ export interface DateValue {
28
+ date: string;
29
+ }
30
+
31
+ /**
32
+ * What `setValue` sets (Phase 6.3): a number (slider), a boolean (switch, checkbox), a string (picker item
33
+ * value or label, segment value) or a date (date / time picker, `<input type="date">`).
34
+ */
35
+ export type ControlValue = number | boolean | string | DateValue;
36
+
37
+ /**
38
+ * Actions from requirements.md §6.3 (extended in Phase 6.2).
39
+ * - `point`: where to touch inside the element (default: its center).
40
+ * - `from`: start of a scroll / swipe inside the element, normalized 0–1 (default: around the center).
41
+ * - `distance`: finger travel in logical units.
42
+ */
43
+ export type ActionSpec =
44
+ | { type: 'tap'; matcher: Matcher; point?: Point }
45
+ | { type: 'longPress'; matcher: Matcher; durationMs?: number; point?: Point }
46
+ | { type: 'doubleTap'; matcher: Matcher }
47
+ | { type: 'multiTap'; matcher: Matcher; count: number }
48
+ | { type: 'type'; matcher: Matcher; text: string }
49
+ | { type: 'replaceText'; matcher: Matcher; text: string }
50
+ | { type: 'clear'; matcher: Matcher }
51
+ | { type: 'pressKey'; matcher: Matcher; key: KeyName }
52
+ | { type: 'scroll'; matcher: Matcher; direction: Direction; distance?: number; from?: Point }
53
+ | { type: 'scrollTo'; container: Matcher; target: Matcher }
54
+ | { type: 'scrollToEdge'; matcher: Matcher; edge: Edge }
55
+ /** `viewPosition`: 0 = row at the top of the list, 0.5 = middle, 1 = bottom. */
56
+ | { type: 'scrollToIndex'; matcher: Matcher; index: number; viewPosition?: number }
57
+ | { type: 'swipe'; matcher: Matcher; direction: Direction; speed?: Speed; distance?: number; from?: Point }
58
+ /** Press and hold `holdMs`, then move to the center of the `to` element or to a window point. */
59
+ | { type: 'drag'; matcher: Matcher; to: { matcher: Matcher } | { point: Point }; holdMs?: number; speed?: Speed }
60
+ /** Window coordinates, no element (Detox `device.tap(point)`). */
61
+ | { type: 'tapAt'; point: Point }
62
+ | { type: 'longPressAt'; point: Point; durationMs?: number }
63
+ /** Set a value control (slider, switch, picker, segmented control, date picker) to `value`. */
64
+ | { type: 'setValue'; matcher: Matcher; value: ControlValue }
65
+ /** Move a slider's thumb to `position` (0 = minimum, 1 = maximum) — Detox adjustSliderToPosition. */
66
+ | { type: 'adjustSlider'; matcher: Matcher; position: number }
67
+ /** Perform a declared accessibility action (`accessibilityActions`) — Detox performAccessibilityAction. */
68
+ | { type: 'accessibilityAction'; matcher: Matcher; name: string }
69
+ /** Two fingers change their distance by `scale` (> 1 apart, < 1 together) on a line at `angle` radians (0 = horizontal). */
70
+ | { type: 'pinch'; matcher: Matcher; scale: number; angle?: number; speed?: Speed }
71
+ /** Two fingers turn `radians` (positive: clockwise on screen) around the element's center. */
72
+ | { type: 'rotate'; matcher: Matcher; radians: number; speed?: Speed }
73
+ /**
74
+ * Fingers along timed paths (each finger is down from its first to its last point). Window
75
+ * coordinates, or the element's own coordinates when `matcher` is given.
76
+ */
77
+ | { type: 'multiTouch'; matcher?: Matcher; fingers: TimedPoint[][] }
78
+ | { type: 'pressBack' }
79
+ | { type: 'openUrl'; url: string }
80
+ | { type: 'dismissKeyboard' };
81
+
82
+ export type ActionType = ActionSpec['type'];
83
+
84
+ /**
85
+ * Real input that the HOST must inject (web `native` mode: Playwright mouse/keyboard).
86
+ * Coordinates are window coordinates in the platform's logical units.
87
+ */
88
+ export type HostInput =
89
+ | { kind: 'tap'; x: number; y: number; count?: number; holdMs?: number }
90
+ | { kind: 'type'; x: number; y: number; text: string; clearFirst?: boolean }
91
+ /** Press at `from`, hold `holdMs`, move to `to` over `durationMs`, release. */
92
+ | { kind: 'drag'; from: { x: number; y: number }; to: { x: number; y: number }; durationMs: number; holdMs?: number }
93
+ /** Mouse wheel at (x, y); positive `dy` scrolls content down (reveals what is below). */
94
+ | { kind: 'wheel'; x: number; y: number; dx: number; dy: number }
95
+ /** Press a key on the focused element (Playwright key name, e.g. `Enter`, `Backspace`). */
96
+ | { kind: 'key'; key: string }
97
+ /**
98
+ * Several fingers (touch screens): flat frames `[tMs, down0, x0, y0, down1, x1, y1, ...]` for
99
+ * `fingers` fingers, played back as touch events (web: CDP Input.dispatchTouchEvent).
100
+ */
101
+ | { kind: 'touches'; fingers: number; frames: number[] }
102
+ /** Choose the option with this value in the `<select>` at (x, y) (Playwright selectOption). */
103
+ | { kind: 'select'; x: number; y: number; value: string }
104
+ /** Set the value of the `<input>` at (x, y) as a user would (Playwright fill: date / time inputs). */
105
+ | { kind: 'fill'; x: number; y: number; value: string }
106
+ | { kind: 'navigate'; url: string }
107
+ | { kind: 'back' };
@@ -0,0 +1,29 @@
1
+ import type { JsonValue } from './json.js';
2
+ import type { Matcher, TextMatch } from './matcher.js';
3
+
4
+ /**
5
+ * Assertions from requirements.md §6.4. Evaluated by the agent, retried until they pass or time out.
6
+ * `not: true` negates text / prop / count / value / label (the single-element ones still need exactly
7
+ * one match); the other assertions come in pairs.
8
+ */
9
+ export type AssertionSpec =
10
+ /** `ratio`: minimum visible fraction of the element's area (0–1]; default: any part visible. */
11
+ | { type: 'visible'; matcher: Matcher; ratio?: number }
12
+ /** No match shows `ratio` of its area (default: no match is visible at all). */
13
+ | { type: 'notVisible'; matcher: Matcher; ratio?: number }
14
+ | { type: 'exists'; matcher: Matcher }
15
+ | { type: 'notExists'; matcher: Matcher }
16
+ | { type: 'text'; matcher: Matcher; expected: TextMatch; not?: boolean }
17
+ | { type: 'prop'; matcher: Matcher; prop: string; expected: JsonValue; not?: boolean }
18
+ | { type: 'count'; matcher: Matcher; expected: number; not?: boolean }
19
+ | { type: 'focused'; matcher: Matcher }
20
+ | { type: 'notFocused'; matcher: Matcher }
21
+ | { type: 'enabled'; matcher: Matcher }
22
+ | { type: 'disabled'; matcher: Matcher }
23
+ | { type: 'checked'; matcher: Matcher }
24
+ | { type: 'notChecked'; matcher: Matcher }
25
+ /** The element's value (TextInput text, Switch / Slider / Picker value, accessibilityValue). */
26
+ | { type: 'value'; matcher: Matcher; expected: JsonValue | TextMatch; not?: boolean }
27
+ | { type: 'label'; matcher: Matcher; expected: TextMatch; not?: boolean };
28
+
29
+ export type AssertionType = AssertionSpec['type'];
package/src/config.ts ADDED
@@ -0,0 +1,54 @@
1
+ import type { LogLevel } from './events.js';
2
+ import type { Matcher, TextMatch } from './matcher.js';
3
+
4
+ export const TRACKER_NAMES = ['network', 'timer', 'react', 'idle-callback', 'frame-stable', 'native'] as const;
5
+ export type TrackerName = (typeof TRACKER_NAMES)[number];
6
+
7
+ /**
8
+ * Agent-side settings derived from `quiesco.config.ts` (requirements.md §6.2, §6.13).
9
+ * Sent by the host in the `hello` result, so trackers installed at app start can be configured later.
10
+ */
11
+ export interface AgentConfig {
12
+ sync: {
13
+ timeoutMs: number;
14
+ timerThresholdMs: number;
15
+ countIntervals: boolean;
16
+ stableFrames: number;
17
+ /** URL patterns ignored by the network tracker. Strings match as substrings. */
18
+ ignoreUrls: TextMatch[];
19
+ /** Per-tracker switch; omitted trackers are enabled. */
20
+ trackers: Partial<Record<TrackerName, boolean>>;
21
+ /**
22
+ * Elements (and their subtrees) left out of the frame-stable check, e.g. a decorative animation that
23
+ * runs for minutes. Optional for older hosts.
24
+ */
25
+ ignoreElements?: Matcher[];
26
+ };
27
+ /** Minimum console level forwarded as `log` events; `off` disables forwarding. */
28
+ logLevel: LogLevel | 'off';
29
+ /**
30
+ * How far fingers move before the platform's gesture recognizers activate (they measure from there):
31
+ * pinch / rotate move this much first, so the app sees the requested scale / angle (Phase 6.4).
32
+ * Logical units and radians. Optional for older hosts (no compensation).
33
+ */
34
+ gestures?: GestureSlop;
35
+ /**
36
+ * Simulated offline mode (Phase 6.6 `app.device.setNetwork('offline')`): the agent fails the app's new
37
+ * fetch / XMLHttpRequest / WebSocket connections, except its own connection and the dev server. Optional
38
+ * for older hosts (online).
39
+ */
40
+ network?: { offline: boolean };
41
+ /**
42
+ * Index of the parallel test worker this app is connected to (0 when running serially; Phase 6.12).
43
+ * Lets e2e code pick per-worker resources, e.g. a mock backend on `3001 + workerIndex`. Optional for
44
+ * older hosts.
45
+ */
46
+ workerIndex?: number;
47
+ }
48
+
49
+ export interface GestureSlop {
50
+ /** Change of the distance between two fingers before a pinch recognizer activates. */
51
+ pinch: number;
52
+ /** Rotation before a rotation recognizer activates, in radians. */
53
+ rotation: number;
54
+ }
@@ -0,0 +1,46 @@
1
+ /** Bumped on any incompatible protocol change. The host rejects agents with a different major version. */
2
+ export const PROTOCOL_VERSION = 1;
3
+
4
+ /**
5
+ * Keys used to pass connection parameters to the app at launch (docs/spikes/05-connection-params.md).
6
+ * - iOS: process arguments `-quiescoPort <port> -quiescoSession <id>` (read via UserDefaults)
7
+ * - Android: intent extras `--es quiescoPort <port> --es quiescoSession <id>`
8
+ * - Web: `window.__QUIESCO__ = { port, session }` injected with Playwright's addInitScript
9
+ */
10
+ export const LAUNCH_PARAM_PORT = 'quiescoPort';
11
+ export const LAUNCH_PARAM_SESSION = 'quiescoSession';
12
+ /**
13
+ * Test launch arguments (Phase 6.5): one parameter holding base64 of the JSON object, so values keep
14
+ * their types and no device shell quoting is involved. The JSON is ASCII-only (non-ASCII characters
15
+ * escaped as \uXXXX), so plain `atob` decodes it. Web: `window.__QUIESCO__.args` holds the object itself.
16
+ */
17
+ export const LAUNCH_PARAM_ARGS = 'quiescoArgs';
18
+ /** iOS: the URL the app is opened with at launch, handed to expo-linking by @quiesco/native. */
19
+ export const LAUNCH_PARAM_URL = 'quiescoUrl';
20
+ export const WEB_PARAMS_GLOBAL = '__QUIESCO__';
21
+
22
+ /** Used when no launch parameters are available (JS-only mode, single device). */
23
+ export const DEFAULT_PORT = 7357;
24
+
25
+ /** WebSocket close codes (4000-4999 are reserved for applications by RFC 6455). */
26
+ export const CloseCode = {
27
+ /** Normal shutdown by the host. */
28
+ NORMAL: 1000,
29
+ /** The agent's session id does not match any session the host is waiting for. */
30
+ SESSION_MISMATCH: 4001,
31
+ /** Incompatible protocol version. */
32
+ PROTOCOL_MISMATCH: 4002,
33
+ /** A newer connection for the same session replaced this one (e.g. web full-page reload). */
34
+ REPLACED: 4003,
35
+ } as const;
36
+ export type CloseCode = (typeof CloseCode)[keyof typeof CloseCode];
37
+
38
+ /** Defaults from requirements.md §6.2 / §6.13. */
39
+ export const SyncDefaults = {
40
+ timeoutMs: 10_000,
41
+ timerThresholdMs: 1_500,
42
+ stableFrames: 2,
43
+ countIntervals: false,
44
+ /** Interval between re-checks while an assertion fails or an action target is not ready yet. */
45
+ retryIntervalMs: 50,
46
+ } as const;
package/src/element.ts ADDED
@@ -0,0 +1,51 @@
1
+ import type { JsonValue } from './json.js';
2
+ import type { SemanticType } from './matcher.js';
3
+
4
+ /** Rectangle in the platform's logical units (dp on Android, pt on iOS, CSS px on web), window coordinates. */
5
+ export interface Rect {
6
+ x: number;
7
+ y: number;
8
+ width: number;
9
+ height: number;
10
+ }
11
+
12
+ /** What the agent reports about a matched element. */
13
+ export interface ElementSummary {
14
+ /** Host component type, e.g. `RCTView`, `RCTText`, `div`. */
15
+ type: string;
16
+ testID?: string;
17
+ text: string;
18
+ role?: string;
19
+ label?: string;
20
+ rect: Rect | null;
21
+ visible: boolean;
22
+ /**
23
+ * Visible fraction of the element's area (0–1): the part inside the window and inside every
24
+ * ancestor that clips its content (scroll views, `overflow: hidden`). 0 when hidden by style.
25
+ */
26
+ visibleRatio: number;
27
+ /** Platform-independent kind, when the element is one of SEMANTIC_TYPES. */
28
+ semanticType?: SemanticType;
29
+ /** Has the input focus (text inputs; the focused DOM element on the web). */
30
+ focused: boolean;
31
+ /** False when disabled (`disabled`, `accessibilityState.disabled`, `aria-disabled`, `editable={false}`). */
32
+ enabled: boolean;
33
+ /** Checked state of switches, checkboxes and radios (`accessibilityState.checked`, `aria-checked`, Switch `value`). */
34
+ checked?: boolean | 'mixed';
35
+ /** Current value: TextInput text, Switch / Slider / Picker value, or `accessibilityValue`. */
36
+ value?: JsonValue;
37
+ /** Serializable subset of the element's props (functions and React elements are dropped). */
38
+ props: Record<string, JsonValue>;
39
+ }
40
+
41
+ /** Compact element tree for diagnostics (`getTree`). */
42
+ export interface TreeNode {
43
+ type: string;
44
+ testID?: string;
45
+ text?: string;
46
+ role?: string;
47
+ semanticType?: SemanticType;
48
+ /** Rounded rect. */
49
+ rect?: Rect;
50
+ children: TreeNode[];
51
+ }
package/src/errors.ts ADDED
@@ -0,0 +1,61 @@
1
+ import type { ActionType } from './actions.js';
2
+ import type { ElementSummary } from './element.js';
3
+ import type { JsonValue } from './json.js';
4
+ import type { Matcher } from './matcher.js';
5
+ import type { TrackerState } from './methods.js';
6
+
7
+ /** Standard JSON-RPC 2.0 error codes. */
8
+ export const JsonRpcErrorCode = {
9
+ PARSE_ERROR: -32700,
10
+ INVALID_REQUEST: -32600,
11
+ METHOD_NOT_FOUND: -32601,
12
+ INVALID_PARAMS: -32602,
13
+ INTERNAL_ERROR: -32603,
14
+ } as const;
15
+
16
+ /** Quiesco error codes (requirements.md §7). */
17
+ export const ErrorCode = {
18
+ ELEMENT_NOT_FOUND: 1001,
19
+ MULTIPLE_MATCHES: 1002,
20
+ SYNC_TIMEOUT: 1003,
21
+ ASSERTION_FAILED: 1004,
22
+ ACTION_NOT_SUPPORTED: 1005,
23
+ BACKDOOR_NOT_REGISTERED: 1006,
24
+ NOT_SERIALIZABLE: 1007,
25
+ BACKDOOR_FAILED: 1008,
26
+ PROTOCOL_MISMATCH: 1009,
27
+ SESSION_MISMATCH: 1010,
28
+ AGENT_NOT_READY: 1011,
29
+ APP_ERROR: 1012,
30
+ RESET_FAILED: 1013,
31
+ ELEMENT_OBSCURED: 1014,
32
+ } as const;
33
+ export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
34
+ export type ErrorName = keyof typeof ErrorCode;
35
+
36
+ /** Structured `error.data` for each Quiesco error code. */
37
+ export interface ErrorDataMap {
38
+ /** `reason: 'not-in-window'`: React rendered it, but no window shows it (e.g. a system alert is over the app; Phase 6.12). */
39
+ ELEMENT_NOT_FOUND: { matcher: Matcher; reason?: 'not-in-window' };
40
+ MULTIPLE_MATCHES: { matcher: Matcher; matches: ElementSummary[] };
41
+ SYNC_TIMEOUT: { timeoutMs: number; busy: TrackerState[] };
42
+ ASSERTION_FAILED: { expected: JsonValue; actual: JsonValue; elements: ElementSummary[] };
43
+ ACTION_NOT_SUPPORTED: { action: ActionType | 'webview'; platform: string; hint?: string };
44
+ BACKDOOR_NOT_REGISTERED: { name: string; registered: string[] };
45
+ NOT_SERIALIZABLE: { where: 'args' | 'result'; path: string };
46
+ BACKDOOR_FAILED: { name: string; message: string; stack?: string };
47
+ PROTOCOL_MISMATCH: { host: number; agent: number };
48
+ SESSION_MISMATCH: { expected: string[]; received: string | null };
49
+ AGENT_NOT_READY: { reason: string };
50
+ APP_ERROR: { message: string; stack?: string };
51
+ RESET_FAILED: { step: string; message: string };
52
+ /** A real touch would not reach the element: another element or window is on top of it. */
53
+ /** `native`: what the native hit test saw (iOS: hit view and its superviews, presented view controllers). */
54
+ ELEMENT_OBSCURED: { matcher: Matcher; element: ElementSummary; obscuredBy: string; native?: Record<string, unknown> };
55
+ }
56
+
57
+ export interface QuiescoErrorObject<N extends ErrorName = ErrorName> {
58
+ code: (typeof ErrorCode)[N];
59
+ message: string;
60
+ data: { name: N } & ErrorDataMap[N];
61
+ }
package/src/events.ts ADDED
@@ -0,0 +1,11 @@
1
+ /** Notifications sent by the agent (no `id`, no response). requirements.md §7. */
2
+ export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
3
+
4
+ export interface AgentEvents {
5
+ /** App-side console output forwarded to the host (level is configurable). */
6
+ log: { level: LogLevel; message: string; timestamp: number };
7
+ /** Uncaught exception / red box / unhandled rejection: the current step must fail immediately. */
8
+ error: { kind: 'uncaught' | 'unhandledRejection' | 'redbox'; message: string; stack?: string; timestamp: number };
9
+ }
10
+
11
+ export type AgentEventName = keyof AgentEvents;
package/src/index.ts ADDED
@@ -0,0 +1,12 @@
1
+ export * from './actions.js';
2
+ export * from './assertions.js';
3
+ export * from './config.js';
4
+ export * from './constants.js';
5
+ export * from './element.js';
6
+ export * from './errors.js';
7
+ export * from './events.js';
8
+ export * from './json.js';
9
+ export * from './matcher.js';
10
+ export * from './messages.js';
11
+ export * from './methods.js';
12
+ export * from './webview.js';
package/src/json.ts ADDED
@@ -0,0 +1,3 @@
1
+ /** Any value that survives JSON.stringify / JSON.parse unchanged. */
2
+ export type JsonPrimitive = string | number | boolean | null;
3
+ export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
package/src/matcher.ts ADDED
@@ -0,0 +1,59 @@
1
+ /** A regular expression in JSON form (RegExp itself is not serializable). */
2
+ export interface RegexPattern {
3
+ regex: { source: string; flags: string };
4
+ }
5
+
6
+ /** Exact string or regular expression. */
7
+ export type TextMatch = string | RegexPattern;
8
+
9
+ /**
10
+ * Platform-independent element kinds (requirements.md §6.1, Phase 6.1). Derived from the host
11
+ * component type, the accessibility role and the props of the owning component; the same element
12
+ * gets the same kind on iOS, Android and the web.
13
+ */
14
+ export const SEMANTIC_TYPES = [
15
+ 'button',
16
+ 'link',
17
+ 'header',
18
+ 'text',
19
+ 'input',
20
+ 'image',
21
+ 'switch',
22
+ 'checkbox',
23
+ 'radio',
24
+ 'slider',
25
+ 'picker',
26
+ 'progress',
27
+ 'scroll',
28
+ 'list',
29
+ ] as const;
30
+
31
+ export type SemanticType = (typeof SEMANTIC_TYPES)[number];
32
+
33
+ /**
34
+ * Element query (requirements.md §6.1). All given fields must match.
35
+ * Only host components (views that end up as native views / DOM nodes) are returned.
36
+ */
37
+ export interface Matcher {
38
+ /** `testID`: exact string or regular expression. */
39
+ id?: TextMatch;
40
+ /** Text content of the element (concatenated text of its subtree). */
41
+ text?: TextMatch;
42
+ /** `accessibilityLabel` / `aria-label`. */
43
+ label?: TextMatch;
44
+ /** `accessibilityRole` / `role`. */
45
+ role?: string;
46
+ /**
47
+ * A semantic type (`'button'`, `'input'`, ... see SEMANTIC_TYPES), a host component type
48
+ * (`'RCTView'`, `'div'`) or the display name of a component that renders the element (`'Pressable'`).
49
+ */
50
+ type?: string;
51
+ /** Some descendant matches this matcher (Detox `withDescendant`). */
52
+ has?: Matcher;
53
+ /** The element itself does NOT match this matcher (its own fields, `has` and `not`). */
54
+ not?: Matcher;
55
+ /** Restrict the search to descendants of the (single) element matched by this matcher. */
56
+ within?: Matcher;
57
+ /** Pick the n-th match (0-based, in render order) when several elements match. */
58
+ index?: number;
59
+ }
@@ -0,0 +1,55 @@
1
+ import type { AgentEventName, AgentEvents } from './events.js';
2
+ import type { QuiescoErrorObject } from './errors.js';
3
+ import type { JsonValue } from './json.js';
4
+ import type { AgentMethods, HostMethods } from './methods.js';
5
+
6
+ /** JSON-RPC 2.0 envelope types (https://www.jsonrpc.org/specification). */
7
+ export type RequestId = number | string;
8
+
9
+ export interface JsonRpcRequest<M extends string = string, P = unknown> {
10
+ jsonrpc: '2.0';
11
+ id: RequestId;
12
+ method: M;
13
+ params: P;
14
+ }
15
+
16
+ export interface JsonRpcNotification<M extends string = string, P = unknown> {
17
+ jsonrpc: '2.0';
18
+ method: M;
19
+ params: P;
20
+ }
21
+
22
+ export interface JsonRpcSuccess<R = unknown> {
23
+ jsonrpc: '2.0';
24
+ id: RequestId;
25
+ result: R;
26
+ }
27
+
28
+ export interface JsonRpcErrorObject {
29
+ code: number;
30
+ message: string;
31
+ data?: JsonValue;
32
+ }
33
+
34
+ export interface JsonRpcFailure {
35
+ jsonrpc: '2.0';
36
+ id: RequestId | null;
37
+ error: JsonRpcErrorObject | QuiescoErrorObject;
38
+ }
39
+
40
+ export type JsonRpcResponse<R = unknown> = JsonRpcSuccess<R> | JsonRpcFailure;
41
+
42
+ /** Typed request for a given method table. */
43
+ export type RequestFor<T extends { [K in keyof T]: { params: unknown } }, K extends keyof T & string = keyof T & string> = {
44
+ [M in K]: JsonRpcRequest<M, T[M]['params']>;
45
+ }[K];
46
+
47
+ export type AgentRequest = RequestFor<AgentMethods>;
48
+ export type HostRequest = RequestFor<HostMethods>;
49
+
50
+ export type AgentEvent = {
51
+ [E in AgentEventName]: JsonRpcNotification<E, AgentEvents[E]>;
52
+ }[AgentEventName];
53
+
54
+ /** Every message that can travel over the socket. */
55
+ export type WireMessage = JsonRpcRequest | JsonRpcNotification | JsonRpcResponse;