@reactiive/ennio 0.0.1

package/react-native.config.js

@@ -0,0 +1,14 @@
+/**
+ * Disable React Native autolinking for ennio
+ *
+ * The ennio-expo-plugin controls whether native code is included.
+ * This allows conditional inclusion based on build type (dev/production).
+ */
+module.exports = {
+  dependency: {
+    platforms: {
+      ios: null, // Disable iOS autolinking
+      android: null, // Disable Android autolinking
+    },
+  },
+};

package/src/Ennio.nitro.ts

@@ -0,0 +1,363 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+
+/**
+ * Layout metrics for a UI element
+ */
+export interface LayoutMetrics {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  screenX: number;
+  screenY: number;
+}
+
+/**
+ * Information about a found element
+ */
+export interface ElementInfo {
+  testID: string;
+  type: string;
+  text?: string;
+  accessible: boolean;
+  enabled: boolean;
+  layout: LayoutMetrics;
+}
+
+/**
+ * Extended element info with additional state properties
+ */
+export interface ExtendedElementInfo extends ElementInfo {
+  checked: boolean;
+  focused: boolean;
+  selected: boolean;
+}
+
+/**
+ * Text matching mode for text selectors
+ */
+export type TextMatchMode = 'exact' | 'contains' | 'regex' | 'startsWith' | 'endsWith';
+
+/**
+ * Text matcher configuration
+ */
+export interface TextMatcher {
+  pattern: string;
+  mode?: TextMatchMode;
+}
+
+/**
+ * Point for coordinate-based selection
+ */
+export interface Point {
+  x: number;
+  y: number;
+  isPercentage?: boolean;
+}
+
+/**
+ * Trait types for trait-based selection
+ */
+export type Trait = 'text' | 'long-text' | 'square';
+
+/**
+ * Direction for scroll / swipe gestures
+ */
+export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * Selector - Full Maestro selector parity
+ *
+ * Supports:
+ * - Primary: id, text, index, point
+ * - State: enabled, checked, focused, selected
+ * - Spatial: below, above, leftOf, rightOf
+ * - Hierarchical: containsChild, childOf, containsDescendants
+ * - Dimensions: width, height, tolerance
+ * - Traits: text, long-text, square
+ */
+export interface Selector {
+  // ============================================
+  // Primary Selectors
+  // ============================================
+
+  /**
+   * Match by testID (O(1) lookup when used alone)
+   */
+  id?: string;
+
+  /**
+   * Match by text content (string for exact match, or TextMatcher for advanced)
+   */
+  text?: string | TextMatcher;
+
+  /**
+   * Return the nth matching element (0-indexed)
+   */
+  index?: number;
+
+  /**
+   * Select element at specific coordinates
+   * String format: "50%,50%" or "100,200"
+   */
+  point?: Point | string;
+
+  // ============================================
+  // State Selectors
+  // ============================================
+
+  /**
+   * Match by enabled state
+   */
+  enabled?: boolean;
+
+  /**
+   * Match by checked state (checkboxes, switches)
+   */
+  checked?: boolean;
+
+  /**
+   * Match by focused state
+   */
+  focused?: boolean;
+
+  /**
+   * Match by selected state
+   */
+  selected?: boolean;
+
+  // ============================================
+  // Spatial Selectors (relative positioning)
+  // ============================================
+
+  /**
+   * Match elements below the reference element
+   */
+  below?: Selector;
+
+  /**
+   * Match elements above the reference element
+   */
+  above?: Selector;
+
+  /**
+   * Match elements to the left of the reference element
+   */
+  leftOf?: Selector;
+
+  /**
+   * Match elements to the right of the reference element
+   */
+  rightOf?: Selector;
+
+  // ============================================
+  // Hierarchical Selectors
+  // ============================================
+
+  /**
+   * Match elements that contain a direct child matching criteria
+   */
+  containsChild?: Selector;
+
+  /**
+   * Match elements that are children of an element matching criteria
+   */
+  childOf?: Selector;
+
+  /**
+   * Match elements that contain all descendants matching each criteria
+   */
+  containsDescendants?: Selector[];
+
+  // ============================================
+  // Dimension Selectors
+  // ============================================
+
+  /**
+   * Match by width (in points)
+   */
+  width?: number;
+
+  /**
+   * Match by height (in points)
+   */
+  height?: number;
+
+  /**
+   * Tolerance for width/height matching (default: 0)
+   */
+  tolerance?: number;
+
+  // ============================================
+  // Trait Selectors
+  // ============================================
+
+  /**
+   * Match elements with specified traits
+   */
+  traits?: Trait[];
+}
+
+/**
+ * Ennio HybridObject - Direct Fabric shadow tree access for E2E testing
+ */
+export interface Ennio extends HybridObject<{ ios: 'c++'; android: 'c++' }> {
+  // ============================================
+  // Element Queries
+  // ============================================
+
+  /**
+   * Check if an element with the given testID exists in the tree
+   * @param testID - The testID prop value to search for
+   */
+  exists(testID: string): boolean;
+
+  /**
+   * Check if an element is visible on screen
+   * Considers: opacity, display, pointerEvents, and viewport bounds
+   * @param testID - The testID prop value
+   */
+  isVisible(testID: string): boolean;
+
+  /**
+   * Get text content of an element
+   * @param testID - The testID prop value
+   * @returns Text content if available, null otherwise
+   */
+  getText(testID: string): string | null;
+
+  // ============================================
+  // Synchronization
+  // ============================================
+
+  /**
+   * Wait for the shadow tree to settle (no pending updates)
+   * @param timeoutMs - Maximum time to wait in milliseconds
+   * @returns true if settled within timeout
+   */
+  waitForIdle(timeoutMs: number): boolean;
+
+  /**
+   * Force a synchronization point - ensures all pending JS and native updates are processed
+   */
+  synchronize(): void;
+
+  /**
+   * Block until React fires the next onCommitFiberRoot, or until maxMs
+   * elapses. Used by the CLI to wake early from blind settle sleeps —
+   * cap is the safety floor, commit signal is the early-wake.
+   * @param maxMs - Maximum time to wait in milliseconds
+   * @returns true if a commit fired within maxMs, false on timeout
+   */
+  waitForNextCommit(maxMs: number): boolean;
+
+  // ============================================
+  // Selector-based Queries (Full Maestro Parity)
+  // ============================================
+
+  /**
+   * Find an element using a selector (JSON string)
+   * @param selectorJson - JSON-encoded Selector object
+   * @returns ExtendedElementInfo if found, null otherwise
+   */
+  findBySelector(selectorJson: string): ExtendedElementInfo | null;
+
+  /**
+   * Find all elements matching a selector (JSON string)
+   * @param selectorJson - JSON-encoded Selector object
+   * @returns Array of ExtendedElementInfo
+   */
+  findAllBySelector(selectorJson: string): ExtendedElementInfo[];
+
+  /**
+   * Check if an element matching the selector exists
+   * @param selectorJson - JSON-encoded Selector object
+   */
+  existsBySelector(selectorJson: string): boolean;
+
+  /**
+   * Get text content of an element using a selector (JSON string)
+   * @param selectorJson - JSON-encoded Selector object
+   * @returns Text content if available, null otherwise
+   */
+  getTextBySelector(selectorJson: string): string | null;
+
+  /**
+   * Check if an element matching the selector is visible
+   * @param selectorJson - JSON-encoded Selector object
+   */
+  isVisibleBySelector(selectorJson: string): boolean;
+
+  // ============================================
+  // Alert/Modal Handling
+  // ============================================
+
+  /**
+   * Check if an alert is currently presented
+   */
+  isAlertPresent(): boolean;
+
+  /**
+   * Get the text content of the current alert (title + message)
+   */
+  getAlertText(): string;
+
+  /**
+   * Get the button titles of the current alert
+   */
+  getAlertButtons(): string[];
+
+  // ============================================
+  // In-app writes (no JSI invokeOnPress, no UITouch synth)
+  //
+  // CLI actuation goes through idb HID at measured coords — Maestro /
+  // XCUITest parity. These methods cover the scroll / keyboard / nav
+  // operations that idb can't model cleanly:
+  //   - scroll / scrollTo -> UIScrollView.setContentOffset
+  //   - swipeAtPoints     -> UITouch-loop pan (cross-view drags)
+  //   - back              -> UINavigationController.popViewController
+  //   - alerts            -> walk UIAlertController.actions
+  //   - hideKeyboard      -> [keyboardWindow firstResponder] resignFirstResponder
+  // ============================================
+
+  scroll(testID: string, direction: ScrollDirection, distance: number): boolean;
+  scrollTo(scrollViewTestID: string, elementTestID: string): boolean;
+
+  /**
+   * Synthesize a pan gesture from (x1,y1) to (x2,y2) over `durationMs`.
+   * If the start point hits a UIScrollView, takes the fast path
+   * (`setContentOffset:animated:NO` with the delta) — no UITouch tax.
+   * Otherwise drives a UITouchPhaseMoved loop for cross-view drags
+   * (sheet dismiss, page swipe, non-scrollable carousel pan).
+   * Coordinates are window-relative. Sim-only (UITouch private API).
+   */
+  swipeAtPoints(x1: number, y1: number, x2: number, y2: number, durationMs: number): boolean;
+
+  /**
+   * Synthesize a hardware key press by HID keycode against the current
+   * first responder when it conforms to UIKeyInput. Currently maps:
+   *   42 → deleteBackward (backspace)
+   *   40 → insertText("\n") (return)
+   *   44 → insertText(" ") (space)
+   * Returns false when no first responder accepts text input. Replaces
+   * idb's HID `pressKey` for in-app text fields.
+   */
+  pressHardwareKey(keyCode: number): boolean;
+
+  /**
+   * Drive a back navigation. Pops the top view controller of the
+   * current UINavigationController.
+   */
+  backGesture(): boolean;
+
+  hideKeyboard(): boolean;
+
+  // Alert writes (the matching reads — isAlertPresent, getAlertText,
+  // getAlertButtons — already exist above).
+  tapAlertButton(buttonText: string): boolean;
+  dismissAlert(): boolean;
+
+  // Pasteboard
+  copyToClipboard(text: string): boolean;
+  pasteFromClipboard(testID: string): boolean;
+}

