@react-native-harness/ui 1.0.0-alpha.22

package/ios/ViewQueryHelper.mm

@@ -0,0 +1,187 @@
+#import "ViewQueryHelper.h"
+
+// =============================================================================
+// ViewQueryResult Implementation
+// =============================================================================
+
+@implementation ViewQueryResult
+
+- (NSDictionary *)toDictionary {
+    return @{
+        @"x": @(self.x),
+        @"y": @(self.y),
+        @"width": @(self.width),
+        @"height": @(self.height)
+    };
+}
+
+@end
+
+// =============================================================================
+// ViewQueryHelper Implementation
+// =============================================================================
+
+@implementation ViewQueryHelper
+
+#pragma mark - Window Access
+
++ (nullable UIWindow *)getActiveWindow {
+    UIWindow *window = nil;
+    if (@available(iOS 13.0, *)) {
+        for (UIWindowScene *scene in [UIApplication sharedApplication].connectedScenes) {
+            if (scene.activationState == UISceneActivationStateForegroundActive) {
+                for (UIWindow *w in scene.windows) {
+                    if (w.isKeyWindow) {
+                        window = w;
+                        break;
+                    }
+                }
+                if (!window) {
+                    window = scene.windows.firstObject;
+                }
+                break;
+            }
+        }
+    } else {
+        window = [UIApplication sharedApplication].keyWindow;
+    }
+    return window;
+}
+
+#pragma mark - View Matching
+
+/**
+ * Checks if a view matches the given query criteria.
+ * Add new query type matching logic here.
+ */
++ (BOOL)view:(UIView *)view matchesQueryType:(ViewQueryType)queryType value:(NSString *)value {
+    switch (queryType) {
+        case ViewQueryTypeTestId:
+            return [view.accessibilityIdentifier isEqualToString:value];
+
+        case ViewQueryTypeAccessibilityLabel:
+            return [view.accessibilityLabel isEqualToString:value];
+
+        // Add new query types here:
+        // case ViewQueryTypeNewType:
+        //     return [view.someProperty isEqualToString:value];
+    }
+    return NO;
+}
+
+#pragma mark - View Traversal
+
+/**
+ * Recursively finds the first view matching the query criteria.
+ */
++ (nullable UIView *)findViewInView:(UIView *)view
+                          queryType:(ViewQueryType)queryType
+                              value:(NSString *)value {
+    if ([self view:view matchesQueryType:queryType value:value]) {
+        return view;
+    }
+
+    for (UIView *subview in view.subviews) {
+        UIView *found = [self findViewInView:subview queryType:queryType value:value];
+        if (found) {
+            return found;
+        }
+    }
+    return nil;
+}
+
+/**
+ * Recursively finds all views matching the query criteria.
+ */
++ (void)findAllViewsInView:(UIView *)view
+                 queryType:(ViewQueryType)queryType
+                     value:(NSString *)value
+                   results:(NSMutableArray<UIView *> *)results {
+    if ([self view:view matchesQueryType:queryType value:value]) {
+        [results addObject:view];
+    }
+
+    for (UIView *subview in view.subviews) {
+        [self findAllViewsInView:subview queryType:queryType value:value results:results];
+    }
+}
+
+#pragma mark - Result Conversion
+
+/**
+ * Converts a UIView to a ViewQueryResult with screen coordinates.
+ */
++ (ViewQueryResult *)resultFromView:(UIView *)view window:(UIWindow *)window {
+    CGRect frameInWindow = [view convertRect:view.bounds toView:window];
+
+    ViewQueryResult *result = [[ViewQueryResult alloc] init];
+    result.x = frameInWindow.origin.x;
+    result.y = frameInWindow.origin.y;
+    result.width = frameInWindow.size.width;
+    result.height = frameInWindow.size.height;
+    return result;
+}
+
+#pragma mark - Public Query API
+
++ (nullable ViewQueryResult *)queryWithType:(ViewQueryType)queryType value:(NSString *)value {
+    UIWindow *window = [self getActiveWindow];
+    if (!window) {
+        return nil;
+    }
+
+    UIView *found = [self findViewInView:window queryType:queryType value:value];
+    if (!found) {
+        return nil;
+    }
+
+    return [self resultFromView:found window:window];
+}
+
++ (NSArray<ViewQueryResult *> *)queryAllWithType:(ViewQueryType)queryType value:(NSString *)value {
+    UIWindow *window = [self getActiveWindow];
+    if (!window) {
+        return @[];
+    }
+
+    NSMutableArray<UIView *> *views = [NSMutableArray array];
+    [self findAllViewsInView:window queryType:queryType value:value results:views];
+
+    NSMutableArray<ViewQueryResult *> *results = [NSMutableArray arrayWithCapacity:views.count];
+    for (UIView *view in views) {
+        [results addObject:[self resultFromView:view window:window]];
+    }
+    return results;
+}
+
+#pragma mark - Screenshot Capture
+
++ (nullable NSData *)captureScreenshotWithBounds:(CGRect)bounds {
+    UIWindow *window = [self getActiveWindow];
+    if (!window) {
+        return nil;
+    }
+
+    // Determine capture rect
+    CGRect captureRect = CGRectIsNull(bounds) ? window.bounds : bounds;
+
+    // Use UIGraphicsImageRenderer for modern, efficient rendering
+    UIGraphicsImageRendererFormat *format = [[UIGraphicsImageRendererFormat alloc] init];
+    format.scale = [UIScreen mainScreen].scale;
+    format.opaque = YES;
+
+    UIGraphicsImageRenderer *renderer = [[UIGraphicsImageRenderer alloc] initWithSize:captureRect.size format:format];
+
+    UIImage *image = [renderer imageWithActions:^(UIGraphicsImageRendererContext *context) {
+        // Translate to capture the correct region
+        CGContextTranslateCTM(context.CGContext, -captureRect.origin.x, -captureRect.origin.y);
+
+        // Draw the window hierarchy
+        [window drawViewHierarchyInRect:window.bounds afterScreenUpdates:YES];
+    }];
+
+    // Convert to PNG
+    return UIImagePNGRepresentation(image);
+}
+
+@end

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@react-native-harness/ui",
+  "description": "Native UI testing module for React Native Harness.",
+  "version": "1.0.0-alpha.22",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "android",
+    "ios",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react-native": "*"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0",
+    "@react-native-harness/runtime": "1.0.0-alpha.22"
+  },
+  "devDependencies": {
+    "react-native": "*"
+  },
+  "codegenConfig": {
+    "name": "HarnessUISpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.harnessui"
+    }
+  },
+  "author": {
+    "name": "Szymon Chmal",
+    "email": "szymon.chmal@callstack.com"
+  },
+  "homepage": "https://github.com/callstackincubator/react-native-harness",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/callstackincubator/react-native-harness.git"
+  },
+  "license": "MIT"
+}

