@react-native-harness/runtime 1.0.0-alpha.1

package/src/collector/errors.ts

@@ -0,0 +1,27 @@
+export type TestErrorCode =
+  | 'CONTEXT_NOT_INITIALIZED'
+  | 'OUTSIDE_DESCRIBE_BLOCK'
+  | 'INVALID_TEST_NAME'
+  | 'DUPLICATE_TEST_NAME'
+  | 'INVALID_FUNCTION';
+
+export class TestError extends Error {
+  constructor(
+    public code: TestErrorCode,
+    public functionName: string,
+    public context?: Record<string, unknown>
+  ) {
+    const baseMessages: Record<TestErrorCode, string> = {
+      CONTEXT_NOT_INITIALIZED:
+        'Test context not initialized. Call collectTests() first.',
+      OUTSIDE_DESCRIBE_BLOCK: `${functionName}() must be called within a describe() block`,
+      INVALID_TEST_NAME: `${functionName}() requires a non-empty string name`,
+      DUPLICATE_TEST_NAME: `Duplicate test name "${context?.name}" in suite "${context?.suiteName}"`,
+      INVALID_FUNCTION: `${functionName}() requires a function as the second parameter`,
+    };
+
+    const message = baseMessages[code] || `Unknown error in ${functionName}()`;
+    super(message);
+    this.name = 'TestError';
+  }
+}

package/src/collector/factory.ts

@@ -0,0 +1,32 @@
+import type { TestCollectorEvents } from '@react-native-harness/bridge';
+import { getEmitter } from '../utils/emitter.js';
+import { collectTests } from './functions.js';
+import { TestCollector } from './types.js';
+
+export const getTestCollector = (): TestCollector => {
+  const events = getEmitter<TestCollectorEvents>();
+
+  return {
+    events,
+    collect: async (fn, testFilePath) => {
+      const start = Date.now();
+      events.emit({
+        type: 'collection-started',
+        file: testFilePath,
+      });
+
+      const result = await collectTests(fn);
+
+      events.emit({
+        type: 'collection-finished',
+        file: testFilePath,
+        duration: Date.now() - start,
+      });
+
+      return result;
+    },
+    dispose: () => {
+      events.clearAllListeners();
+    },
+  };
+};

package/src/collector/functions.ts

