hermes-test 0.2.0

package/src/shims/tanstack-query.js

@@ -0,0 +1,68 @@
+// hermes-test shim for @tanstack/react-query
+//
+// Transparent wrapper with test-friendly defaults. Ensures single-instance
+// resolution and provides auto-cleanup tracking for QueryClient instances.
+//
+// Usage in hermes-test.config.json:
+//   "shims": { "@tanstack/react-query": "hermes-test/shims/tanstack-query" }
+
+var real = require('@__ht_real_pkg/@tanstack/react-query');
+
+// Re-export everything unchanged
+var mod = {};
+var keys = Object.getOwnPropertyNames(real);
+for (var i = 0; i < keys.length; i++) {
+  if (keys[i] !== 'QueryClient') mod[keys[i]] = real[keys[i]];
+}
+
+// Track QueryClient instances for between-test cleanup
+var _clients = [];
+globalThis.__HT_queryClients = _clients;
+
+var OrigQueryClient = real.QueryClient;
+
+// Wrapper that applies test-friendly defaults
+function QueryClient(opts) {
+  var config = opts || {};
+  var defaults = config.defaultOptions || {};
+  var queries = defaults.queries || {};
+
+  // Disable retries by default in tests (prevents timeouts)
+  if (queries.retry === undefined) queries.retry = false;
+
+  defaults.queries = queries;
+  config.defaultOptions = defaults;
+
+  var client = new OrigQueryClient(config);
+  _clients.push(client);
+  return client;
+}
+
+// Preserve prototype chain so instanceof checks work
+QueryClient.prototype = OrigQueryClient.prototype;
+
+mod.QueryClient = QueryClient;
+
+// withQueryClient — test context factory (same pattern as withStore for Redux)
+mod.withQueryClient = function withQueryClient(opts) {
+  var config = opts || {};
+  var client = new mod.QueryClient(config);
+  var React = require('react');
+  var QCP = mod.QueryClientProvider;
+
+  var wrapper = function(props) {
+    return React.createElement(QCP, { client: client }, props.children);
+  };
+
+  var renderHook = require('hermes-test').renderHook;
+
+  return {
+    queryClient: client,
+    wrapper: wrapper,
+    renderHookWithQuery: function(hookFn, hookOpts) {
+      return renderHook(hookFn, Object.assign({}, hookOpts, { wrapper: wrapper }));
+    },
+  };
+};
+
+module.exports = mod;

package/src/spy.ts

