@react-native-harness/runtime 1.0.0-alpha.20 → 1.0.0-alpha.22

package/dist/index.js

@@ -1,4 +1,5 @@
-import './globals.d.ts';
+import './polyfills.js';
+import './globals.js';
 export { UI as ReactNativeHarness } from './ui/index.js';
 export * from './spy/index.js';
 export * from './expect/index.js';

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "@react-native-harness/runtime",
-  "version": "1.0.0-alpha.20",
+  "description": "The core test runtime that executes on React Native devices, providing Jest-compatible APIs (describe, it, expect) and managing test collection, execution, and result reporting in native environments.",
+  "version": "1.0.0-alpha.22",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "files": [
+    "src",
+    "lib",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -35,12 +44,21 @@
     "event-target-shim": "^6.0.2",
     "use-sync-external-store": "^1.6.0",
     "zustand": "^5.0.5",
-    "@react-native-harness/bridge": "1.0.0-alpha.20"
+    "@react-native-harness/bridge": "1.0.0-alpha.22"
   },
   "devDependencies": {
     "@types/chai": "^5.2.2",
     "react": "*",
     "react-native": "*"
   },
+  "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/bundler/errors.ts

@@ -20,7 +20,8 @@ export class BundlingFailedError extends Error {
     public readonly modulePath: string,
     public readonly reason: string
   ) {
-    super(`Bundling of ${modulePath} failed`);
+    const reasonMessage = JSON.parse(reason).message ?? reason;
+    super(`Bundling of ${modulePath} failed with error:\n\n${reasonMessage}\n`);
     this.name = 'BundlingFailedError';
   }
 }

package/src/client/factory.ts

@@ -14,6 +14,7 @@ import { getBundler, evaluateModule, Bundler } from '../bundler/index.js';
 import { markTestsAsSkippedByName } from '../filtering/index.js';
 import { setup } from '../render/setup.js';
 import { runSetupFiles } from './setup-files.js';