package/src/cli/hid-daemon.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+Persistent HID injection daemon backed by the python idb client.
+
+The python `idb` CLI eats ~250 ms per invocation booting the
+interpreter + loading grpclib + building a gRPC channel — wasted
+work when the runner fires 30+ taps per flow. This daemon pays that
+cost once, then loops on stdin reading one-line commands and dispatches
+them to a long-lived `Client` instance. Each tap is just a gRPC RTT
+over the already-warm channel: ~3-8 ms.
+
+Wire protocol (line-delimited, both directions):
+
+  IN   tap <x> <y> <durationMs>
+  IN   swipe <x1> <y1> <x2> <y2> <durationMs>
+  IN   exit
+  OUT  ok                  — command completed
+  OUT  err <message>       — command failed; daemon stays alive
+
+The daemon discovers the companion socket from `IDB_COMPANION` env
+var or `/tmp/idb/<UDID>_companion.sock` if the parent passes a UDID
+positional. The CLI launches one daemon per booted target and keeps
+it alive for the whole `ennio test` session.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+
+from idb.common.types import Address, DomainSocketAddress
+from idb.grpc.client import Client
+
+# Silence idb's noisy info-level chatter — daemon stdout is the wire
+# protocol; any non-`ok` / `err` line would corrupt it.
+logging.basicConfig(level=logging.ERROR)
+
+
+async def main() -> None:
+    udid = sys.argv[1] if len(sys.argv) > 1 else os.environ.get("ENNIO_UDID")
+    if not udid:
+        print("err missing-udid", flush=True)
+        sys.exit(2)
+
+    sock_path = Path(f"/tmp/idb/{udid}_companion.sock")
+    if not sock_path.exists():
+        # No companion running yet — the CLI is expected to run
+        # `idb connect <UDID>` once before spawning the daemon. Bail
+        # loudly so the parent sees a startup failure.
+        print(f"err no-socket {sock_path}", flush=True)
+        sys.exit(3)
+
+    address: Address = DomainSocketAddress(path=str(sock_path))
+
+    # `Client.build` is an async context manager that owns the gRPC
+    # channel for the duration of the `async with` block. Hold it open
+    # for the whole daemon lifetime so per-call cost is just the RTT.
+    async with Client.build(address=address, logger=logging.getLogger("ennio")) as client:
+        # Signal readiness — parent CLI waits for this line before
+        # sending commands.
+        print("ready", flush=True)
+
+        # `sys.stdin.readline` is blocking; wrap in
+        # `run_in_executor` so the event loop stays responsive (idb's
+        # underlying grpclib streams need it).
+        loop = asyncio.get_event_loop()
+        while True:
+            line = await loop.run_in_executor(None, sys.stdin.readline)
+            if not line:
+                # Parent closed stdin — exit cleanly.
+                return
+            try:
+                await handle(client, line.strip())
+            except Exception as e:
+                # Per-call failures shouldn't kill the daemon; the
+                # parent CLI may retry, or fall back to spawning
+                # python idb. Log + continue.
+                print(f"err {type(e).__name__}: {e}", flush=True)
+
+
+async def handle(client: Client, line: str) -> None:
+    if not line:
+        return
+    parts = line.split()
+    if not parts:
+        return
+    op = parts[0]
+    # Validate arg counts up front so a malformed line returns a clean
+    # "err …" instead of crashing the daemon with IndexError (which the
+    # Node parent only sees as an unexpected EOF).
+    try:
+        if op == "tap":
+            # tap <x> <y> [durationMs]
+            if len(parts) < 3:
+                print("err tap-needs-x-y", flush=True)
+                return
+            x = float(parts[1])
+            y = float(parts[2])
+            dur_ms = float(parts[3]) if len(parts) > 3 else 80.0
+            await client.tap(x=x, y=y, duration=dur_ms / 1000.0)
+            print("ok", flush=True)
+        elif op == "swipe":
+            # swipe <x1> <y1> <x2> <y2> [durationMs]
+            if len(parts) < 5:
+                print("err swipe-needs-x1-y1-x2-y2", flush=True)
+                return
+            x1 = float(parts[1])
+            y1 = float(parts[2])
+            x2 = float(parts[3])
+            y2 = float(parts[4])
+            dur_ms = float(parts[5]) if len(parts) > 5 else 300.0
+            await client.swipe(
+                p_start=(x1, y1),
+                p_end=(x2, y2),
+                duration=dur_ms / 1000.0,
+            )
+            print("ok", flush=True)
+        elif op == "exit":
+            sys.exit(0)
+        else:
+            print(f"err unknown-op {op}", flush=True)
+    except ValueError as e:
+        # float() on non-numeric arg.
+        print(f"err bad-arg {e}", flush=True)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/src/index.ts