@@ -0,0 +1,160 @@
+export type Spy<F extends (...args: any[]) => any = (...args: any[]) => any> =
+  F & {
+    readonly calls: ReadonlyArray<Parameters<F>>;
+    readonly callCount: number;
+    readonly returnValues: ReadonlyArray<ReturnType<F>>;
+    reset(): void;
+
+    // Core
+    setImpl(impl: F): void;
+    returns(value: ReturnType<F>): Spy<F>;
+
+    // Jest-compatible API
+    mockImplementation(fn: F): Spy<F>;
+    mockImplementationOnce(fn: F): Spy<F>;
+    mockReturnValue(value: ReturnType<F>): Spy<F>;
+    mockReturnValueOnce(value: ReturnType<F>): Spy<F>;
+    mockResolvedValue(value: any): Spy<F>;
+    mockResolvedValueOnce(value: any): Spy<F>;
+    mockRejectedValue(value: any): Spy<F>;
+    mockRejectedValueOnce(value: any): Spy<F>;
+    mockClear(): void;
+    mockReset(): void;
+    mockRestore(): void;
+
+    // spyOn support
+    _restore?: () => void;
+    _isSpy: true;
+  };
+
+// Registry of all spies created — clearAllMocks() clears them all at once.
+const _allSpies: Spy[] = [];
+
+export function clearAllMocks(): void {
+  for (const s of _allSpies) s.mockClear();
+}
+
+export function spy<F extends (...args: any[]) => any = () => void>(
+  impl?: F
+): Spy<F> {
+  let baseImpl: F | undefined = impl;
+  const onceImpls: F[] = []; // FIFO queue for mockImplementationOnce/mockReturnValueOnce
+  const calls: any[][] = [];
+  const returnValues: any[] = [];
+
+  const fn = function (this: any, ...args: any[]) {
+    calls.push(args);
+
+    // Once-implementations take priority (FIFO)
+    let ret: any;
+    if (onceImpls.length > 0) {
+      const onceFn = onceImpls.shift()!;
+      ret = onceFn.apply(this, args);
+    } else {
+      ret = baseImpl ? baseImpl.apply(this, args) : undefined;
+    }
+
+    returnValues.push(ret);
+    return ret;
+  } as unknown as Spy<F>;
+
+  Object.defineProperties(fn, {
+    calls: { get: () => calls },
+    callCount: { get: () => calls.length },
+    returnValues: { get: () => returnValues },
+    _isSpy: { value: true },
+  });
+
+  // --- Core API ---
+
+  (fn as any).reset = () => {
+    calls.length = 0;
+    returnValues.length = 0;
+    onceImpls.length = 0;
+  };
+
+  (fn as any).setImpl = (newImpl: F) => {
+    baseImpl = newImpl;
+    return fn;
+  };
+
+  (fn as any).returns = (value: any) => {
+    baseImpl = (() => value) as any;
+    return fn;
+  };
+
+  // --- Jest-compatible API ---
+
+  (fn as any).mockImplementation = (newImpl: F) => {
+    baseImpl = newImpl;
+    return fn;
+  };
+
+  (fn as any).mockImplementationOnce = (onceFn: F) => {
+    onceImpls.push(onceFn);
+    return fn;
+  };
+
+  (fn as any).mockReturnValue = (value: any) => {
+    baseImpl = (() => value) as any;
+    return fn;
+  };
+
+  (fn as any).mockReturnValueOnce = (value: any) => {
+    onceImpls.push((() => value) as any);
+    return fn;
+  };
+
+  (fn as any).mockResolvedValue = (value: any) => {
+    baseImpl = (() => Promise.resolve(value)) as any;
+    return fn;
+  };
+
+  (fn as any).mockResolvedValueOnce = (value: any) => {
+    onceImpls.push((() => Promise.resolve(value)) as any);
+    return fn;
+  };
+
+  (fn as any).mockRejectedValue = (value: any) => {
+    baseImpl = (() => Promise.reject(value)) as any;
+    return fn;
+  };
+
+  (fn as any).mockRejectedValueOnce = (value: any) => {
+    onceImpls.push((() => Promise.reject(value)) as any);
+    return fn;
+  };
+
+  (fn as any).mockClear = () => {
+    calls.length = 0;
+    returnValues.length = 0;
+    onceImpls.length = 0;
+  };
+
+  (fn as any).mockReset = () => {
+    calls.length = 0;
+    returnValues.length = 0;
+    onceImpls.length = 0;
+    baseImpl = undefined;
+  };
+
+  (fn as any).mockRestore = () => {
+    (fn as any).mockReset();
+    if ((fn as any)._restore) (fn as any)._restore();
+  };
+
+  _allSpies.push(fn);
+  return fn;
+}
+
+// --- spyOn: replace a method on an object with a spy, preserving original ---
+export function spyOn<T extends Record<string, any>>(
+  obj: T,
+  method: keyof T & string,
+): Spy {
+  const original = obj[method];
+  const s = spy(typeof original === 'function' ? original.bind(obj) : undefined);
+  (s as any)._restore = () => { obj[method] = original; };
+  obj[method] = s as any;
+  return s;
+}

package/src/store.ts

