hermes-test 0.2.0

package/src/hooks.ts

@@ -0,0 +1,226 @@
+// renderHook, act, waitFor — React hook testing primitives
+// Uses react-reconciler to run hooks in a minimal React tree.
+// No dependency on react-test-renderer (deprecated in React 19).
+//
+// React and ReactReconciler are NOT bundled with the harness — they come from
+// the user's project via esbuild. The harness expects them on globalThis.
+
+function getReact(): typeof import('react') {
+  const R = (globalThis as any).__HT_React;
+  if (!R) throw new Error('React not available. Make sure react is installed in your project.');
+  return R;
+}
+
+import Reconciler from 'react-reconciler';
+import { DefaultEventPriority, NoEventPriority } from 'react-reconciler/constants';
+
+// Based on mdjastrzebski/test-renderer — the universal-test-renderer for React 19
+// https://github.com/mdjastrzebski/test-renderer
+let currentUpdatePriority: number = NoEventPriority;
+
+const hostConfig = {
+  supportsMutation: true,
+  supportsPersistence: false,
+  supportsHydration: false,
+  supportsMicrotasks: true,
+  isPrimaryRenderer: true,
+  warnsIfNotActing: true,
+  createInstance() { return { children: [] }; },
+  createTextInstance() { return {}; },
+  appendInitialChild(p: any, c: any) { p.children.push(c); },
+  appendChild(p: any, c: any) { p.children.push(c); },
+  appendChildToContainer(p: any, c: any) { p.children.push(c); },
+  removeChild(p: any, c: any) { const i = p.children.indexOf(c); if (i !== -1) p.children.splice(i, 1); },
+  removeChildFromContainer(p: any, c: any) { const i = p.children.indexOf(c); if (i !== -1) p.children.splice(i, 1); },
+  insertBefore(p: any, c: any, b: any) { const i = p.children.indexOf(b); p.children.splice(i, 0, c); },
+  insertInContainerBefore(p: any, c: any, b: any) { const i = p.children.indexOf(b); p.children.splice(i, 0, c); },
+  commitUpdate() {},
+  commitTextUpdate() {},
+  commitMount() {},
+  prepareForCommit() { return null; },
+  resetAfterCommit() {},
+  resetTextContent() {},
+  finalizeInitialChildren() { return false; },
+  shouldSetTextContent() { return false; },
+  getRootHostContext() { return null; },
+  getChildHostContext(ctx: any) { return ctx; },
+  getPublicInstance(inst: any) { return inst; },
+  prepareUpdate() { return {}; },
+  clearContainer(c: any) { c.children = []; },
+  scheduleTimeout: (globalThis as any).setTimeout || ((fn: any) => fn()),
+  cancelTimeout: (globalThis as any).clearTimeout || (() => {}),
+  noTimeout: -1,
+  scheduleMicrotask: typeof queueMicrotask === 'function' ? queueMicrotask : (fn: any) => Promise.resolve().then(fn),
+  getCurrentEventPriority() { return DefaultEventPriority; },
+  setCurrentUpdatePriority(priority: number) { currentUpdatePriority = priority; },
+  getCurrentUpdatePriority() { return currentUpdatePriority; },
+  resolveUpdatePriority() { return currentUpdatePriority || DefaultEventPriority; },
+  shouldAttemptEagerTransition() { return false; },
+  trackSchedulerEvent() {},
+  resolveEventType() { return ''; },
+  resolveEventTimeStamp() { return -1.1; },
+  requestPostPaintCallback() {},
+  maySuspendCommit() { return false; },
+  preloadInstance() { return true; },
+  startSuspendingCommit() {},
+  suspendInstance() {},
+  waitForCommitToBeReady() { return null; },
+  NotPendingTransition: null,
+  resetFormInstance() {},
+  hideInstance() {},
+  unhideInstance() {},
+  hideTextInstance() {},
+  unhideTextInstance() {},
+  getInstanceFromNode() { return null; },
+  prepareScopeUpdate() {},
+  getInstanceFromScope() { return null; },
+  detachDeletedInstance() {},
+  beforeActiveInstanceBlur() {},
+  afterActiveInstanceBlur() {},
+  preparePortalMount() {},
+};
+
+function createReconciler() {
+  const create = typeof Reconciler === 'function' ? Reconciler : (Reconciler as any).default;
+  return create(hostConfig);
+}
+
+type HookResult<T> = {
+  readonly result: { readonly current: T };
+  readonly current: T;
+  readonly history: ReadonlyArray<T>;
+  readonly renderCount: number;
+  rerender(props?: any): void;
+  unmount(): void;
+};
+
+const drain = (globalThis as any).__HT_drain || (() => {});
+
+function flush() {
+  drain();
+}
+
+// Enable React.act() support
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+export function act(fn: () => void | Promise<void>): void {
+  const React = getReact();
+  const reactAct = (React as any).act || (React as any).unstable_act;
+  if (!reactAct) {
+    fn();
+    flush();
+    return;
+  }
+
+  reactAct(() => {
+    const result = fn();
+    if (result && typeof (result as any).then === 'function') {
+      let settled = false;
+      let error: any;
+      (result as Promise<void>).then(
+        () => { settled = true; },
+        (e: any) => { settled = true; error = e; }
+      );
+      for (let i = 0; i < 50 && !settled; i++) {
+        drain();
+      }
+      if (error) throw error;
+    }
+  });
+  flush();
+}
+
+export function renderHook<T>(
+  hookFn: (props?: any) => T,
+  options?: { initialProps?: any; wrapper?: any }
+): HookResult<T> {
+  const history: T[] = [];
+  let currentValue: T;
+
+  const React = getReact();
+  const reconciler = createReconciler();
+
+  const container = { children: [] };
+  const root = reconciler.createContainer(
+    container,
+    0, // LegacyRoot — effects fire synchronously in act()
+    null,  // hydrationCallbacks
+    false, // isStrictMode
+    false, // concurrentUpdatesByDefaultOverride
+    '',    // identifierPrefix
+    (err: any) => { throw err; }, // onUncaughtError
+    (err: any) => { throw err; }, // onCaughtError
+    null,  // onRecoverableError
+    () => {}, // onDefaultTransitionIndicator
+  );
+
+  function TestComponent({ hookProps }: { hookProps: any }) {
+    const value = hookFn(hookProps);
+    currentValue = value;
+    history.push(value);
+    return null;
+  }
+
+  function createTree(props?: any) {
+    const testEl = React.createElement(TestComponent, { hookProps: props });
+    if (options?.wrapper) {
+      return React.createElement(options.wrapper, null, testEl);
+    }
+    return testEl;
+  }
+
+  act(() => {
+    reconciler.updateContainer(createTree(options?.initialProps), root, null, null);
+  });
+
+  return {
+    result: {
+      get current() {
+        return currentValue!;
+      },
+    },
+    get current() {
+      return currentValue!;
+    },
+    get history() {
+      return history;
+    },
+    get renderCount() {
+      return history.length;
+    },
+    rerender(props?: any) {
+      act(() => {
+        reconciler.updateContainer(createTree(props), root, null, null);
+      });
+    },
+    unmount() {
+      act(() => {
+        reconciler.updateContainer(null, root, null, null);
+      });
+    },
+  };
+}
+
+export function waitFor<T>(
+  predicate: () => T | false | null | undefined,
+  options?: { timeout?: number; interval?: number }
+): T {
+  const timeout = options?.timeout ?? 1000;
+  const start = Date.now();
+
+  for (let attempt = 0; attempt < 100; attempt++) {
+    act(() => { drain(); });
+    drain();
+
+    const result = predicate();
+    if (result !== false && result !== null && result !== undefined) {
+      return result;
+    }
+
+    if (Date.now() - start >= timeout) {
+      throw new Error(`waitFor timed out after ${timeout}ms`);
+    }
+  }
+
+  throw new Error(`waitFor exceeded max attempts`);
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+// Thin re-export from the hermes-test harness runtime.
+// The harness is eval'd before the user bundle, so globalThis.__HT is always available.
+// Users import from 'hermes-test' instead of accessing globalThis directly.
+
+const ht = (globalThis as any).__HT;
+
+// --- Redux test store factories ---
+// withStore: quick identity-reducer store for any state shape
+// withApiStore: configurable RTK Query store factory
+
+function _withTestActions(reducer: (state: any, action: any) => any) {
+  return (state: any, action: any) => {
+    if (action.type === '__SET_STATE__') return action.payload;
+    if (action.type === '__PATCH__') return { ...state, ...action.payload };
+    return reducer(state, action);
+  };
+}
+
+function _makeCtx(store: any) {
+  const React = require('react');
+  const { Provider } = require('react-redux');
+
+  const wrapper = ({ children }: { children: any }) =>
+    React.createElement(Provider, { store } as any, children);
+
+  return {
+    store,
+    wrapper,
+    dispatch: store.dispatch.bind(store),
+    getState: store.getState.bind(store),
+    setState(state: Record<string, any>) { store.dispatch({ type: '__SET_STATE__', payload: state }); },
+    patchState(partial: Record<string, any>) { store.dispatch({ type: '__PATCH__', payload: partial }); },
+    renderHookWithReduxStore<T>(hookFn: (props?: any) => T, options?: { initialProps?: any }) {
+      return ht.renderHook(hookFn, { ...options, wrapper });
+    },
+  };
+}
+
+export function withStore(initialState: Record<string, any> = {}) {
+  const { configureStore } = require('@reduxjs/toolkit');
+  return _makeCtx(configureStore({
+    reducer: _withTestActions((s: any = initialState) => s),
+    preloadedState: initialState,
+    middleware: (gdm: any) => gdm({ serializableCheck: false, immutableCheck: false }),
+  }));
+}
+
+export function withAppReducer(
+  reducer: (state: any, action: any) => any,
+  preloadedState?: Record<string, any>,
+) {
+  const { configureStore } = require('@reduxjs/toolkit');
+  return _makeCtx(configureStore({
+    reducer: _withTestActions(reducer),
+    preloadedState,
+    middleware: (gdm: any) => gdm({ serializableCheck: false, immutableCheck: false }),
+  }));
+}
+
+interface RtkQueryApi {
+  reducer: any;
+  middleware: any;
+  reducerPath: string;
+}
+
+interface SetupApiStoreOptions {
+  middleware?: {
+    prepend?: any[];
+    concat?: any[];
+  };
+  preloadedState?: Record<string, any>;
+}
+
+export function setupApiStore(
+  apis: RtkQueryApi[],
+  extraReducers?: Record<string, any>,
+  options?: SetupApiStoreOptions,
+) {
+  const { configureStore } = require('@reduxjs/toolkit');
+
+  const reducerMap: Record<string, any> = {};
+  for (const api of apis) {
+    reducerMap[api.reducerPath] = api.reducer;
+  }
+  if (extraReducers) Object.assign(reducerMap, extraReducers);
+
+  const store = configureStore({
+    reducer: reducerMap,
+    preloadedState: options?.preloadedState,
+    middleware: (gdm: any) => {
+      let chain = gdm({ serializableCheck: false, immutableCheck: false });
+      for (const a of apis) chain = chain.concat(a.middleware);
+      for (const mw of (options?.middleware?.concat ?? [])) chain = chain.concat(mw);
+      for (const mw of (options?.middleware?.prepend ?? [])) chain = chain.prepend(mw);
+      return chain;
+    },
+  });
+
+  return { ..._makeCtx(store), apis };
+}
+
+export const test = ht.test;
+export const group = ht.group;
+export const expect = ht.expect;
+export const spy = ht.spy;
+export const spyOn = ht.spyOn;
+export const clearAllMocks = ht.clearAllMocks;
+export const beforeEach = ht.beforeEach;
+export const afterEach = ht.afterEach;
+export const beforeAll = ht.beforeAll;
+export const afterAll = ht.afterAll;
+export const renderHook = ht.renderHook;
+export const act = ht.act;
+export const waitFor = ht.waitFor;
+export const mockModule = ht.mockModule;
+export const useMock = ht.useMock;
+export const mockFetch = ht.mockFetch;
+export const mockFetchUse = ht.mockFetchUse;
+export const mockFetchReset = ht.mockFetchReset;
+export const mockFetchClear = ht.mockFetchClear;
+export const http = ht.http;
+export const HttpResponse = ht.HttpResponse;
+export const flushAsync = ht.flushAsync;
+export const useFakeTimers = ht.useFakeTimers;
+export const useRealTimers = ht.useRealTimers;
+export const advanceTimersByTime = ht.advanceTimersByTime;
+export const runAllTimers = ht.runAllTimers;
+export const getTimerCount = ht.getTimerCount;
+export const advanceTimersToNextTimer = ht.advanceTimersToNextTimer;

package/src/mock.ts

@@ -0,0 +1,145 @@
+// useMock — patches module exports for test mocking
+// Works by replacing the getter functions on ESM namespace objects
+//
+// mockModule — jest.mock() equivalent: registers factory in global __HT_mocks
+// so that externalized modules resolve through our mock layer at require() time.
+
+import { spy, type Spy } from './spy';
+
+type SavedDescriptor = { target: any; key: string; desc: PropertyDescriptor };
+let savedDescriptors: SavedDescriptor[] = [];
+
+// --- mockModule: jest.mock() equivalent ---
+// Registers a mock factory for a module path, scoped to the current test file.
+// The bundler wraps mocked module exports in Proxies that check the per-file
+// mock registry at access time. This allows multiple files to mock the same
+// module with different implementations in a single bundle.
+const mockRegistry: Record<string, Record<string, any>> = (globalThis as any).__HT_mocks || {};
+(globalThis as any).__HT_mocks = mockRegistry;
+
+// Per-file mock scoping: __HT_file_mocks[filename][modulePath] = mock
+const fileMocks: Record<string, Record<string, any>> =
+  (globalThis as any).__HT_file_mocks || ((globalThis as any).__HT_file_mocks = {});
+
+// Track patches applied by mockModule so they can be undone between files
+let mockModulePatches: { target: any; key: string; original: any }[] = [];
+
+export function mockModule(
+  modulePath: string,
+  factory: () => Record<string, any>
+): void {
+  const impl = factory();
+  const value = typeof impl === 'function' ? impl : wrapWithSpies(impl);
+
+  // Register in per-file scope only — no global registry pollution
+  const currentFile = (globalThis as any).__currentTestFile || '__global__';
+  if (!fileMocks[currentFile]) fileMocks[currentFile] = {};
+  fileMocks[currentFile][modulePath] = value;
+
+  // Also patch the real module's properties so module-level destructuring picks up
+  // the mock. Example: `const { fn } = api.endpoints` captures at init time — the
+  // Proxy can't intercept it. But if we overwrite `api.endpoints.fn` on the real
+  // object, the destructured `fn` still points to the same object's property.
+  // This covers the case where a hook destructures `{ endpoints }` from a Proxy:
+  //   const { method } = endpoints;  // captured at init
+  // If we patch `endpoints.method = spy`, the captured `method` is updated.
+  //
+  // We look up the real module via __HT_mocks (for externalized) or by requiring
+  // through the shadow wrapper's _getReal().
+  const globalMock = mockRegistry[modulePath];
+  if (globalMock && typeof globalMock === 'object' && typeof value === 'object') {
+    for (const key of Object.keys(value)) {
+      if (key === 'default' || key === '__esModule') continue;
+      try {
+        if (key in globalMock) {
+          mockModulePatches.push({ target: globalMock, key, original: globalMock[key] });
+          globalMock[key] = value[key];
+        }
+      } catch { /* frozen or non-configurable */ }
+    }
+    // Also patch 'default' export if mock provides it
+    if ('default' in value && 'default' in globalMock) {
+      const mockDefault = value['default'];
+      const realDefault = globalMock['default'];
+      if (realDefault && typeof realDefault === 'object' && typeof mockDefault === 'object') {
+        for (const key of Object.keys(mockDefault)) {
+          try {
+            if (key in realDefault) {
+              mockModulePatches.push({ target: realDefault, key, original: realDefault[key] });
+              realDefault[key] = mockDefault[key];
+            }
+          } catch { /* frozen */ }
+        }
+      }
+    }
+  }
+}
+
+// Called between test files to undo mockModule patches and mark
+// source modules for re-initialization (so they re-read from Proxies
+// with the new __currentTestFile).
+export function resetMockModulePatches(): void {
+  for (const { target, key, original } of mockModulePatches) {
+    try { target[key] = original; } catch { /* best effort */ }
+  }
+  mockModulePatches = [];
+
+}
+
+function wrapWithSpies<T extends Record<string, any>>(impl: T): T {
+  const wrapped: any = {};
+  for (const key of Object.keys(impl)) {
+    const value = impl[key];
+    if (typeof value === 'function' && !(value as any)._isSpy) {
+      wrapped[key] = spy(value);
+    } else {
+      wrapped[key] = value;
+    }
+  }
+  return wrapped;
+}
+
+export function useMock<T extends Record<string, any>>(
+  moduleExports: T,
+  implementation: Partial<T>
+): { [K in keyof T]: T[K] extends (...args: any[]) => any ? Spy<T[K]> : T[K] } {
+  const wrapped = wrapWithSpies(implementation as Record<string, any>);
+
+  for (const key of Object.keys(wrapped)) {
+    // Save original descriptor for reset
+    const desc = Object.getOwnPropertyDescriptor(moduleExports, key);
+    if (desc) {
+      savedDescriptors.push({ target: moduleExports, key, desc });
+    }
+
+    // Replace with a getter that returns our mock
+    const mockValue = wrapped[key];
+    try {
+      Object.defineProperty(moduleExports, key, {
+        get: () => mockValue,
+        configurable: true,
+        enumerable: true,
+      });
+    } catch {
+      // If defineProperty fails, try direct assignment as fallback
+      try {
+        (moduleExports as any)[key] = mockValue;
+      } catch {
+        // Module is fully frozen — warn but continue
+      }
+    }
+  }
+
+  return wrapped as any;
+}
+
+export function resetMocks(): void {
+  for (const { target, key, desc } of savedDescriptors) {
+    try {
+      Object.defineProperty(target, key, desc);
+    } catch {
+      // best effort
+    }
+  }
+  savedDescriptors = [];
+}