+import { setClient } from './store.js';
 
 export const getClient = async () => {
   const client = await getBridgeClient(getWSServer(), {
@@ -22,9 +23,11 @@ export const getClient = async () => {
     },
   });
 
+  setClient(client);
+
   client.rpc.$functions.runTests = async (
     path: string,
-    options: TestExecutionOptions = {}
+    options: TestExecutionOptions
   ) => {
     if (store.getState().status === 'running') {
       throw new Error('Already running tests');
@@ -84,7 +87,11 @@ export const getClient = async () => {
           )
         : collectionResult.testSuite;
 
-      const result = await runner.run(processedTestSuite, path);
+      const result = await runner.run({
+        testSuite: processedTestSuite,
+        testFilePath: path,
+        runner: options.runner,
+      });
       return result;
     } finally {
       collector?.dispose();

package/src/client/store.ts

@@ -0,0 +1,16 @@
+import type { BridgeClient } from '@react-native-harness/bridge/client';
+
+let clientInstance: BridgeClient | null = null;
+
+export const setClient = (client: BridgeClient): void => {
+  clientInstance = client;
+};
+
+export const getClientInstance = (): BridgeClient => {
+  if (!clientInstance) {
+    throw new Error(
+      'Bridge client not initialized. This should not happen in normal operation.'
+    );
+  }
+  return clientInstance;
+};

package/src/expect/expect.ts

@@ -0,0 +1,127 @@
+// This is adapted version of https://github.com/vitest-dev/vitest/blob/main/packages/vitest/src/integrations/chai/index.ts
+// Credits to Vitest team for the original implementation.
+
+import type { Assertion, ExpectStatic, MatcherState } from '@vitest/expect';
+import {
+  addCustomEqualityTesters,
+  ASYMMETRIC_MATCHERS_OBJECT,
+  customMatchers,
+  getState,
+  GLOBAL_EXPECT,
+  setState,
+} from '@vitest/expect';
+import * as chai from 'chai';
+
+// Setup additional matchers
+import './setup.js';
+import { toMatchImageSnapshot } from './matchers/toMatchImageSnapshot.js';
+
+export function createExpect(): ExpectStatic {
+  const expect = ((value: unknown, message?: string): Assertion => {
+    const { assertionCalls } = getState(expect);
+    setState({ assertionCalls: assertionCalls + 1 }, expect);
+    return chai.expect(value, message) as unknown as Assertion;
+  }) as ExpectStatic;
+  Object.assign(expect, chai.expect);
+  Object.assign(
+    expect,
+    globalThis[ASYMMETRIC_MATCHERS_OBJECT as unknown as keyof typeof globalThis]
+  );
+
+  expect.getState = () => getState<MatcherState>(expect);
+  expect.setState = (state) => setState(state as Partial<MatcherState>, expect);
+
+  // @ts-expect-error global is not typed
+  const globalState = getState(globalThis[GLOBAL_EXPECT]) || {};
+
+  setState<MatcherState>(
+    {
+      // this should also add "snapshotState" that is added conditionally
+      ...globalState,
+      assertionCalls: 0,
+      isExpectingAssertions: false,
+      isExpectingAssertionsError: null,
+      expectedAssertionsNumber: null,
+      expectedAssertionsNumberErrorGen: null,
+    },
+    expect
+  );
+
+  // @ts-expect-error untyped
+  expect.extend = (matchers) => chai.expect.extend(expect, matchers);
+  // @ts-expect-error untyped
+  expect.addEqualityTesters = (customTesters) =>
+    addCustomEqualityTesters(customTesters);
+
+  // @ts-expect-error untyped
+  expect.soft = (...args) => {
+    // @ts-expect-error private soft access
+    return expect(...args).withContext({ soft: true }) as Assertion;
+  };
+
+  // @ts-expect-error untyped
+  expect.unreachable = (message?: string) => {
+    chai.assert.fail(
+      `expected${message ? ` "${message}" ` : ' '}not to be reached`
+    );
+  };
+
+  function assertions(expected: number) {
+    const errorGen = () =>
+      new Error(
+        `expected number of assertions to be ${expected}, but got ${
+          expect.getState().assertionCalls
+        }`
+      );
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(errorGen(), assertions);
+    }
+
+    expect.setState({
+      expectedAssertionsNumber: expected,
+      expectedAssertionsNumberErrorGen: errorGen,
+    });
+  }
+
+  function hasAssertions() {
+    const error = new Error('expected any number of assertion, but got none');
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(error, hasAssertions);
+    }
+
+    expect.setState({
+      isExpectingAssertions: true,
+      isExpectingAssertionsError: error,
+    });
+  }
+
+  chai.util.addMethod(expect, 'assertions', assertions);
+  chai.util.addMethod(expect, 'hasAssertions', hasAssertions);
+
+  expect.extend(customMatchers);
+  expect.extend({
+    toMatchImageSnapshot,
+  });
+
+  return expect;
+}
+
+const globalExpect: ExpectStatic = createExpect();
+
+Object.defineProperty(globalThis, GLOBAL_EXPECT, {
+  value: globalExpect,
+  writable: true,
+  configurable: true,
+});
+
+export { assert, should } from 'chai';
+export { chai, globalExpect as expect };
+
+export type {
+  Assertion,
+  AsymmetricMatchersContaining,
+  DeeplyAllowMatchers,
+  ExpectStatic,
+  JestAssertion,
+  Matchers,
+} from '@vitest/expect';

package/src/expect/index.ts

@@ -1,123 +1 @@
-// This is adapted version of https://github.com/vitest-dev/vitest/blob/main/packages/vitest/src/integrations/chai/index.ts
-// Credits to Vitest team for the original implementation.
-
-import type { Assertion, ExpectStatic, MatcherState } from '@vitest/expect';
-import {
-  addCustomEqualityTesters,
-  ASYMMETRIC_MATCHERS_OBJECT,
-  customMatchers,
-  getState,
-  GLOBAL_EXPECT,
-  setState,
-} from '@vitest/expect';
-import * as chai from 'chai';
-
-// Setup additional matchers
-import './setup.js';
-
-export function createExpect(): ExpectStatic {
-  const expect = ((value: unknown, message?: string): Assertion => {
-    const { assertionCalls } = getState(expect);
-    setState({ assertionCalls: assertionCalls + 1 }, expect);
-    return chai.expect(value, message) as unknown as Assertion;
-  }) as ExpectStatic;
-  Object.assign(expect, chai.expect);
-  Object.assign(
-    expect,
-    globalThis[ASYMMETRIC_MATCHERS_OBJECT as unknown as keyof typeof globalThis]
-  );
-
-  expect.getState = () => getState<MatcherState>(expect);
-  expect.setState = (state) => setState(state as Partial<MatcherState>, expect);
-
-  // @ts-expect-error global is not typed
-  const globalState = getState(globalThis[GLOBAL_EXPECT]) || {};
-
-  setState<MatcherState>(
-    {
-      // this should also add "snapshotState" that is added conditionally
-      ...globalState,
-      assertionCalls: 0,
-      isExpectingAssertions: false,
-      isExpectingAssertionsError: null,
-      expectedAssertionsNumber: null,
-      expectedAssertionsNumberErrorGen: null,
-    },
-    expect
-  );
-
-  // @ts-expect-error untyped
-  expect.extend = (matchers) => chai.expect.extend(expect, matchers);
-  // @ts-expect-error untyped
-  expect.addEqualityTesters = (customTesters) =>
-    addCustomEqualityTesters(customTesters);
-
-  // @ts-expect-error untyped
-  expect.soft = (...args) => {
-    // @ts-expect-error private soft access
-    return expect(...args).withContext({ soft: true }) as Assertion;
-  };
-
-  // @ts-expect-error untyped
-  expect.unreachable = (message?: string) => {
-    chai.assert.fail(
-      `expected${message ? ` "${message}" ` : ' '}not to be reached`
-    );
-  };
-
-  function assertions(expected: number) {
-    const errorGen = () =>
-      new Error(
-        `expected number of assertions to be ${expected}, but got ${
-          expect.getState().assertionCalls
-        }`
-      );
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(errorGen(), assertions);
-    }
-
-    expect.setState({
-      expectedAssertionsNumber: expected,
-      expectedAssertionsNumberErrorGen: errorGen,
-    });
-  }
-
-  function hasAssertions() {
-    const error = new Error('expected any number of assertion, but got none');
-    if (Error.captureStackTrace) {
-      Error.captureStackTrace(error, hasAssertions);
-    }
-
-    expect.setState({
-      isExpectingAssertions: true,
-      isExpectingAssertionsError: error,
-    });
-  }
-
-  chai.util.addMethod(expect, 'assertions', assertions);
-  chai.util.addMethod(expect, 'hasAssertions', hasAssertions);
-
-  expect.extend(customMatchers);
-
-  return expect;
-}
-
-const globalExpect: ExpectStatic = createExpect();
-
-Object.defineProperty(globalThis, GLOBAL_EXPECT, {
-  value: globalExpect,
-  writable: true,
-  configurable: true,
-});
-
-export { assert, should } from 'chai';
-export { chai, globalExpect as expect };
-
-export type {
-  Assertion,
-  AsymmetricMatchersContaining,
-  DeeplyAllowMatchers,
-  ExpectStatic,
-  JestAssertion,
-  Matchers,
-} from '@vitest/expect';
+export * from './expect.js';

