@quake2ts/test-utils 0.0.1

package/src/setup/storage.ts

@@ -0,0 +1,60 @@
+/**
+ * Helper to create a storage-like object (localStorage/sessionStorage).
+ */
+function createStorageMock(initialData: Record<string, string> = {}): Storage {
+  const store = new Map<string, string>(Object.entries(initialData));
+
+  return {
+    getItem: (key: string) => store.get(key) || null,
+    setItem: (key: string, value: string) => store.set(key, value.toString()),
+    removeItem: (key: string) => store.delete(key),
+    clear: () => store.clear(),
+    key: (index: number) => Array.from(store.keys())[index] || null,
+    get length() { return store.size; }
+  } as Storage;
+}
+
+/**
+ * Creates a mock LocalStorage instance.
+ */
+export function createMockLocalStorage(initialData: Record<string, string> = {}): Storage {
+  return createStorageMock(initialData);
+}
+
+/**
+ * Creates a mock SessionStorage instance.
+ */
+export function createMockSessionStorage(initialData: Record<string, string> = {}): Storage {
+  return createStorageMock(initialData);
+}
+
+/**
+ * Creates a mock IndexedDB factory.
+ * Wraps fake-indexeddb.
+ */
+export function createMockIndexedDB(databases?: IDBDatabase[]): IDBFactory {
+  // fake-indexeddb/auto already sets global.indexedDB
+  // If we need to return a specific instance or customized one, we can do it here.
+  // For now, return the global one or a fresh 'fake-indexeddb' instance if we were to import it directly.
+
+  // Since we imported 'fake-indexeddb/auto' in setup/browser.ts, global.indexedDB is already mocked.
+  // We can return that.
+  return global.indexedDB;
+}
+
+export interface StorageScenario {
+  localStorage: Storage;
+  sessionStorage: Storage;
+  indexedDB: IDBFactory;
+}
+
+/**
+ * Creates a complete storage test scenario.
+ */
+export function createStorageTestScenario(storageType: 'local' | 'session' | 'indexed' = 'local'): StorageScenario {
+  return {
+    localStorage: createMockLocalStorage(),
+    sessionStorage: createMockSessionStorage(),
+    indexedDB: createMockIndexedDB()
+  };
+}

package/src/setup/timing.ts

