hermes-test 0.2.4 → 1.0.1

package/src/harness.ts

@@ -1,9 +1,36 @@
 // Polyfills (process, setImmediate) are injected via esbuild banner in bundle.mjs
 // to ensure they run before any bundled dependency (React checks process.env.NODE_ENV at load time)
 
-import { expect } from './expect';
+// Console interceptor — replace console with print()-based output.
+// Hermes's native print() writes to stdout and is always available.
+// This works in all bundle modes (single, split, watch).
+(function() {
+  const p = (globalThis as any).print || (() => {});
+  function fmt(...args: any[]) {
+    return args.map((a: any) => {
+      try { return typeof a === 'string' ? a : JSON.stringify(a, null, 2); }
+      catch { return String(a); }
+    }).join(' ');
+  }
+  (globalThis as any).console = {
+    log: (...args: any[]) => p(fmt(...args)),
+    info: (...args: any[]) => p(fmt(...args)),
+    debug: (...args: any[]) => p(fmt(...args)),
+    warn: (...args: any[]) => p('\x1b[33m⚠ ' + fmt(...args) + '\x1b[0m'),
+    error: (...args: any[]) => {
+      const msg = fmt(...args);
+      // Filter internal framework noise (not actionable by test authors)
+      if (msg.includes('Expected host context to exist')) return;
+      if (msg.includes('An unhandled error occurred processing a request for the endpoint')) return;
+      p('\x1b[31m✗ ' + msg + '\x1b[0m');
+    },
+  };
+})();
+
+import { expect, _setSnapshotContext, getSnapshotCount } from './expect';
 import { spy, spyOn, clearAllMocks } from './spy';
 import { renderHook, act, waitFor } from './hooks';
+import { render, fireEvent } from './render';
 import { useMock, mockModule, resetMocks, resetMockModulePatches } from './mock';
 import { mockFetch, mockFetchUse, mockFetchReset, mockFetchClear, http, HttpResponse } from './fetch';
 import { useFakeTimers, useRealTimers, advanceTimersByTime, runAllTimers, getTimerCount, advanceTimersToNextTimer } from './timers';
@@ -70,6 +97,7 @@ function group(name: string, fn: () => void): void {
   fn();
   currentGroup = prev;
 }