package/src/expect/matchers/toMatchImageSnapshot.ts

@@ -0,0 +1,50 @@
+import { getClientInstance } from '../../client/store.js';
+import type { MatcherState } from '@vitest/expect';
+import {
+  type ImageSnapshotOptions,
+  generateTransferId,
+} from '@react-native-harness/bridge';
+import { getHarnessContext } from '../../runner/index.js';
+
+type ScreenshotResult = {
+  data: Uint8Array;
+  width: number;
+  height: number;
+};
+
+export async function toMatchImageSnapshot(
+  this: MatcherState,
+  received: ScreenshotResult,
+  options: ImageSnapshotOptions
+): Promise<{ pass: boolean; message: () => string }> {
+  const client = getClientInstance();
+  const context = getHarnessContext();
+
+  const transferId = generateTransferId();
+  client.sendBinary(transferId, received.data);
+
+  const screenshotFile = await client.rpc['device.screenshot.receive'](
+    {
+      type: 'binary',
+      transferId,
+      size: received.data.length,
+      mimeType: 'image/png',
+    },
+    {
+      width: received.width,
+      height: received.height,
+    }
+  );
+
+  const result = await client.rpc['test.matchImageSnapshot'](
+    screenshotFile,
+    context.testFilePath,
+    options,
+    context.runner
+  );
+
+  return {
+    pass: result.pass,
+    message: () => result.message,
+  };
+}