@@ -0,0 +1,142 @@
+/**
+ * Interface for the mock RequestAnimationFrame implementation.
+ */
+export interface MockRAF {
+  /**
+   * Advances time by one tick (simulating one frame).
+   * @param time Timestamp to pass to callbacks (default: calls Date.now())
+   */
+  tick(time?: number): void;
+  /**
+   * Advances time by a specific amount, triggering multiple frames if necessary.
+   * Not fully implemented in simple version, acts as alias to tick() with specific time.
+   */
+  advance(ms: number): void;
+  /**
+   * Returns current pending callbacks.
+   */
+  getCallbacks(): Array<{id: number, callback: FrameRequestCallback}>;
+}
+
+/**
+ * Creates a mock RequestAnimationFrame implementation.
+ * Replaces global.requestAnimationFrame and cancelAnimationFrame.
+ */
+export function createMockRAF(): MockRAF {
+  let callbacks: Array<{id: number, callback: FrameRequestCallback}> = [];
+  let lastId = 0;
+  let currentTime = 0;
+
+  const originalRAF = global.requestAnimationFrame;
+  const originalCancelRAF = global.cancelAnimationFrame;
+
+  global.requestAnimationFrame = (callback: FrameRequestCallback): number => {
+    lastId++;
+    callbacks.push({ id: lastId, callback });
+    return lastId;
+  };
+
+  global.cancelAnimationFrame = (id: number): void => {
+    callbacks = callbacks.filter(cb => cb.id !== id);
+  };
+
+  return {
+    tick(time?: number) {
+      if (time) currentTime = time;
+      else currentTime += 16.66; // ~60fps
+
+      const currentCallbacks = [...callbacks];
+      callbacks = []; // Clear before execution to allow re-scheduling
+
+      currentCallbacks.forEach(cb => cb.callback(currentTime));
+    },
+    advance(ms: number) {
+      // Simple implementation: just advance time and process one batch
+      // For more complex simulation, we might loop
+      currentTime += ms;
+      this.tick(currentTime);
+    },
+    getCallbacks() {
+      return callbacks;
+    }
+  };
+}
+
+/**
+ * Creates a mock Performance object.
+ */
+export function createMockPerformance(startTime: number = 0): Performance {
+  let now = startTime;
+
+  const mockPerformance = {
+    now: () => now,
+    timeOrigin: startTime,
+    timing: {
+      navigationStart: startTime,
+    },
+    mark: (_name: string) => {},
+    measure: (_name: string, _start: string, _end: string) => {},
+    getEntries: () => [],
+    getEntriesByName: (_name: string) => [],
+    getEntriesByType: (_type: string) => [],
+    clearMarks: (_name?: string) => {},
+    clearMeasures: (_name?: string) => {},
+    clearResourceTimings: () => {},
+    setResourceTimingBufferSize: (_maxSize: number) => {},
+    onresourcetimingbufferfull: null,
+    toJSON: () => ({})
+  } as unknown as Performance;
+
+  // Polyfill global if needed, or return for injection
+  if (typeof global.performance === 'undefined') {
+      global.performance = mockPerformance;
+  }
+
+  return mockPerformance;
+}
+
+export interface ControlledTimer {
+  /**
+   * Advances virtual time by ms.
+   */
+  advanceBy(ms: number): void;
+  /**
+   * Runs all pending timers.
+   */
+  runAll(): void;
+  /**
+   * Restores original timer functions.
+   */
+  clear(): void;
+}
+
+/**
+ * Creates controlled timers (setTimeout/setInterval).
+ * Note: Use verify's useFakeTimers() for better integration with test runner.
+ * This is a lightweight alternative or specific helper.
+ */
+export function createControlledTimer(): ControlledTimer {
+    // This functionality is best provided by vitest/jest directly via vi.useFakeTimers()
+    // Wrapping it here for convenience if needed, but for now we'll recommend `vi`.
+    console.warn('createControlledTimer: Recommend using vi.useFakeTimers() instead.');
+
+    return {
+        advanceBy: (ms: number) => { /* delegate to vi.advanceTimersByTime(ms) in consumer */ },
+        runAll: () => { /* delegate to vi.runAllTimers() */ },
+        clear: () => { /* delegate to vi.useRealTimers() */ }
+    };
+}
+
+/**
+ * Simulates multiple RAF frames.
+ */
+export function simulateFrames(count: number, frameTime: number = 16, callback?: (frameIndex: number) => void): void {
+  for (let i = 0; i < count; i++) {
+    // If using the global mock RAF from createMockRAF, we just rely on callbacks being scheduled.
+    // However, if we need to manually trigger them, we assume existing RAF loop.
+    // This helper assumes a synchronous execution where we can just wait or tick.
+    // With `vi.useFakeTimers()`, we would `vi.advanceTimersByTime(frameTime)`.
+
+    if (callback) callback(i);
+  }
+}

package/src/setup/webgl.ts

@@ -0,0 +1,8 @@
+import { createMockWebGL2Context } from '../engine/mocks/webgl.js';
+
+// Re-export for compatibility during migration
+// But actually we prefer to use the one from engine/mocks/webgl.ts
+// This file is kept if necessary for backward compatibility of file path imports
+// but the implementation is now delegating to the consolidated one.
+
+export { createMockWebGL2Context };

package/src/setup/webgpu.ts