@@ -0,0 +1,376 @@
+import type {
+  TestCase,
+  TestSuite,
+  CollectionResult,
+} from '@react-native-harness/bridge';
+import type { TestFn } from './types.js';
+import { TestError } from './errors.js';
+import { validateTestName, validateTestFunction } from './validation.js';
+
+type TestStatus = 'active' | 'skipped' | 'todo';
+
+type RawTestCase = {
+  name: string;
+  fn: TestFn;
+  options: {
+    only?: boolean;
+    skip?: boolean;
+    todo?: boolean;
+  };
+};
+
+type RawTestSuite = {
+  name: string;
+  tests: RawTestCase[];
+  suites: RawTestSuite[];
+  hooks: {
+    beforeAll: TestFn[];
+    afterAll: TestFn[];
+    beforeEach: TestFn[];
+    afterEach: TestFn[];
+  };
+  options: {
+    only?: boolean;
+    skip?: boolean;
+  };
+};
+
+// Computation functions for two-phase approach
+const computeTestStatus = (
+  test: RawTestCase,
+  suiteContext: { hasFocusedTests: boolean }
+): TestStatus => {
+  if (test.options.todo) return 'todo';
+  if (test.options.skip) return 'skipped';
+  if (test.options.only) return 'active';
+  if (suiteContext.hasFocusedTests) return 'skipped';
+  return 'active';
+};
+
+const computeSuiteStatus = (
+  suite: RawTestSuite,
+  parentContext: { hasFocusedChildren: boolean }
+): TestStatus => {
+  if (suite.options.skip) return 'skipped';
+  if (suite.options.only) return 'active';
+  if (parentContext.hasFocusedChildren) return 'skipped';
+  return 'active';
+};
+
+const convertRawTestCaseToTestCase = (
+  rawTest: RawTestCase,
+  suiteContext: { hasFocusedTests: boolean }
+): TestCase => {
+  return {
+    name: rawTest.name,
+    fn: rawTest.fn,
+    status: computeTestStatus(rawTest, suiteContext),
+  };
+};
+
+const convertRawTestSuiteToTestSuite = (
+  rawSuite: RawTestSuite,
+  parentContext: { hasFocusedChildren: boolean } = {
+    hasFocusedChildren: false,
+  },
+  parentSuite?: TestSuite
+): TestSuite => {
+  // Validate duplicate test names within this suite
+  const testNames = new Set<string>();
+  for (const test of rawSuite.tests) {
+    if (testNames.has(test.name)) {
+      throw new TestError('DUPLICATE_TEST_NAME', 'test', {
+        name: test.name,
+        suiteName: rawSuite.name,
+      });
+    }
+    testNames.add(test.name);
+  }
+
+  // Check if this suite has focused tests
+  const hasFocusedTests = rawSuite.tests.some((test) => test.options.only);
+
+  // Check if this suite has focused children
+  const hasFocusedChildren = rawSuite.suites.some(
+    (suite) =>
+      suite.options.only || suite.tests.some((test) => test.options.only)
+  );
+
+  // Convert tests
+  const tests = rawSuite.tests.map((test) =>
+    convertRawTestCaseToTestCase(test, { hasFocusedTests })
+  );
+
+  // Create the suite first so we can reference it when converting children
+  const suite: TestSuite = {
+    name: rawSuite.name,
+    tests,
+    suites: [],
+    parent: parentSuite,
+    beforeAll: rawSuite.hooks.beforeAll,
+    afterAll: rawSuite.hooks.afterAll,
+    beforeEach: rawSuite.hooks.beforeEach,
+    afterEach: rawSuite.hooks.afterEach,
+    status: computeSuiteStatus(rawSuite, parentContext),
+    _hasFocused: hasFocusedTests || hasFocusedChildren || rawSuite.options.only,
+  };
+
+  // Convert child suites with this suite as their parent
+  suite.suites = rawSuite.suites.map((childSuite) =>
+    convertRawTestSuiteToTestSuite(childSuite, { hasFocusedChildren }, suite)
+  );
+
+  return suite;
+};
+
+type TestContext = {
+  rootSuite: RawTestSuite;
+  currentSuite: RawTestSuite | null;
+};
+
+let currentContext: TestContext | null = null;
+
+const clearState = (): TestContext => {
+  const rootSuite = createRawSuite('root');
+  return {
+    rootSuite,
+    currentSuite: rootSuite,
+  };
+};
+
+const getCurrentSuite = (): RawTestSuite | null => {
+  if (!currentContext) {
+    throw new TestError('CONTEXT_NOT_INITIALIZED', 'getCurrentSuite');
+  }
+  return currentContext.currentSuite;
+};
+
+const getRootSuite = (): RawTestSuite => {
+  if (!currentContext) {
+    throw new TestError('CONTEXT_NOT_INITIALIZED', 'getRootSuite');
+  }
+  return currentContext.rootSuite;
+};
+
+const setCurrentSuite = (suite: RawTestSuite | null): void => {
+  if (!currentContext) {
+    throw new TestError('CONTEXT_NOT_INITIALIZED', 'setCurrentSuite');
+  }
+  currentContext.currentSuite = suite;
+};
+
+const createRawSuite = (
+  name: string,
+  options: { only?: boolean; skip?: boolean } = {}
+): RawTestSuite => {
+  return {
+    name,
+    tests: [],
+    suites: [],
+    hooks: {
+      beforeAll: [],
+      afterAll: [],
+      beforeEach: [],
+      afterEach: [],
+    },
+    options,
+  };
+};
+
+export const describe = Object.assign(
+  (name: string, fn: () => void) => {
+    validateTestName(name, 'describe');
+    validateTestFunction(fn, 'describe');
+
+    const suite = createRawSuite(name);
+    const previousSuite = getCurrentSuite();
+    setCurrentSuite(suite);
+
+    try {
+      fn();
+    } finally {
+      setCurrentSuite(previousSuite);
+    }
+
+    // Add the suite to its parent
+    if (previousSuite) {
+      previousSuite.suites.push(suite);
+    } else {
+      getRootSuite().suites.push(suite);
+    }
+  },
+  {
+    skip: (name: string, fn: () => void) => {
+      validateTestName(name, 'describe.skip');
+      validateTestFunction(fn, 'describe.skip');
+
+      const suite = createRawSuite(name, { skip: true });
+      const previousSuite = getCurrentSuite();
+      setCurrentSuite(suite);
+
+      try {
+        fn();
+      } finally {
+        setCurrentSuite(previousSuite);
+      }
+
+      // Add the suite to its parent
+      if (previousSuite) {
+        previousSuite.suites.push(suite);
+      } else {
+        getRootSuite().suites.push(suite);
+      }
+    },
+    only: (name: string, fn: () => void) => {
+      validateTestName(name, 'describe.only');
+      validateTestFunction(fn, 'describe.only');
+
+      const suite = createRawSuite(name, { only: true });
+      const previousSuite = getCurrentSuite();
+      setCurrentSuite(suite);
+
+      try {
+        fn();
+      } finally {
+        setCurrentSuite(previousSuite);
+      }
+
+      // Add the suite to its parent
+      if (previousSuite) {
+        previousSuite.suites.push(suite);
+      } else {
+        getRootSuite().suites.push(suite);
+      }
+    },
+  }
+);
+
+export const test = Object.assign(
+  (name: string, fn: TestFn) => {
+    validateTestName(name, 'test');
+    validateTestFunction(fn, 'test');
+
+    const currentSuite = getCurrentSuite();
+    if (!currentSuite) {
+      throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'test');
+    }
+
+    // Add test with default options
+    currentSuite.tests.push({ name, fn, options: {} });
+  },
+  {
+    skip: (name: string, fn: TestFn) => {
+      validateTestName(name, 'test.skip');
+      validateTestFunction(fn, 'test.skip');
+
+      const currentSuite = getCurrentSuite();
+      if (!currentSuite) {
+        throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'test.skip');
+      }
+
+      currentSuite.tests.push({ name, fn, options: { skip: true } });
+    },
+    only: (name: string, fn: TestFn) => {
+      validateTestName(name, 'test.only');
+      validateTestFunction(fn, 'test.only');
+
+      const currentSuite = getCurrentSuite();
+      if (!currentSuite) {
+        throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'test.only');
+      }
+
+      currentSuite.tests.push({ name, fn, options: { only: true } });
+    },
+    todo: (name: string) => {
+      validateTestName(name, 'test.todo');
+
+      const currentSuite = getCurrentSuite();
+      if (!currentSuite) {
+        throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'test.todo');
+      }
+
+      currentSuite.tests.push({
+        name,
+        fn: () => {
+          // Empty function for todo tests
+        },
+        options: { todo: true },
+      });
+    },
+  }
+);
+
+export const it = test;
+
+export function beforeAll(fn: TestFn) {
+  validateTestFunction(fn, 'beforeAll');
+
+  const currentSuite = getCurrentSuite();
+  if (!currentSuite) {
+    throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'beforeAll');
+  }
+  currentSuite.hooks.beforeAll.push(fn);
+}
+
+export function afterAll(fn: TestFn) {
+  validateTestFunction(fn, 'afterAll');
+
+  const currentSuite = getCurrentSuite();
+  if (!currentSuite) {
+    throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'afterAll');
+  }
+  currentSuite.hooks.afterAll.push(fn);
+}
+
+export function beforeEach(fn: TestFn) {
+  validateTestFunction(fn, 'beforeEach');
+
+  const currentSuite = getCurrentSuite();
+  if (!currentSuite) {
+    throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'beforeEach');
+  }
+  currentSuite.hooks.beforeEach.push(fn);
+}
+
+export function afterEach(fn: TestFn) {
+  validateTestFunction(fn, 'afterEach');
+
+  const currentSuite = getCurrentSuite();
+  if (!currentSuite) {
+    throw new TestError('OUTSIDE_DESCRIBE_BLOCK', 'afterEach');
+  }
+  currentSuite.hooks.afterEach.push(fn);
+}
+
+/**
+ * Recursively counts the total number of tests that will actually be executed.
+ * Only counts active tests since skipped and todo tests are not executed.
+ */
+const countTests = (suite: TestSuite): number => {
+  let count = suite.tests.filter((test) => test.status === 'active').length;
+
+  for (const childSuite of suite.suites) {
+    count += countTests(childSuite);
+  }
+
+  return count;
+};
+
+export const collectTests = (fn: () => void): CollectionResult => {
+  currentContext = clearState();
+
+  try {
+    fn();
+
+    // Convert raw structure to final structure using computation phase
+    const testSuite = convertRawTestSuiteToTestSuite(getRootSuite());
+    const totalTests = countTests(testSuite);
+
+    return {
+      testSuite,
+      totalTests,
+    };
+  } finally {
+    currentContext = null;
+  }
+};