@@ -0,0 +1,114 @@
+// hermes-test/store — Redux test store factories
+//
+// setupApiStore: thin wrapper matching Jest's setupApiStore pattern
+// withStore: quick identity-reducer store for any state shape
+// withAppReducer: real app reducer with patchState + real actions
+
+import React from 'react';
+import { Provider } from 'react-redux';
+import { configureStore } from '@reduxjs/toolkit';
+
+type StoreContext = {
+  store: any;
+  wrapper: any;
+  dispatch: (action: any) => any;
+  getState: () => any;
+  setState: (state: Record<string, any>) => void;
+  patchState: (partial: Record<string, any>) => void;
+  renderHookWithReduxStore: <T>(hookFn: (props?: any) => T, options?: { initialProps?: any }) => any;
+};
+
+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): StoreContext {
+  const { renderHook } = require('hermes-test');
+
+  const wrapper = ({ children }: { children: React.ReactNode }) =>
+    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 renderHook(hookFn, { ...options, wrapper });
+    },
+  };
+}
+
+/** Quick store from plain state object — identity reducer, any shape */
+export function withStore(initialState: Record<string, any> = {}): StoreContext {
+  return makeCtx(configureStore({
+    reducer: withTestActions((s: any = initialState) => s),
+    preloadedState: initialState,
+    middleware: (gdm) => gdm({ serializableCheck: false, immutableCheck: false }),
+  }));
+}
+
+/** Real app reducer — patchState + real actions both work */
+export function withAppReducer(
+  reducer: (state: any, action: any) => any,
+  preloadedState?: Record<string, any>,
+): StoreContext {
+  return makeCtx(configureStore({
+    reducer: withTestActions(reducer),
+    preloadedState,
+    middleware: (gdm) => gdm({ serializableCheck: false, immutableCheck: false }),
+  }));
+}
+
+interface RtkQueryApi {
+  reducer: any;
+  middleware: any;
+  reducerPath: string;
+}
+
+export interface SetupApiStoreOptions {
+  middleware?: {
+    prepend?: any[];
+    concat?: any[];
+  };
+  preloadedState?: Record<string, any>;
+}
+
+/**
+ * Thin store factory matching Jest's setupApiStore pattern.
+ *
+ * setupApiStore([api, cms], { app: rootReducer })
+ * setupApiStore([api], { app: rootReducer }, { middleware: { prepend: [myMw] } })
+ * setupApiStore([api], { app: rootReducer }, { preloadedState: { app: { auth: { ... } } } })
+ */
+export function setupApiStore(
+  apis: RtkQueryApi[],
+  extraReducers?: Record<string, any>,
+  options?: SetupApiStoreOptions,
+) {
+  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) => {
+      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 };
+}

package/src/timers.ts