@@ -0,0 +1,113 @@
+
+// Types for our setup
+export interface HeadlessWebGPUSetup {
+  adapter: GPUAdapter;
+  device: GPUDevice;
+  cleanup: () => Promise<void>;
+}
+
+export interface WebGPUContextState {
+    adapter: GPUAdapter;
+    device: GPUDevice;
+    queue: GPUQueue;
+    format: GPUTextureFormat;
+}
+
+/**
+ * Initialize WebGPU in a headless Node.js environment using @webgpu/dawn (via webgpu package)
+ */
+export async function initHeadlessWebGPU(
+  options?: {
+    powerPreference?: 'low-power' | 'high-performance';
+    requiredFeatures?: GPUFeatureName[];
+  }
+): Promise<HeadlessWebGPUSetup> {
+  // Check if we are in Node.js environment
+  if (typeof process === 'undefined' || process.release?.name !== 'node') {
+    throw new Error('initHeadlessWebGPU should only be called in a Node.js environment');
+  }
+
+  // Dynamic import to avoid hard dependency
+  let create, globals;
+  try {
+      const webgpu = await import('webgpu');
+      create = webgpu.create;
+      globals = webgpu.globals;
+  } catch (e) {
+      throw new Error(`Failed to load "webgpu" package. Please ensure it is installed. Original error: ${e}`);
+  }
+
+  // Inject WebGPU globals into globalThis if not already present
+  // Note: we need to handle navigator specifically as it might be read-only in some envs (like jsdom)
+  // or simply missing.
+  if (!globalThis.navigator) {
+      // @ts-ignore
+      globalThis.navigator = {};
+  }
+
+  if (!globalThis.navigator.gpu) {
+      // Create the GPU instance using the 'webgpu' package's create function
+      // This is more robust than relying on 'globals' if 'globals' expects a clean environment
+      const gpu = create([]);
+
+      try {
+          Object.defineProperty(globalThis.navigator, 'gpu', {
+              value: gpu,
+              writable: true,
+              configurable: true
+          });
+      } catch (e) {
+          // Fallback if defineProperty fails (e.g. read-only navigator in strict mode)
+          // But usually in tests we can modify it.
+          // If we are in JSDOM, navigator might be tricky.
+          console.warn('Could not define navigator.gpu, trying direct assignment');
+          // @ts-ignore
+          globalThis.navigator.gpu = gpu;
+      }
+
+      // Also inject other globals like GPUAdapter, GPUDevice etc.
+      Object.assign(globalThis, globals);
+  }
+
+  // Request Adapter
+  const adapter = await navigator.gpu.requestAdapter({
+    powerPreference: options?.powerPreference || 'high-performance',
+  });
+
+  if (!adapter) {
+    throw new Error('Failed to create WebGPU adapter');
+  }
+
+  // Request Device
+  const device = await adapter.requestDevice({
+    requiredFeatures: options?.requiredFeatures || [],
+  });
+
+  if (!device) {
+    throw new Error('Failed to create WebGPU device');
+  }
+
+  return {
+    adapter,
+    device,
+    cleanup: async () => {
+      device.destroy();
+      // 'webgpu' package doesn't expose a way to explicitly destroy the adapter or the global instance
+      // cleanly other than letting it be garbage collected or process exit.
+      // However, destroying the device is usually sufficient for tests.
+    }
+  };
+}
+
+/**
+ * Creates a complete context state for testing
+ */
+export async function createHeadlessTestContext(): Promise<WebGPUContextState> {
+    const { adapter, device } = await initHeadlessWebGPU();
+    return {
+        adapter,
+        device,
+        queue: device.queue,
+        format: 'rgba8unorm'
+    };
+}

package/src/shared/bsp.ts

