@react-native-harness/ui 1.0.0-alpha.23 → 1.0.0-alpha.25

package/src/screen.ts

@@ -1,11 +1,18 @@
-import NativeHarnessUI, { type ViewInfo } from './NativeHarnessUI.js';
+import { type ViewInfo, type BoundingBox } from './types.js';
 import { waitFor } from '@react-native-harness/runtime';
+import HarnessUI from './harness.js';
 
 /**
- * Represents an element found on screen with its position and dimensions.
- * This can be used with userEvent.press() to interact with the element.
+ * Represents an element found on screen.
+ * This is an opaque reference that can be used with userEvent or screenshot.
  */
-export type ElementReference = ViewInfo;
+export type ElementReference = {
+  readonly nativeId: string;
+};
+
+const wrapElement = (viewInfo: ViewInfo): ElementReference => ({
+  nativeId: viewInfo.nativeId,
+});
 
 /**
  * Screenshot result containing PNG image data.
@@ -69,54 +76,57 @@ export type Screen = {
   queryAllByAccessibilityLabel: (label: string) => ElementReference[];
 
   /**
-   * Captures a screenshot of the entire app window or a specific element.
-   * @param element Optional element reference to capture. If not provided, captures the entire window.
+   * Captures a screenshot of the entire app window, a specific element, or a region.
+   * @param target Optional element reference or bounding box to capture. If not provided, captures the entire window.
    * @returns Promise resolving to ScreenshotResult with PNG data, or null if capture fails.
    */