package/src/collector/index.ts

@@ -0,0 +1,12 @@
+export {
+  describe,
+  test,
+  it,
+  beforeAll,
+  afterAll,
+  beforeEach,
+  afterEach,
+} from './functions.js';
+export { TestError, type TestErrorCode } from './errors.js';
+export type { TestCollector, TestCollectorEventsEmitter } from './types.js';
+export { getTestCollector } from './factory.js';

package/src/collector/types.ts

@@ -0,0 +1,15 @@
+import { EventEmitter } from '../utils/emitter.js';
+import {
+  TestCollectorEvents,
+  CollectionResult,
+} from '@react-native-harness/bridge';
+
+export type TestFn = () => void | Promise<void>;
+
+export type TestCollectorEventsEmitter = EventEmitter<TestCollectorEvents>;
+
+export type TestCollector = {
+  events: TestCollectorEventsEmitter;
+  collect: (fn: () => void, testFilePath: string) => Promise<CollectionResult>;
+  dispose: () => void;
+};

package/src/collector/validation.ts

@@ -0,0 +1,21 @@
+import { TestError } from './errors.js';
+import { TestFn } from './types.js';
+
+export const validateTestName = (name: string, functionName: string): void => {
+  if (!name || typeof name !== 'string' || name.trim() === '') {
+    throw new TestError('INVALID_TEST_NAME', functionName, {
+      name,
+    });
+  }
+};
+
+export const validateTestFunction = (
+  fn: TestFn,
+  functionName: string
+): void => {
+  if (typeof fn !== 'function') {
+    throw new TestError('INVALID_FUNCTION', functionName, {
+      functionType: typeof fn,
+    });
+  }
+};

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const LOGO_IMAGE = require('../assets/logo.png');
+export const WS_SERVER_PORT = 3001;