+const describe = group;
 
 function beforeEach(fn: LifecycleHook): void {
   beforeEachHooks.push({ fn, group: currentGroup });
@@ -131,13 +159,14 @@ function flushAsync<T = any>(promise: Promise<T> | T): T {
     (v) => { result = v; settled = true; },
     (e) => { error = e; settled = true; }
   );
-  // Each drain() flushes all current microtasks. We loop because resolved work
-  // may schedule new async work (promise chains, effects, timers). The loop
-  // exits as soon as our promise settles. The cap prevents infinite loops.
-  for (let i = 0; i < 100 && !settled; i++) {
-    drain();
-    // Check timeout during drain loop to catch deadlocked async work
-    checkDeadline();
+  // drainMicrotasks() flushes all pending microtasks. One call should settle
+  // most promises. Loop only as safety net for edge cases (macrotask scheduling).
+  drain();
+  if (!settled) {
+    for (let i = 0; i < 100 && !settled; i++) {
+      drain();
+      checkDeadline();
+    }
   }
   if (!settled) {
     throw new Error('flushAsync: promise did not resolve after 100 drain cycles');
@@ -179,6 +208,97 @@ function _printFileResult(file: string, passed: number, failed: number, duration
   }
 }
 
+/// Format a test error with a clean stack trace and actionable hints.
+/// Works consistently across single-bundle and split-bundle modes.
+function formatTestError(e: any): string {
+  const message = e?.message ?? String(e);
+  const stack = e?.stack as string | undefined;
+  if (!stack) return message;
+
+  // Parse stack into structured frames
+  const frames: { fn: string; file: string; line: string }[] = [];
+  for (const raw of stack.split('\n').slice(1)) {
+    // Hermes format: "at fnName (file:line:col)" or "at file:line:col"
+    const m = raw.match(/at\s+(?:([^\s(]+)\s+\()?([^:)]+):(\d+)/);
+    if (m) frames.push({ fn: m[1] || '', file: m[2], line: m[3] });
+  }
+
+  // Filter to application frames only (skip react internals, harness, native)
+  const skipFn = new Set([
+    'anonymous', 'global', '__init', 'apply', 'map',
+    'react-stack-bottom-frame', 'proxy trap',
+  ]);
+  const skipPrefix = [
+    'render', 'run', 'perform', 'work', 'flush', 'begin', 'update',
+    'reconcile', 'create', 'complete', 'commit', 'process',
+  ];
+  const appFrames = frames.filter(f => {
+    if (skipFn.has(f.fn)) return false;
+    if (f.file.includes('harness') || f.file.includes('runner')) return false;
+    if (f.fn === '' && !f.file.includes('/src/') && !f.file.includes('packages/')) return false;
+    for (const p of skipPrefix) { if (f.fn.startsWith(p)) return false; }
+    return true;
+  });
+
+  // Build clean stack: show source file paths where possible
+  let cleanStack = message;
+  if (appFrames.length > 0) {
+    cleanStack += '\n';
+    for (const f of appFrames.slice(0, 8)) {
+      // esbuild names __esm blocks with source paths like "src/utils/string.ts"
+      const loc = f.fn.includes('/') ? f.fn : (f.fn ? f.fn + ' (' + f.file + ':' + f.line + ')' : f.file + ':' + f.line);
+      cleanStack += '\n    at ' + loc;
+    }
+  }
+
+  // Build hint: resolve the crashing function/module to an ht.mock() suggestion
+  const importMap = (globalThis as any).__HT_shallow_imports;
+  let hint = '';
+
+  for (const f of appFrames) {
+    const fnName = f.fn;
+
+    // Source file path (module init crash): "packages/ui/src/..." or "../../node_modules/@pkg/..."
+    if (fnName.includes('/') && (fnName.includes('.ts') || fnName.includes('.js'))) {
+      const srcPath = fnName.replace(/^(\.\.\/)*/, '');
+      // Extract npm package name from node_modules path
+      const nmMatch = srcPath.match(/node_modules\/((?:@[^/]+\/)?[^/]+)/);
+      if (nmMatch) {
+        const pkg = nmMatch[1];
+        hint = '\n\n  "' + pkg + '" crashed during initialization (native dependency).'
+          + '\n  Add to externals in hermes-test.config.json:\n\n'
+          + '    { "externals": ["' + pkg + '"] }\n'
+          + '\n  Or mock the module that imports it with ht.mock().\n';
+      } else {
+        const cleanPath = srcPath.replace(/\/index\.(tsx?|jsx?)$/, '');
+        hint = '\n\n  Module "' + cleanPath + '" crashed during initialization.'
+          + '\n  A dependency uses an API not available in Hermes.'
+          + '\n  Mock it with ht.mock() or add the native dep to externals.\n';
+      }
+      break;
+    }
+
+    // Function name: resolve via import map
+    if (fnName && fnName.length > 2 && !fnName.includes('(') && importMap) {
+      const modPath = importMap[fnName];
+      if (modPath) {
+        // Collect all exports from this module for a complete mock
+        const siblings: string[] = [];
+        for (const k in importMap) {
+          if (importMap[k] === modPath && siblings.indexOf(k) === -1) siblings.push(k);
+        }
+        const mockBody = siblings.map(s => '    ' + s + ': () => {}').join(',\n');
+        hint = '\n\n  "' + fnName + '" from "' + modPath + '" failed.'
+          + '\n  Add this mock to your test file:\n\n'
+          + "    ht.mock('" + modPath + "', () => ({\n" + mockBody + '\n    }));\n';
+        break;
+      }
+    }
+  }
+
+  return cleanStack + hint;
+}
+
 function runTests(): TestResult[] {
   const results: TestResult[] = [];
   const hasOnly = tests.some((t) => t.options.only);
@@ -217,6 +337,11 @@ function runTests(): TestResult[] {
   for (const entry of tests) {
     // Flush live output when switching to a new file
     if (entry.file !== _currentFile) {
+      // Reset RTK Query API state and drain pending microtasks from
+      // previous file to prevent cross-test contamination.
+      if (_currentFile) {
+        drain();
+      }
       _flushFileResult();
       _currentFile = entry.file;
     }
@@ -237,6 +362,19 @@ function runTests(): TestResult[] {
       }
     }
 
+    // Set up snapshot context for this test
+    {
+      // Use full file path (set by entry code) for correct snapshot directory
+      const filePath = (globalThis as any).__currentTestFilePath || entry.file || 'unknown';
+      // Strip leading ./ if present
+      const clean = filePath.startsWith('./') ? filePath.substring(2) : filePath;
+      const lastSlash = clean.lastIndexOf('/');
+      const dir = lastSlash >= 0 ? clean.substring(0, lastSlash) : '.';
+      const basename = lastSlash >= 0 ? clean.substring(lastSlash + 1) : clean;
+      const snapFile = dir + '/__snapshots__/' + basename + '.snap';
+      _setSnapshotContext(snapFile, entry.name, !!(globalThis as any).__HT_updateSnapshots);
+    }
+
     // Set up timeout for this test
     const timeoutMs = entry.options.timeout ?? DEFAULT_TIMEOUT_MS;
     __testTimeoutMs = timeoutMs;
@@ -267,6 +405,10 @@ function runTests(): TestResult[] {
       // Reset mocks between tests
       resetMocks();
 
+      // Drain all pending microtasks so async effects from this test
+      // don't leak into the next test (RTK Query dispatches, promises, etc.)
+      drain();
+
       // Clear deadline
       __testMaxDrains = 0;
 
@@ -293,12 +435,16 @@ function runTests(): TestResult[] {
       // Reset mocks between tests
       resetMocks();
 
+      // Drain pending microtasks to prevent cross-test contamination
+      drain();
+
       _fileFailed++;
-      _fileFailures.push({ name: entry.name, error: e?.message ?? String(e) });
+      const errMsg = e?.stack ?? e?.message ?? String(e);
+      _fileFailures.push({ name: entry.name, error: errMsg });
       results.push({
         name: entry.name,
         status: 'fail',
-        error: e?.message ?? String(e),
+        error: errMsg,
         duration: Date.now() - start,
         file: entry.file,
       });
@@ -325,9 +471,12 @@ function runTests(): TestResult[] {
 
 // Reset between watch cycles (persistent runtime)
 function registerCrash(file: string, error: string): void {
+  // Error string already has stack from entry.rs (e.stack || e.message).
+  // Parse it through formatTestError for consistent hints.
+  const formatted = formatTestError({ message: error.split('\n')[0], stack: error });
   tests.push({
     name: `[CRASH] ${file}`,
-    fn: () => { throw new Error(error); },
+    fn: () => { throw new Error(formatted); },
     options: {},
     file,
   });
@@ -346,6 +495,28 @@ function resetRegistry(): void {
   resetMockModulePatches();
 }
 
+// --- ht global: ht.mock(path, factory) + ht.mock.fetch / ht.mock.fetch.overwrite / etc. ---
+// Available globally without import, like jest.mock().
+const mock = mockModule as typeof mockModule & {
+  fetch: typeof mockFetch & {
+    overwrite: typeof mockFetchUse;
+    reset: typeof mockFetchReset;
+    clear: typeof mockFetchClear;
+  };
+};
+mock.fetch = mockFetch as typeof mockFetch & {
+  overwrite: typeof mockFetchUse;
+  reset: typeof mockFetchReset;
+  clear: typeof mockFetchClear;
+};
+mock.fetch.overwrite = mockFetchUse;
+mock.fetch.reset = mockFetchReset;
+mock.fetch.clear = mockFetchClear;
+
+const shallow = (_componentPath: string) => {};
+const unmock = (_modulePath: string) => {}; // Bundler directive — no runtime effect
+(globalThis as any).ht = { mock, shallow, unmock };
+
 // Expose to the global scope for the harness entry
 (globalThis as any).__HT = {
   test,
@@ -354,6 +525,7 @@ function resetRegistry(): void {
   spyOn,
   clearAllMocks,
   group,
+  describe,
   beforeEach,
   afterEach,
   beforeAll,
@@ -363,17 +535,15 @@ function resetRegistry(): void {
   act,
   waitFor,
   useMock,
-  mockModule,
-  mockFetch,
-  mockFetchUse,
-  mockFetchReset,
-  mockFetchClear,
   http,
   HttpResponse,
+  render,
+  fireEvent,
   flushAsync,
   registerCrash,
   resetRegistry,
   resetMockModulePatches,
+  getSnapshotCount,
   // Timer control
   useFakeTimers,
   useRealTimers,
@@ -383,4 +553,4 @@ function resetRegistry(): void {
   advanceTimersToNextTimer,
 };
 
-export { test, expect, spy, spyOn, clearAllMocks, group, beforeEach, afterEach, beforeAll, afterAll, renderHook, act, waitFor, useMock, mockModule, mockFetch, mockFetchUse, mockFetchReset, mockFetchClear, http, HttpResponse, flushAsync, useFakeTimers, useRealTimers, advanceTimersByTime, runAllTimers, getTimerCount, advanceTimersToNextTimer };
+export { test, expect, spy, spyOn, clearAllMocks, group, describe, beforeEach, afterEach, beforeAll, afterAll, renderHook, act, waitFor, render, fireEvent, useMock, http, HttpResponse, flushAsync, useFakeTimers, useRealTimers, advanceTimersByTime, runAllTimers, getTimerCount, advanceTimersToNextTimer };

package/src/hooks.ts

@@ -2,8 +2,9 @@
 // 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.
+// react-reconciler is NOT bundled with the harness — it's loaded at runtime
+// from the user's node_modules via globalThis.__HT_Reconciler. This ensures
+// the reconciler always matches the user's React version.
 
 function getReact(): typeof import('react') {
   const R = (globalThis as any).__HT_React;
@@ -11,12 +12,19 @@ function getReact(): typeof import('react') {
   return R;
 }
 
-import Reconciler from 'react-reconciler';
-import { DefaultEventPriority, NoEventPriority } from 'react-reconciler/constants';
+function getReconcilerModule(): any {
+  const R = (globalThis as any).__HT_Reconciler;
+  if (!R) throw new Error('react-reconciler not available. Make sure it is installed (it ships with hermes-test).');
+  return R;
+}
+
+function getReconcilerConstants(): any {
+  return (globalThis as any).__HT_ReconcilerConstants || {};
+}
 
 // Based on mdjastrzebski/test-renderer — the universal-test-renderer for React 19
 // https://github.com/mdjastrzebski/test-renderer
-let currentUpdatePriority: number = NoEventPriority;
+let currentUpdatePriority: number = 0;
 
 const hostConfig = {
   supportsMutation: true,
@@ -25,17 +33,17 @@ const hostConfig = {
   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); },
+  createInstance(type: string, props: any) { const { children: _c, ...rest } = props; return { type, props: rest, children: [] }; },
+  createTextInstance(text: string) { return { type: '__TEXT__', props: {}, text, children: [] }; },
+  appendInitialChild(p: any, c: any) { p.children.push(c); c._parent = p; },
+  appendChild(p: any, c: any) { p.children.push(c); c._parent = p; },
+  appendChildToContainer(p: any, c: any) { p.children.push(c); c._parent = p; },
   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() {},
+  insertBefore(p: any, c: any, b: any) { const i = p.children.indexOf(b); p.children.splice(i, 0, c); c._parent = p; },
+  insertInContainerBefore(p: any, c: any, b: any) { const i = p.children.indexOf(b); p.children.splice(i, 0, c); c._parent = p; },
+  commitUpdate(inst: any, _type: any, _oldProps: any, newProps: any) { const { children: _c, ...rest } = newProps; inst.props = rest; },
+  commitTextUpdate(inst: any, _oldText: string, newText: string) { inst.text = newText; },
   commitMount() {},
   prepareForCommit() { return null; },
   resetAfterCommit() {},
@@ -51,10 +59,10 @@ const hostConfig = {
   cancelTimeout: (globalThis as any).clearTimeout || (() => {}),
   noTimeout: -1,
   scheduleMicrotask: typeof queueMicrotask === 'function' ? queueMicrotask : (fn: any) => Promise.resolve().then(fn),
-  getCurrentEventPriority() { return DefaultEventPriority; },
+  getCurrentEventPriority() { return getReconcilerConstants().DefaultEventPriority ?? 0; },
   setCurrentUpdatePriority(priority: number) { currentUpdatePriority = priority; },
   getCurrentUpdatePriority() { return currentUpdatePriority; },
-  resolveUpdatePriority() { return currentUpdatePriority || DefaultEventPriority; },
+  resolveUpdatePriority() { return currentUpdatePriority || (getReconcilerConstants().DefaultEventPriority ?? 0); },
   shouldAttemptEagerTransition() { return false; },
   trackSchedulerEvent() {},
   resolveEventType() { return ''; },
@@ -80,8 +88,9 @@ const hostConfig = {
   preparePortalMount() {},
 };
 
-function createReconciler() {
-  const create = typeof Reconciler === 'function' ? Reconciler : (Reconciler as any).default;
+export function createReconciler() {
+  const Reconciler = getReconcilerModule();
+  const create = typeof Reconciler === 'function' ? Reconciler : Reconciler.default;
   return create(hostConfig);
 }
 
@@ -100,8 +109,10 @@ function flush() {
   drain();
 }
 
-// Enable React.act() support
-(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+// React act() environment — same pattern as React Testing Library.
+// true inside act() → React processes updates and can warn about missing act.
+// false outside act() → React doesn't warn about async state updates.
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = false;
 
 export function act(fn: () => void | Promise<void>): void {
   const React = getReact();
@@ -112,22 +123,31 @@ export function act(fn: () => void | Promise<void>): void {
     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++) {
+  const prev = (globalThis as any).IS_REACT_ACT_ENVIRONMENT;
+  (globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+  try {
+    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; }
+        );
         drain();
+        if (error) throw error;
       }
-      if (error) throw error;
-    }
-  });
-  flush();
+    });
+    // Restore env BEFORE flush so async effects resolved by flush
+    // don't trigger "not wrapped in act" warnings
+    (globalThis as any).IS_REACT_ACT_ENVIRONMENT = prev;
+    flush();
+  } catch (error) {
+    (globalThis as any).IS_REACT_ACT_ENVIRONMENT = prev;
+    throw error;
+  }
 }
 
 export function renderHook<T>(

package/src/index.ts

@@ -101,6 +101,7 @@ export function setupApiStore(
 
 export const test = ht.test;
 export const group = ht.group;
+export const describe = ht.describe;
 export const expect = ht.expect;
 export const spy = ht.spy;
 export const spyOn = ht.spyOn;
@@ -112,14 +113,11 @@ 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 render = ht.render;
+export const fireEvent = ht.fireEvent;
 export const flushAsync = ht.flushAsync;
 export const useFakeTimers = ht.useFakeTimers;
 export const useRealTimers = ht.useRealTimers;

package/src/mock.ts

@@ -1,7 +1,7 @@
 // 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
+// mock() — 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';
@@ -9,7 +9,7 @@ import { spy, type Spy } from './spy';
 type SavedDescriptor = { target: any; key: string; desc: PropertyDescriptor };
 let savedDescriptors: SavedDescriptor[] = [];
 
-// --- mockModule: jest.mock() equivalent ---
+// --- mock(): 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
@@ -21,7 +21,7 @@ const mockRegistry: Record<string, Record<string, any>> = (globalThis as any).__
 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
+// Track patches applied by mock() so they can be undone between files
 let mockModulePatches: { target: any; key: string; original: any }[] = [];
 
 export function mockModule(
@@ -75,7 +75,7 @@ export function mockModule(
   }
 }
 
-// Called between test files to undo mockModule patches and mark
+// Called between test files to undo mock() patches and mark
 // source modules for re-initialization (so they re-read from Proxies
 // with the new __currentTestFile).
 export function resetMockModulePatches(): void {