-  screenshot: (element?: ElementReference) => Promise<ScreenshotResult | null>;
+  screenshot: (
+    target?: ElementReference | BoundingBox
+  ) => Promise<ScreenshotResult | null>;
 };
 
 const createScreen = (): Screen => {
   return {
     findByTestId: async (testId: string): Promise<ElementReference> => {
       return waitFor(() => {
-        const result = NativeHarnessUI.queryByTestId(testId);
+        const result = HarnessUI.queryByTestId(testId);
         if (!result) {
           throw new Error(`Unable to find element with testID: ${testId}`);
         }
-        return result;
+        return wrapElement(result);
       });
     },
 
     findAllByTestId: async (testId: string): Promise<ElementReference[]> => {
       return waitFor(() => {
-        const results = NativeHarnessUI.queryAllByTestId(testId);
+        const results = HarnessUI.queryAllByTestId(testId);
         if (results.length === 0) {
           throw new Error(`Unable to find any elements with testID: ${testId}`);
         }
-        return results;
+        return results.map(wrapElement);
       });
     },
 
     queryByTestId: (testId: string): ElementReference | null => {
-      return NativeHarnessUI.queryByTestId(testId);
+      const result = HarnessUI.queryByTestId(testId);
+      return result ? wrapElement(result) : null;
     },
 
     queryAllByTestId: (testId: string): ElementReference[] => {
-      return NativeHarnessUI.queryAllByTestId(testId);
+      return HarnessUI.queryAllByTestId(testId).map(wrapElement);
     },
 
     findByAccessibilityLabel: async (
       label: string
     ): Promise<ElementReference> => {
       return waitFor(() => {
-        const result = NativeHarnessUI.queryByAccessibilityLabel(label);
+        const result = HarnessUI.queryByAccessibilityLabel(label);
         if (!result) {
           throw new Error(
             `Unable to find element with accessibility label: ${label}`
           );
         }
-        return result;
+        return wrapElement(result);
       });
     },
 
@@ -124,37 +134,59 @@ const createScreen = (): Screen => {
       label: string
     ): Promise<ElementReference[]> => {
       return waitFor(() => {
-        const results = NativeHarnessUI.queryAllByAccessibilityLabel(label);
+        const results = HarnessUI.queryAllByAccessibilityLabel(label);
         if (results.length === 0) {
           throw new Error(
             `Unable to find any elements with accessibility label: ${label}`
           );
         }
-        return results;
+        return results.map(wrapElement);
       });
     },
 
     queryByAccessibilityLabel: (label: string): ElementReference | null => {
-      return NativeHarnessUI.queryByAccessibilityLabel(label);
+      const result = HarnessUI.queryByAccessibilityLabel(label);
+      return result ? wrapElement(result) : null;
     },
 
     queryAllByAccessibilityLabel: (label: string): ElementReference[] => {
-      return NativeHarnessUI.queryAllByAccessibilityLabel(label);
+      return HarnessUI.queryAllByAccessibilityLabel(label).map(wrapElement);
     },
 
     screenshot: async (
-      element?: ElementReference
+      target?: ElementReference | BoundingBox
     ): Promise<ScreenshotResult | null> => {
-      const bounds = element ?? null;
-      const base64String = await NativeHarnessUI.captureScreenshot(bounds);
+      let captureBounds: ViewInfo | null = null;
+      let targetWidth = 0;
+      let targetHeight = 0;
+
+      if (target) {
+        if ('nativeId' in target) {
+          // ElementReference
+          captureBounds = {
+            nativeId: target.nativeId,
+            x: 0,
+            y: 0,
+            width: 0,
+            height: 0,
+          };
+        } else {
+          // BoundingBox
+          captureBounds = {
+            nativeId: '',
+            ...target,
+          };
+          targetWidth = target.width;
+          targetHeight = target.height;
+        }
+      }
+
+      const base64String = await HarnessUI.captureScreenshot(captureBounds);
 
       if (!base64String) {
         return null;
       }
 
-      const width = element?.width ?? 0;
-      const height = element?.height ?? 0;
-
       // Decode Base64 string to Uint8Array
       const binaryString = atob(base64String);
       const len = binaryString.length;
@@ -163,10 +195,15 @@ const createScreen = (): Screen => {
         bytes[i] = binaryString.charCodeAt(i);
       }
 
+      // If we captured by nativeId, we might not know the width/height beforehand in JS.
+      // But the native side returns the actual captured PNG.
+      // Ideally we'd get the size from the native side, but currently the bridge doesn't return it.
+      // For now we use the provided target size or 0.
+
       return {
         data: bytes,
-        width,
-        height,
+        width: targetWidth,
+        height: targetHeight,
       };
     },
   };

package/src/types.ts

@@ -0,0 +1,54 @@
+import type { ViewInfo } from "./NativeHarnessUI.js";
+
+export type { ViewInfo, BoundingBox } from "./NativeHarnessUI.js";
+
+export interface HarnessUIModule {
+  /**
+   * Simulates a native press on a view identified by nativeId, or at coordinates if nativeId is empty.
+   * Returns a promise that resolves when the press action is complete.
+   */
+  simulatePress(nativeId: string, x: number, y: number): Promise<void>;
+
+  /**
+   * Finds a view by its testID (accessibilityIdentifier on iOS, tag on Android).
+   * Returns null if no view is found.
+   */
+  queryByTestId(testId: string): ViewInfo | null;
+
+  /**
+   * Finds all views by testID (accessibilityIdentifier on iOS, tag on Android).
+   * Returns an empty array if no views are found.
+   */
+  queryAllByTestId(testId: string): ViewInfo[];
+
+  /**
+   * Finds a view by its accessibility label.
+   * Returns null if no view is found.
+   */
+  queryByAccessibilityLabel(label: string): ViewInfo | null;
+
+  /**
+   * Finds all views by accessibility label.
+   * Returns an empty array if no views are found.
+   */
+  queryAllByAccessibilityLabel(label: string): ViewInfo[];
+
+  /**
+   * Captures a screenshot of the app UI.
+   * @param bounds Optional bounds to capture a specific region. Pass null to capture the entire window.
+   * @returns Promise resolving to Base64 encoded string containing PNG data, or null on failure.
+   */
+  captureScreenshot(bounds: ViewInfo | null): Promise<string | null>;
+
+  /**
+   * Types a single character into the currently focused text input.
+   * If no text input is focused, this is a no-op.
+   */
+  typeChar(character: string): Promise<void>;
+
+  /**
+   * Blurs (resigns first responder from) the currently focused element.
+   * Optionally triggers submitEditing event before blur.
+   */
+  blur(options: { submitEditing?: boolean }): Promise<void>;
+}

package/src/userEvent.ts

@@ -1,4 +1,4 @@
-import NativeHarnessUI from './NativeHarnessUI.js';
+import HarnessUI from './harness.js';
 import type { ElementReference } from './screen.js';
 
 /**
@@ -63,16 +63,15 @@ export type UserEvent = {
 const createUserEvent = (): UserEvent => {
   return {
     press: async (element: ElementReference): Promise<void> => {
-      // Calculate center point of the element
-      const centerX = element.x + element.width / 2;
-      const centerY = element.y + element.height / 2;
-      await NativeHarnessUI.simulatePress(centerX, centerY);
+      // We pass 0, 0 as coordinates when nativeId is provided.
+      // Native side will resolve the view and calculate the center.
+      await HarnessUI.simulatePress(element.nativeId, 0, 0);
       // Flush pending events to ensure onPress and other callbacks are processed
       await flushEvents();
     },
 
     pressAt: async (x: number, y: number): Promise<void> => {
-      await NativeHarnessUI.simulatePress(x, y);
+      await HarnessUI.simulatePress('', x, y);
       // Flush pending events to ensure onPress and other callbacks are processed
       await flushEvents();
     },
@@ -87,32 +86,24 @@ const createUserEvent = (): UserEvent => {
       }
     ): Promise<void> => {
       // Press to focus the element (triggers pressIn/pressOut unless skipPress is true)
-      // Note: Currently we always press to focus, the skipPress option would need
-      // additional implementation in simulatePress to avoid firing press events
       if (!options?.skipPress) {
-        // Calculate center point of the element
-        const centerX = element.x + element.width / 2;
-        const centerY = element.y + element.height / 2;
-        await NativeHarnessUI.simulatePress(centerX, centerY);
+        await HarnessUI.simulatePress(element.nativeId, 0, 0);
         await flushEvents();
       } else {
-        // Still need to press to focus, but ideally without press events
-        // For now, we press anyway - future enhancement could add a focusOnly method
-        const centerX = element.x + element.width / 2;
-        const centerY = element.y + element.height / 2;
-        await NativeHarnessUI.simulatePress(centerX, centerY);
+        // Still need to press to focus
+        await HarnessUI.simulatePress(element.nativeId, 0, 0);
         await flushEvents();
       }
 
       // Type each character one by one
       for (const char of text) {
-        await NativeHarnessUI.typeChar(char);
+        await HarnessUI.typeChar(char);
         await flushEvents(); // Let onChangeText fire
       }
 
       // Blur (triggers endEditing and blur unless skipBlur)
       if (!options?.skipBlur) {
-        await NativeHarnessUI.blur({
+        await HarnessUI.blur({
           submitEditing: options?.submitEditing ?? false,
         });
         await flushEvents();