package/src/globals.ts

@@ -1,3 +1,5 @@
+import type { ImageSnapshotOptions } from '@react-native-harness/bridge';
+
 export type HarnessGlobal = {
   appRegistryComponentName: string;
   webSocketPort?: number;
@@ -7,6 +9,16 @@ declare global {
   var RN_HARNESS: HarnessGlobal | undefined;
 }
 
+declare module '@vitest/expect' {
+  interface Matchers {
+    /**
+     * Match the received screenshot against a stored snapshot.
+     * Creates a new snapshot if one doesn't exist.
+     */
+    toMatchImageSnapshot(options: ImageSnapshotOptions): Promise<void>;
+  }
+}
+
 export const getHarnessGlobal = (): HarnessGlobal => {
   const harnessGlobal = global.RN_HARNESS;
 

package/src/index.ts

@@ -1,4 +1,5 @@
-import './globals.d.ts';
+import './polyfills.js';
+import './globals.js';
 
 export { UI as ReactNativeHarness } from './ui/index.js';
 export * from './spy/index.js';

package/src/polyfills.ts

@@ -0,0 +1,14 @@
+/**
+ * Polyfills for ES2022+ features not supported by JSC (JavaScriptCore).
+ *
+ * JSC, used in React Native when Hermes is disabled, doesn't support
+ * Object.hasOwn (ES2022). This causes runtime errors when @vitest/expect
+ * v4.x initializes.
+ *
+ * This polyfill must be loaded before any code that uses Object.hasOwn.
+ */
+
+if (typeof Object.hasOwn !== 'function') {
+  Object.hasOwn = (obj: object, prop: PropertyKey): boolean =>
+    Object.prototype.hasOwnProperty.call(obj, prop);
+}

package/src/render/TestComponentOverlay.tsx

@@ -4,6 +4,21 @@ import { useRenderedElement } from '../ui/state.js';
 import { store } from '../ui/state.js';
 import { ErrorBoundary } from './ErrorBoundary.js';
 
+/**
+ * Waits for the native view hierarchy to be fully updated.
+ * Uses double requestAnimationFrame to ensure native has processed
+ * all view creation commands after React's commit phase.
+ */
+const waitForNativeViewHierarchy = (): Promise<void> => {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        resolve();
+      });
+    });
+  });
+};
+
 export const TestComponentOverlay = (): React.ReactElement | null => {
   const { element, key } = useRenderedElement();
 
@@ -12,8 +27,13 @@ export const TestComponentOverlay = (): React.ReactElement | null => {
     const callback = store.getState().onRenderCallback;
 
     if (callback) {
-      callback();
-      store.getState().setOnRenderCallback(null);
+      // Wait for native view hierarchy to be fully updated before calling callback.
+      // useEffect fires after React commits, but native processes commands async.
+      // Double rAF ensures native has finished processing all view creation.
+      waitForNativeViewHierarchy().then(() => {
+        callback();
+        store.getState().setOnRenderCallback(null);
+      });
     }
   }, [element]);
 

package/src/render/index.ts

@@ -25,16 +25,18 @@ export const render = async (
     store.getState().setOnRenderCallback(null);
   }
 