@@ -0,0 +1,145 @@
+import {
+  computePlaneSignBits,
+  type CollisionBrush,
+  type CollisionModel,
+  type CollisionPlane,
+  type CollisionNode,
+  type CollisionLeaf,
+  CONTENTS_SOLID,
+  type Vec3
+} from '@quake2ts/shared';
+
+/**
+ * Creates a collision plane with the specified normal and distance.
+ * Automatically calculates the plane type and signbits.
+ *
+ * @param normal - The normal vector of the plane.
+ * @param dist - The distance from the origin.
+ * @returns A CollisionPlane object.
+ */
+export function makePlane(normal: Vec3, dist: number): CollisionPlane {
+  return {
+    normal,
+    dist,
+    type: Math.abs(normal.x) === 1 ? 0 : Math.abs(normal.y) === 1 ? 1 : Math.abs(normal.z) === 1 ? 2 : 3,
+    signbits: computePlaneSignBits(normal),
+  };
+}
+
+/**
+ * Creates a simple axis-aligned cubic brush for testing.
+ *
+ * @param size - The size of the cube (width, height, depth).
+ * @param contents - The content flags for the brush (default: CONTENTS_SOLID).
+ * @returns A CollisionBrush object.
+ */
+export function makeAxisBrush(size: number, contents = CONTENTS_SOLID): CollisionBrush {
+  const half = size / 2;
+  const planes = [
+    makePlane({ x: 1, y: 0, z: 0 }, half),
+    makePlane({ x: -1, y: 0, z: 0 }, half),
+    makePlane({ x: 0, y: 1, z: 0 }, half),
+    makePlane({ x: 0, y: -1, z: 0 }, half),
+    makePlane({ x: 0, y: 0, z: 1 }, half),
+    makePlane({ x: 0, y: 0, z: -1 }, half),
+  ];
+
+  return {
+    contents,
+    sides: planes.map((plane) => ({ plane, surfaceFlags: 0 })),
+  };
+}
+
+/**
+ * Creates a BSP node.
+ *
+ * @param plane - The splitting plane for this node.
+ * @param children - Indices of the children (positive for nodes, negative for leaves).
+ * @returns A CollisionNode object.
+ */
+export function makeNode(plane: CollisionPlane, children: [number, number]): CollisionNode {
+  return { plane, children };
+}
+
+/**
+ * Constructs a full CollisionModel from components.
+ *
+ * @param planes - Array of planes.
+ * @param nodes - Array of nodes.
+ * @param leaves - Array of leaves.
+ * @param brushes - Array of brushes.
+ * @param leafBrushes - Array of leaf brush indices.
+ * @returns A CollisionModel object.
+ */
+export function makeBspModel(
+  planes: CollisionPlane[],
+  nodes: CollisionNode[],
+  leaves: CollisionLeaf[],
+  brushes: CollisionBrush[],
+  leafBrushes: number[]
+): CollisionModel {
+  return {
+    planes,
+    nodes,
+    leaves,
+    brushes,
+    leafBrushes,
+    bmodels: [],
+  };
+}
+
+/**
+ * Creates a BSP leaf.
+ *
+ * @param contents - The content flags for this leaf.
+ * @param firstLeafBrush - Index into the leafBrushes array.
+ * @param numLeafBrushes - Number of brushes in this leaf.
+ * @returns A CollisionLeaf object.
+ */
+export function makeLeaf(contents: number, firstLeafBrush: number, numLeafBrushes: number): CollisionLeaf {
+  return { contents, cluster: 0, area: 0, firstLeafBrush, numLeafBrushes };
+}
+
+/**
+ * Creates a simplified CollisionModel consisting of a single leaf containing the provided brushes.
+ * Useful for testing collision against a set of brushes without full BSP tree traversal.
+ *
+ * @param brushes - Array of CollisionBrushes to include.
+ * @returns A CollisionModel object.
+ */
+export function makeLeafModel(brushes: CollisionBrush[]): CollisionModel {
+  const planes = brushes.flatMap((brush) => brush.sides.map((side) => side.plane));
+
+  return {
+    planes,
+    nodes: [],
+    leaves: [makeLeaf(0, 0, brushes.length)],
+    brushes,
+    leafBrushes: brushes.map((_, i) => i),
+    bmodels: [],
+  };
+}
+
+/**
+ * Creates a brush defined by min and max bounds.
+ *
+ * @param mins - Minimum coordinates (x, y, z).
+ * @param maxs - Maximum coordinates (x, y, z).
+ * @param contents - Content flags (default: CONTENTS_SOLID).
+ * @returns A CollisionBrush object.
+ */
+export function makeBrushFromMinsMaxs(mins: Vec3, maxs: Vec3, contents = CONTENTS_SOLID): CollisionBrush {
+  const planes = [
+    makePlane({ x: 1, y: 0, z: 0 }, maxs.x),
+    makePlane({ x: -1, y: 0, z: 0 }, -mins.x),
+    makePlane({ x: 0, y: 1, z: 0 }, maxs.y),
+    makePlane({ x: 0, y: -1, z: 0 }, -mins.y),
+    makePlane({ x: 0, y: 0, z: 1 }, maxs.z),
+    makePlane({ x: 0, y: 0, z: -1 }, -mins.z),
+  ];
+
+  return {
+    contents,
+    sides: planes.map((plane) => ({ plane, surfaceFlags: 0 })),
+  };
+}