package/src/NativeHarnessUI.ts

@@ -0,0 +1,66 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+/**
+ * Represents the position and dimensions of a view in screen coordinates (points/dp).
+ */
+export interface ViewInfo {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+interface Spec extends TurboModule {
+  /**
+   * Simulates a native press at the specified screen coordinates.
+   * Returns a promise that resolves when the press action is complete.
+   */
+  simulatePress(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>;
+}
+
+export type HarnessUIModule = Spec;
+
+export default TurboModuleRegistry.getEnforcing<Spec>('HarnessUI');

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @react-native-harness/ui
+ *
+ * Native UI testing module for React Native Harness.
+ * Provides view queries and touch simulation.
+ *
+ * This module is automatically excluded from release builds
+ * and only available in debug builds.
+ */
+
+export {
+  screen,
+  type Screen,
+  type ElementReference,
+  type ScreenshotResult,
+} from './screen.js';
+export { userEvent, type UserEvent } from './userEvent.js';
+export type { ViewInfo } from './NativeHarnessUI.js';

package/src/screen.ts

@@ -0,0 +1,175 @@
+import NativeHarnessUI, { type ViewInfo } from './NativeHarnessUI.js';
+import { waitFor } from '@react-native-harness/runtime';
+
+/**
+ * Represents an element found on screen with its position and dimensions.
+ * This can be used with userEvent.press() to interact with the element.
+ */
+export type ElementReference = ViewInfo;
+
+/**
+ * Screenshot result containing PNG image data.
+ */
+export interface ScreenshotResult {
+  /** PNG image data as Uint8Array (ArrayBuffer view) */
+  data: Uint8Array;
+  /** Width of the captured image in logical pixels (points/dp) */
+  width: number;
+  /** Height of the captured image in logical pixels (points/dp) */
+  height: number;
+}
+
+export type Screen = {
+  /**
+   * Finds an element by its testID (accessibilityIdentifier on iOS, tag on Android).
+   * @throws Error if no element is found with the given testID.
+   */
+  findByTestId: (testId: string) => Promise<ElementReference>;
+
+  /**
+   * Finds all elements by testID (accessibilityIdentifier on iOS, tag on Android).
+   * @throws Error if no elements are found with the given testID.
+   */
+  findAllByTestId: (testId: string) => Promise<ElementReference[]>;
+
+  /**
+   * Queries for an element by its testID without throwing.
+   * Returns null if no element is found.
+   */
+  queryByTestId: (testId: string) => ElementReference | null;
+
+  /**
+   * Queries for all elements by testID without throwing.
+   * Returns an empty array if no elements are found.
+   */
+  queryAllByTestId: (testId: string) => ElementReference[];
+
+  /**
+   * Finds an element by its accessibility label.
+   * @throws Error if no element is found with the given label.
+   */
+  findByAccessibilityLabel: (label: string) => Promise<ElementReference>;
+
+  /**
+   * Finds all elements by accessibility label.
+   * @throws Error if no elements are found with the given label.
+   */
+  findAllByAccessibilityLabel: (label: string) => Promise<ElementReference[]>;
+
+  /**
+   * Queries for an element by its accessibility label without throwing.
+   * Returns null if no element is found.
+   */
+  queryByAccessibilityLabel: (label: string) => ElementReference | null;
+
+  /**
+   * Queries for all elements by accessibility label without throwing.
+   * Returns an empty array if no elements are found.
+   */
+  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.
+   * @returns Promise resolving to ScreenshotResult with PNG data, or null if capture fails.
+   */
+  screenshot: (element?: ElementReference) => Promise<ScreenshotResult | null>;
+};
+
+const createScreen = (): Screen => {
+  return {
+    findByTestId: async (testId: string): Promise<ElementReference> => {
+      return waitFor(() => {
+        const result = NativeHarnessUI.queryByTestId(testId);
+        if (!result) {
+          throw new Error(`Unable to find element with testID: ${testId}`);
+        }
+        return result;
+      });
+    },
+
+    findAllByTestId: async (testId: string): Promise<ElementReference[]> => {
+      return waitFor(() => {
+        const results = NativeHarnessUI.queryAllByTestId(testId);
+        if (results.length === 0) {
+          throw new Error(`Unable to find any elements with testID: ${testId}`);
+        }
+        return results;
+      });
+    },
+
+    queryByTestId: (testId: string): ElementReference | null => {
+      return NativeHarnessUI.queryByTestId(testId);
+    },
+
+    queryAllByTestId: (testId: string): ElementReference[] => {
+      return NativeHarnessUI.queryAllByTestId(testId);
+    },
+
+    findByAccessibilityLabel: async (
+      label: string
+    ): Promise<ElementReference> => {
+      return waitFor(() => {
+        const result = NativeHarnessUI.queryByAccessibilityLabel(label);
+        if (!result) {
+          throw new Error(
+            `Unable to find element with accessibility label: ${label}`
+          );
+        }
+        return result;
+      });
+    },
+
+    findAllByAccessibilityLabel: async (
+      label: string
+    ): Promise<ElementReference[]> => {
+      return waitFor(() => {
+        const results = NativeHarnessUI.queryAllByAccessibilityLabel(label);
+        if (results.length === 0) {
+          throw new Error(
+            `Unable to find any elements with accessibility label: ${label}`
+          );
+        }
+        return results;
+      });
+    },
+
+    queryByAccessibilityLabel: (label: string): ElementReference | null => {
+      return NativeHarnessUI.queryByAccessibilityLabel(label);
+    },
+
+    queryAllByAccessibilityLabel: (label: string): ElementReference[] => {
+      return NativeHarnessUI.queryAllByAccessibilityLabel(label);
+    },
+
+    screenshot: async (
+      element?: ElementReference
+    ): Promise<ScreenshotResult | null> => {
+      const bounds = element ?? null;
+      const base64String = await NativeHarnessUI.captureScreenshot(bounds);
+
+      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;
+      const bytes = new Uint8Array(len);
+      for (let i = 0; i < len; i++) {
+        bytes[i] = binaryString.charCodeAt(i);
+      }
+
+      return {
+        data: bytes,
+        width,
+        height,
+      };
+    },
+  };
+};
+
+export const screen = createScreen();

package/src/userEvent.ts

@@ -0,0 +1,124 @@
+import NativeHarnessUI from './NativeHarnessUI.js';
+import type { ElementReference } from './screen.js';
+
+/**
+ * Flushes pending events on the JS event loop.
+ * This ensures that any events triggered by native code (like onPress callbacks)
+ * are processed before we continue.
+ *
+ * Uses requestAnimationFrame to wait for the next frame render, ensuring React
+ * has had time to process events and commit state updates. Includes a small
+ * timeout buffer for slow devices.
+ */
+const flushEvents = (): Promise<void> => {
+  return new Promise((resolve) => {
+    // Wait for the next frame - ensures React has processed events and rendered
+    requestAnimationFrame(() => {
+      // Wait for another frame to handle any cascading updates
+      requestAnimationFrame(() => {
+        // Small timeout buffer for slow devices to complete any async processing
+        setTimeout(resolve, 16);
+      });
+    });
+  });
+};
+
+export type UserEvent = {
+  /**
+   * Simulates a press on the given element.
+   * The press occurs at the center of the element's bounds.
+   * Returns a promise that resolves when the press is complete.
+   */
+  press: (element: ElementReference) => Promise<void>;
+
+  /**
+   * Simulates a press at the specified screen coordinates.
+   * Returns a promise that resolves when the press is complete.
+   */
+  pressAt: (x: number, y: number) => Promise<void>;
+
+  /**
+   * Simulates typing text into a text input element.
+   * This helper focuses the element by tapping it, types text one character at a time,
+   * and then blurs the element (unless skipBlur is true).
+   *
+   * @param element - The element to type into (should be a TextInput)
+   * @param text - The text to type
+   * @param options - Optional configuration
+   * @param options.skipPress - If true, pressIn and pressOut events will not be triggered
+   * @param options.skipBlur - If true, endEditing and blur events will not be triggered when typing is complete
+   * @param options.submitEditing - If true, submitEditing event will be triggered after typing the text
+   */
+  type: (
+    element: ElementReference,
+    text: string,
+    options?: {
+      skipPress?: boolean;
+      skipBlur?: boolean;
+      submitEditing?: boolean;
+    }
+  ) => Promise<void>;
+};
+
+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);
+      // 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);
+      // Flush pending events to ensure onPress and other callbacks are processed
+      await flushEvents();
+    },
+
+    type: async (
+      element: ElementReference,
+      text: string,
+      options?: {
+        skipPress?: boolean;
+        skipBlur?: boolean;
+        submitEditing?: boolean;
+      }
+    ): 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 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);
+        await flushEvents();
+      }
+
+      // Type each character one by one
+      for (const char of text) {
+        await NativeHarnessUI.typeChar(char);
+        await flushEvents(); // Let onChangeText fire
+      }
+
+      // Blur (triggers endEditing and blur unless skipBlur)
+      if (!options?.skipBlur) {
+        await NativeHarnessUI.blur({
+          submitEditing: options?.submitEditing ?? false,
+        });
+        await flushEvents();
+      }
+    },
+  };
+};
+
+export const userEvent = createUserEvent();