-  // Create a promise that resolves when the element is laid out
-  const layoutPromise = new Promise<void>((resolve, reject) => {
+  // Create a promise that resolves when the element is rendered.
+  // We use onRenderCallback which fires in useEffect, guaranteeing that
+  // React has committed all children to the native view hierarchy.
+  const renderPromise = new Promise<void>((resolve, reject) => {
     const timeoutId = setTimeout(() => {
-      store.getState().setOnLayoutCallback(null);
+      store.getState().setOnRenderCallback(null);
       reject(
         new Error(`Render timeout: Element did not mount within ${timeout}ms`)
       );
     }, timeout);
 
-    store.getState().setOnLayoutCallback(() => {
+    store.getState().setOnRenderCallback(() => {
       clearTimeout(timeoutId);
       resolve();
     });
@@ -44,8 +46,8 @@ export const render = async (
   const wrappedElement = wrapElement(element, wrapper);
   store.getState().setRenderedElement(wrappedElement);
 
-  // Wait for layout
-  await layoutPromise;
+  // Wait for useEffect to fire, ensuring all children are committed
+  await renderPromise;
 
   const rerender = async (newElement: React.ReactElement): Promise<void> => {
     if (store.getState().renderedElement === null) {

package/src/runner/context.ts

@@ -0,0 +1,16 @@
+export type HarnessContext = {
+  testFilePath: string;
+  runner: string;
+};
+
+declare global {
+  var HARNESS_CONTEXT: HarnessContext;
+}
+
+export const getHarnessContext = (): HarnessContext => {
+  return globalThis['HARNESS_CONTEXT'];
+};
+
+export const setHarnessContext = (context: HarnessContext): void => {
+  globalThis['HARNESS_CONTEXT'] = context;
+};

package/src/runner/factory.ts

@@ -2,13 +2,19 @@ import type { TestRunnerEvents } from '@react-native-harness/bridge';
 import { getEmitter } from '../utils/emitter.js';
 import { runSuite } from './runSuite.js';
 import { TestRunner } from './types.js';
+import { setHarnessContext } from './context.js';
 
 export const getTestRunner = (): TestRunner => {
   const events = getEmitter<TestRunnerEvents>();
 
   return {
     events,
-    run: async (testSuite, testFilePath) => {
+    run: async ({ testSuite, testFilePath, runner }) => {
+      setHarnessContext({
+        testFilePath,
+        runner,
+      });
+
       const result = await runSuite(testSuite, {
         events,
         testFilePath,

package/src/runner/index.ts

@@ -5,3 +5,8 @@ export type {
 } from './types.js';
 export { TestExecutionError } from './errors.js';
 export { getTestRunner } from './factory.js';
+export {
+  getHarnessContext,
+  setHarnessContext,
+  type HarnessContext,
+} from './context.js';

package/src/runner/runSuite.ts

@@ -8,6 +8,10 @@ import { runHooks } from './hooks.js';
 import { getTestExecutionError } from './errors.js';
 import { TestRunnerContext } from './types.js';
 
+declare global {
+  var HARNESS_TEST_PATH: string;
+}
+
 const runTest = async (
   test: TestCase,
   suite: TestSuite,

package/src/runner/types.ts

@@ -12,8 +12,14 @@ export type TestRunnerContext = {
   testFilePath: string;
 };
 
+export type RunTestsOptions = {
+  testSuite: TestSuite;
+  testFilePath: string;
+  runner: string;
+};
+
 export type TestRunner = {
   events: TestRunnerEventsEmitter;
-  run: (testSuite: TestSuite, testFilePath: string) => Promise<TestSuiteResult>;
+  run: (options: RunTestsOptions) => Promise<TestSuiteResult>;
   dispose: () => void;
 };

package/src/ui/ReadyScreen.tsx

@@ -16,6 +16,7 @@ export const ReadyScreen = () => {
 
   return (
     <View style={styles.container}>
+      <StatusBar hidden={true} />
       <View style={styles.contentContainer}>
         <Text style={styles.title}>React Native Harness</Text>
 

package/.babelrc.js

@@ -1,23 +0,0 @@
-module.exports = function (api) {
-  api.cache(true);
-
-  return {
-    presets: [
-      [
-        '@nx/react/babel',
-        {
-          runtime: 'automatic',
-          useBuiltIns: 'usage',
-        },
-      ],
-    ],
-    plugins: [],
-    env: {
-      test: {
-        presets: [
-          ['module:@react-native/babel-preset', { useTransformReactJSX: true }],
-        ],
-      },
-    },
-  };
-};