package/src/shared/collision.ts

@@ -0,0 +1,64 @@
+import type { Vec3 } from '@quake2ts/shared/math/vec3';
+import type { TraceResult, CollisionPlane } from '@quake2ts/shared/bsp/collision';
+
+// Re-export trace helpers from shared if they exist there now, or redefine them here if needed
+// The plan says "Move trace helpers from game/helpers.ts to shared/collision.ts"
+// But currently `game/helpers.ts` re-exports them from `@quake2ts/shared`.
+// `intersects`, `stairTrace`, `ladderTrace` are in `packages/shared/src/testing.ts`.
+// I will re-export them here for test-utils consumers.
+
+export { intersects, stairTrace, ladderTrace } from '@quake2ts/shared';
+
+/**
+ * Interface for a TraceResult mock, including all standard properties.
+ */
+export interface TraceMock extends Partial<TraceResult> {
+    fraction: number;
+    endpos: Vec3;
+    plane: CollisionPlane;
+    surface: { flags: number, name?: string, value?: number };
+    contents: number;
+    ent: any; // Using any to avoid circular dependency with Entity
+    allsolid: boolean;
+    startsolid: boolean;
+}
+
+/**
+ * Creates a mock TraceResult.
+ *
+ * @param overrides - Optional overrides for trace properties.
+ * @returns A TraceMock object.
+ */
+export const createTraceMock = (overrides?: Partial<TraceMock>): TraceMock => ({
+    fraction: 1.0,
+    endpos: { x: 0, y: 0, z: 0 },
+    plane: { normal: { x: 0, y: 0, z: 0 }, dist: 0, type: 0, signbits: 0 },
+    surface: { flags: 0 },
+    contents: 0,
+    ent: null,
+    allsolid: false,
+    startsolid: false,
+    ...overrides
+});
+
+/**
+ * Interface for a Surface mock.
+ */
+export interface SurfaceMock {
+    flags: number;
+    name: string;
+    value: number;
+}
+
+/**
+ * Creates a mock Surface.
+ *
+ * @param overrides - Optional overrides for surface properties.
+ * @returns A SurfaceMock object.
+ */
+export const createSurfaceMock = (overrides?: Partial<SurfaceMock>): SurfaceMock => ({
+    flags: 0,
+    name: 'default',
+    value: 0,
+    ...overrides
+});

package/src/shared/factories.ts