@@ -0,0 +1,141 @@
+// Fake timer control for deterministic testing.
+//
+// Usage:
+//   useFakeTimers();
+//   setTimeout(fn, 1000);
+//   advanceTimersByTime(1000); // fn fires synchronously
+//   useRealTimers();
+
+// Save the real Date.now function REFERENCE before useFakeTimers can overwrite it.
+// useFakeTimers does `globalThis.Date.now = () => fakeNow` which mutates the original
+// Date object's .now property. So we must save the function itself, not the constructor.
+const _savedDateNow: () => number = Date.now;
+export function realDateNow(): number { return _savedDateNow(); }
+
+interface PendingTimer {
+  id: number;
+  fn: () => void;
+  delay: number;
+  fireAt: number;
+  type: 'timeout' | 'interval';
+  interval: number;
+}
+
+let fakeNow = 0;
+let nextId = 1;
+let pending: PendingTimer[] = [];
+let isFake = false;
+
+// Save originals
+const _setTimeout = (globalThis as any).setTimeout;
+const _clearTimeout = (globalThis as any).clearTimeout;
+const _setInterval = (globalThis as any).setInterval;
+const _clearInterval = (globalThis as any).clearInterval;
+const _Date = globalThis.Date;
+
+function fakeSetTimeout(fn: () => void, delay: number = 0): number {
+  const id = nextId++;
+  pending.push({ id, fn, delay, fireAt: fakeNow + delay, type: 'timeout', interval: 0 });
+  return id;
+}
+
+function fakeClearTimeout(id: number) {
+  pending = pending.filter(t => t.id !== id);
+}
+
+function fakeSetInterval(fn: () => void, delay: number): number {
+  const id = nextId++;
+  pending.push({ id, fn, delay, fireAt: fakeNow + delay, type: 'interval', interval: delay });
+  return id;
+}
+
+function fakeClearInterval(id: number) {
+  pending = pending.filter(t => t.id !== id);
+}
+
+export function useFakeTimers(initialTime?: number) {
+  fakeNow = initialTime ?? 0;
+  nextId = 1;
+  pending = [];
+  isFake = true;
+
+  (globalThis as any).setTimeout = fakeSetTimeout;
+  (globalThis as any).clearTimeout = fakeClearTimeout;
+  (globalThis as any).setInterval = fakeSetInterval;
+  (globalThis as any).clearInterval = fakeClearInterval;
+
+  // Override Date.now()
+  (globalThis as any).Date = function (...args: any[]) {
+    if (args.length === 0) return new _Date(fakeNow);
+    return new (_Date as any)(...args);
+  } as any;
+  (globalThis as any).Date.now = () => fakeNow;
+  (globalThis as any).Date.parse = _Date.parse;
+  (globalThis as any).Date.UTC = _Date.UTC;
+  // Copy prototype so instanceof checks and methods still work
+  (globalThis as any).Date.prototype = _Date.prototype;
+}
+
+export function useRealTimers() {
+  isFake = false;
+  pending = [];
+  (globalThis as any).setTimeout = _setTimeout;
+  (globalThis as any).clearTimeout = _clearTimeout;
+  (globalThis as any).setInterval = _setInterval;
+  (globalThis as any).clearInterval = _clearInterval;
+  (globalThis as any).Date = _Date;
+}
+
+export function advanceTimersByTime(ms: number) {
+  if (!isFake) throw new Error('advanceTimersByTime called without useFakeTimers()');
+  const target = fakeNow + ms;
+
+  while (fakeNow < target) {
+    // Find next timer to fire
+    const ready = pending.filter(t => t.fireAt <= target).sort((a, b) => a.fireAt - b.fireAt);
+    if (ready.length === 0) {
+      fakeNow = target;
+      break;
+    }
+
+    const timer = ready[0];
+    fakeNow = timer.fireAt;
+
+    if (timer.type === 'timeout') {
+      pending = pending.filter(t => t.id !== timer.id);
+      timer.fn();
+    } else {
+      // interval: fire and reschedule
+      timer.fireAt += timer.interval;
+      timer.fn();
+    }
+  }
+
+  fakeNow = target;
+}
+
+export function runAllTimers() {
+  if (!isFake) throw new Error('runAllTimers called without useFakeTimers()');
+  let safety = 1000;
+  while (pending.length > 0 && safety-- > 0) {
+    const next = pending.reduce((min, t) => t.fireAt < min.fireAt ? t : min);
+    fakeNow = next.fireAt;
+    if (next.type === 'timeout') {
+      pending = pending.filter(t => t.id !== next.id);
+      next.fn();
+    } else {
+      next.fireAt += next.interval;
+      next.fn();
+    }
+  }
+}
+
+export function getTimerCount(): number {
+  return pending.length;
+}
+
+export function advanceTimersToNextTimer() {
+  if (!isFake || pending.length === 0) return;
+  const next = pending.reduce((min, t) => t.fireAt < min.fireAt ? t : min);
+  advanceTimersByTime(next.fireAt - fakeNow);
+}

package/store.d.ts

@@ -0,0 +1,43 @@
+// Type declarations for hermes-test/store
+
+import type React from 'react';
+
+export interface StoreContext {
+  readonly store: any;
+  readonly wrapper: React.ComponentType<{ children: React.ReactNode }>;
+  dispatch(action: unknown): unknown;
+  getState(): unknown;
+  setState(state: Record<string, unknown>): void;
+  patchState(partial: Record<string, unknown>): void;
+  renderHookWithReduxStore<T>(
+    hookFn: (props?: unknown) => T,
+    options?: { initialProps?: unknown },
+  ): import('./index').HookResult<T>;
+}
+
+export interface SetupApiStoreOptions {
+  middleware?: {
+    prepend?: unknown[];
+    concat?: unknown[];
+  };
+  preloadedState?: Record<string, unknown>;
+}
+
+export interface RtkQueryApi {
+  reducer: unknown;
+  middleware: unknown;
+  reducerPath: string;
+}
+
+export function setupApiStore(
+  apis: RtkQueryApi[],
+  extraReducers?: Record<string, unknown>,
+  options?: SetupApiStoreOptions,
+): StoreContext & { apis: RtkQueryApi[] };
+
+export function withStore(initialState?: Record<string, unknown>): StoreContext;
+
+export function withAppReducer(
+  reducer: (state: unknown, action: unknown) => unknown,
+  preloadedState?: Record<string, unknown>,
+): StoreContext;