@@ -0,0 +1,72 @@
+import { NitroModules } from 'react-native-nitro-modules';
+import type {
+  Ennio,
+  ExtendedElementInfo,
+  LayoutMetrics,
+  Selector,
+  TextMatcher,
+  TextMatchMode,
+  Point,
+  Trait,
+  ScrollDirection,
+} from './Ennio.nitro';
+
+export type {
+  Ennio,
+  ExtendedElementInfo,
+  LayoutMetrics,
+  Selector,
+  TextMatcher,
+  TextMatchMode,
+  Point,
+  Trait,
+  ScrollDirection,
+};
+
+let _ennioModule: Ennio | null = null;
+let _initError: Error | null = null;
+
+/**
+ * Get the Ennio HybridObject instance. Auto-init happens at app start
+ * (EnnioAutoInit swizzles RCTHost.start) — this is just a stable
+ * handle for callers that want to introspect from JS.
+ */
+export function getEnnioModule(): Ennio | null {
+  if (_ennioModule) {
+    return _ennioModule;
+  }
+
+  if (_initError) {
+    return null;
+  }
+
+  try {
+    _ennioModule = NitroModules.createHybridObject<Ennio>('Ennio');
+    return _ennioModule;
+  } catch (error) {
+    _initError = error instanceof Error ? error : new Error(String(error));
+    if (__DEV__) {
+      console.warn('[Ennio] Native module not available:', _initError.message);
+      console.warn('[Ennio] E2E testing features will be disabled');
+    }
+    return null;
+  }
+}
+
+/**
+ * Returns true when the Ennio JSI surface is reachable. The runtime
+ * dispatch surface (`__ennioDispatch` + commit signal) is installed
+ * automatically by the pod's `+load` hook — this only exposes the
+ * Nitro module to JS callers that want to read state directly.
+ */
+export function isNativeModuleAvailable(): boolean {
+  return getEnnioModule() !== null;
+}
+
+// No JS-side bootstrap. `ennio` autolinks via Pod, and the iOS
+// `EnnioAutoInit` swizzle installs the JSI dispatch surface (commit
+// signal + `__ennioDispatch` host function) natively, on the JS
+// thread, the moment RCTHost finishes booting. The user's app never
+// imports this package; it lands purely through `npm install ennio`.
+// The external CLI drives the runtime via Hermes Inspector
+// (`Runtime.evaluate('__ennioDispatch(...)')`).