@@ -0,0 +1,88 @@
+import { Cvar, type ConfigStringEntry } from '@quake2ts/engine';
+import { CvarFlags, PlayerState } from '@quake2ts/shared';
+
+// Re-export Cvar for convenience if needed, but the factory returns Cvar instance
+export { Cvar } from '@quake2ts/engine';
+export type { ConfigStringEntry } from '@quake2ts/engine';
+
+/**
+ * Creates a mock ConfigStringEntry.
+ *
+ * @param index - The config string index.
+ * @param value - The config string value.
+ * @returns A ConfigStringEntry object.
+ */
+export function createConfigStringMock(index: number, value: string): ConfigStringEntry {
+  return { index, value };
+}
+
+/**
+ * Creates an array of ConfigStringEntry objects from a record.
+ *
+ * @param entries - A record of index-value pairs (optional).
+ * @returns An array of ConfigStringEntry objects.
+ */
+export function createConfigStringArrayMock(entries?: Record<number, string>): ConfigStringEntry[] {
+  const result: ConfigStringEntry[] = [];
+  if (entries) {
+    for (const [key, value] of Object.entries(entries)) {
+      result.push({ index: Number(key), value });
+    }
+  }
+  return result;
+}
+
+/**
+ * Creates a mock Cvar.
+ *
+ * @param name - The name of the cvar.
+ * @param value - The initial value of the cvar.
+ * @param flags - Cvar flags (default: CvarFlags.None).
+ * @returns A Cvar instance.
+ */
+export function createCvarMock(name: string, value: string, flags: number = CvarFlags.None): Cvar {
+  // We instantiate a real Cvar because it encapsulates logic (latched, default value, etc.)
+  // effectively acting as its own mock/implementation for testing purposes.
+  return new Cvar({
+    name,
+    defaultValue: value,
+    flags,
+  });
+}
+
+/**
+ * Creates a mock PlayerState with sensible defaults.
+ * Corresponds to player_state_t in q_shared.h.
+ *
+ * @param overrides - Partial PlayerState to override defaults.
+ * @returns A complete PlayerState object.
+ */
+export function createMockPlayerState(overrides?: Partial<PlayerState>): PlayerState {
+  return {
+    origin: { x: 0, y: 0, z: 0 },
+    velocity: { x: 0, y: 0, z: 0 },
+    viewAngles: { x: 0, y: 0, z: 0 },
+    onGround: false,
+    waterLevel: 0,
+    watertype: 0,
+    mins: { x: -16, y: -16, z: -24 },
+    maxs: { x: 16, y: 16, z: 32 },
+    damageAlpha: 0,
+    damageIndicators: [],
+    blend: [0, 0, 0, 0],
+    stats: new Array(32).fill(0),
+    kick_angles: { x: 0, y: 0, z: 0 },
+    kick_origin: { x: 0, y: 0, z: 0 },
+    gunoffset: { x: 0, y: 0, z: 0 },
+    gunangles: { x: 0, y: 0, z: 0 },
+    gunindex: 0,
+    pm_type: 0,
+    pm_time: 0,
+    pm_flags: 0,
+    gun_frame: 0,
+    rdflags: 0,
+    fov: 90,
+    renderfx: 0,
+    ...overrides
+  };
+}

package/src/shared/math.ts

@@ -0,0 +1,65 @@
+import type { Vec3, Bounds3 } from '@quake2ts/shared/math/vec3';
+
+/**
+ * Creates a Vector3 object.
+ *
+ * @param x - The X coordinate (default: 0).
+ * @param y - The Y coordinate (default: 0).
+ * @param z - The Z coordinate (default: 0).
+ * @returns A Vec3 object.
+ */
+export const createVector3 = (x: number = 0, y: number = 0, z: number = 0): Vec3 => ({
+  x,
+  y,
+  z,
+});
+
+/**
+ * Creates a bounds object (min/max vectors).
+ *
+ * @param mins - The minimum bounds vector (default: 0,0,0).
+ * @param maxs - The maximum bounds vector (default: 1,1,1).
+ * @returns A Bounds3 object.
+ */
+export const createBounds = (
+  mins: Vec3 = createVector3(0, 0, 0),
+  maxs: Vec3 = createVector3(1, 1, 1)
+): Bounds3 => ({
+  mins,
+  maxs,
+});
+
+/**
+ * Interface representing a transformation (position, rotation, scale).
+ */
+export interface Transform {
+    position: Vec3;
+    rotation: Vec3; // Euler angles
+    scale: Vec3;
+}
+
+/**
+ * Creates a Transform object.
+ *
+ * @param overrides - Optional overrides for transform properties.
+ * @returns A Transform object.
+ */
+export const createTransform = (overrides?: Partial<Transform>): Transform => ({
+    position: createVector3(),
+    rotation: createVector3(),
+    scale: createVector3(1, 1, 1),
+    ...overrides
+});
+
+/**
+ * Generates a random Vector3 within the specified range.
+ *
+ * @param min - Minimum value for each component (default: -100).
+ * @param max - Maximum value for each component (default: 100).
+ * @returns A random Vec3 object.
+ */
+export const randomVector3 = (min: number = -100, max: number = 100): Vec3 => ({
+    x: Math.random() * (max - min) + min,
+    y: Math.random() * (max - min) + min,
+    z: Math.random() * (max - min) + min,
+});