package/src/errors.ts

@@ -0,0 +1,12 @@
+export class EnvironmentError extends Error {
+  constructor(
+    public readonly context: string,
+    public readonly details?: string
+  ) {
+    const message = details
+      ? `Environment error in ${context}: ${details}`
+      : `Environment error: ${context}`;
+    super(message);
+    this.name = 'EnvironmentError';
+  }
+}

package/src/expect/index.ts

@@ -0,0 +1,117 @@
+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: any, 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 as any)[ASYMMETRIC_MATCHERS_OBJECT]);
+
+  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';

package/src/expect/setup.ts

@@ -0,0 +1,10 @@
+import {
+  JestAsymmetricMatchers,
+  JestChaiExpect,
+  JestExtend,
+} from '@vitest/expect';
+import * as chai from 'chai';
+
+chai.use(JestExtend);
+chai.use(JestChaiExpect);
+chai.use(JestAsymmetricMatchers);

package/src/globals.ts

@@ -0,0 +1,5 @@
+declare global {
+  var RN_HARNESS: boolean | undefined;
+}
+
+export {};

package/src/index.ts

@@ -0,0 +1,7 @@
+import './globals.d.ts';
+
+export { UI as ReactNativeHarness } from './ui/index.js';
+export * from './spy/index.js';
+export * from './expect/index.js';
+export * from './collector/index.js';
+export * from './mocker/index.js';

package/src/initialize.ts

@@ -0,0 +1,22 @@
+import { getDeviceDescriptor } from './client/getDeviceDescriptor.js';
+import { getClient } from './client/index.js';
+
+// Polyfill for EventTarget
+const Shim = require('event-target-shim');
+globalThis.Event = Shim.Event;
+globalThis.EventTarget = Shim.EventTarget;
+
+// Turn off LogBox
+const { LogBox } = require('react-native');
+LogBox.ignoreAllLogs(true);
+
+// Turn off HMR
+const HMRClient = require('react-native/Libraries/Utilities/HMRClient');
+HMRClient.setup = () => {
+  // No setup = no HMR
+};
+
+// Initialize the client
+void getClient().then((client) =>
+  client.rpc.reportReady(getDeviceDescriptor())
+);

package/src/mocker/index.ts

@@ -0,0 +1 @@
+export { mock, requireActual, clearMocks } from './registry.js';

package/src/mocker/metro-require.d.ts

@@ -0,0 +1,5 @@
+import type { Require } from './types.js';
+
+declare global {
+  var __r: Require;
+}