@quake2ts/test-utils 0.0.1

package/src/server/mocks/transport.ts

@@ -0,0 +1,161 @@
+import { NetworkTransport } from '@quake2ts/server';
+import { NetDriver } from '@quake2ts/shared';
+import { vi } from 'vitest';
+
+/**
+ * Mock implementation of the NetworkTransport interface for server testing.
+ * Allows simulating connections and errors.
+ */
+export class MockTransport implements NetworkTransport {
+    public onConnectionCallback?: (driver: NetDriver, info?: any) => void;
+    public onErrorCallback?: (error: Error) => void;
+    public address: string = '127.0.0.1';
+    public port: number = 27910;
+    public sentMessages: Uint8Array[] = [];
+    public receivedMessages: Uint8Array[] = [];
+    public listening: boolean = false;
+
+    public listenSpy = vi.fn().mockImplementation(async (port: number) => {
+        this.port = port;
+        this.listening = true;
+    });
+    public closeSpy = vi.fn().mockImplementation(() => {
+        this.listening = false;
+    });
+
+    /**
+     * Start listening on the specified port.
+     */
+    async listen(port: number): Promise<void> {
+        return this.listenSpy(port);
+    }
+
+    /**
+     * Close the transport.
+     */
+    close() {
+        this.closeSpy();
+    }
+
+    /**
+     * Register a callback for new connections.
+     */
+    onConnection(callback: (driver: NetDriver, info?: any) => void) {
+        this.onConnectionCallback = callback;
+    }
+
+    /**
+     * Register a callback for errors.
+     */
+    onError(callback: (error: Error) => void) {
+        this.onErrorCallback = callback;
+    }
+
+    /**
+     * Check if the transport is currently listening.
+     */
+    public isListening(): boolean {
+        return this.listening;
+    }
+
+    /**
+     * Helper to simulate a new connection.
+     * @param driver The network driver for the connection.
+     * @param info Optional connection info.
+     */
+    public simulateConnection(driver: NetDriver, info?: any) {
+        if (this.onConnectionCallback) {
+            this.onConnectionCallback(driver, info);
+        }
+    }
+
+    /**
+     * Helper to simulate an error.
+     * @param error The error to simulate.
+     */
+    public simulateError(error: Error) {
+        if (this.onErrorCallback) {
+            this.onErrorCallback(error);
+        }
+    }
+}
+
+/**
+ * Interface for mock UDP socket.
+ * This is a partial mock of Node.js dgram.Socket or similar.
+ */
+export interface MockUDPSocket {
+    send: (msg: Uint8Array, offset: number, length: number, port: number, address: string, callback?: (error: Error | null, bytes: number) => void) => void;
+    on: (event: string, callback: (...args: any[]) => void) => void;
+    close: () => void;
+    bind: (port: number, address?: string) => void;
+    address: () => { address: string; family: string; port: number };
+}
+
+/**
+ * Creates a mock UDP socket.
+ * @param overrides Optional overrides for the socket methods.
+ */
+export function createMockUDPSocket(overrides?: Partial<MockUDPSocket>): MockUDPSocket {
+    const socket: MockUDPSocket = {
+        send: vi.fn(),
+        on: vi.fn(),
+        close: vi.fn(),
+        bind: vi.fn(),
+        address: vi.fn().mockReturnValue({ address: '127.0.0.1', family: 'IPv4', port: 0 }),
+        ...overrides,
+    };
+    return socket;
+}
+
+/**
+ * Interface for network address.
+ */
+export interface NetworkAddress {
+    ip: string;
+    port: number;
+}
+
+/**
+ * Creates a mock network address.
+ * @param ip IP address (default: '127.0.0.1')
+ * @param port Port number (default: 27910)
+ */
+export function createMockNetworkAddress(ip: string = '127.0.0.1', port: number = 27910): NetworkAddress {
+    return { ip, port };
+}
+
+/**
+ * Creates a configured MockTransport instance.
+ * @param address Address to bind to (default: '127.0.0.1')
+ * @param port Port to listen on (default: 27910)
+ * @param overrides Optional overrides for the transport properties.
+ */
+export function createMockTransport(
+    address: string = '127.0.0.1',
+    port: number = 27910,
+    overrides?: Partial<MockTransport>
+): MockTransport {
+    const transport = new MockTransport();
+    transport.address = address;
+    transport.port = port;
+    Object.assign(transport, overrides);
+    return transport;
+}
+
+/**
+ * Creates a mock NetDriver instance.
+ * @param overrides Optional overrides for the NetDriver methods.
+ */
+export function createMockNetDriver(overrides?: Partial<NetDriver>): NetDriver {
+    return {
+        connect: vi.fn().mockResolvedValue(undefined),
+        disconnect: vi.fn(),
+        send: vi.fn(),
+        onMessage: vi.fn(),
+        onClose: vi.fn(),
+        onError: vi.fn(),
+        isConnected: vi.fn().mockReturnValue(true),
+        ...overrides
+    };
+}

package/src/setup/audio.ts

@@ -0,0 +1,118 @@
+/**
+ * Mocks for Web Audio API.
+ */
+
+/**
+ * Sets up a mock AudioContext globally.
+ */
+export function setupMockAudioContext(): void {
+  class MockAudioContext {
+    state = 'suspended';
+    destination = {};
+    currentTime = 0;
+    listener = {
+        positionX: { value: 0 },
+        positionY: { value: 0 },
+        positionZ: { value: 0 },
+        forwardX: { value: 0 },
+        forwardY: { value: 0 },
+        forwardZ: { value: 0 },
+        upX: { value: 0 },
+        upY: { value: 0 },
+        upZ: { value: 0 },
+        setOrientation: () => {},
+        setPosition: () => {}
+    };
+
+    createGain() {
+      return {
+        gain: { value: 1, linearRampToValueAtTime: () => {} },
+        connect: () => {},
+        disconnect: () => {}
+      };
+    }
+
+    createBufferSource() {
+        return {
+            buffer: null,
+            loop: false,
+            playbackRate: { value: 1 },
+            connect: () => {},
+            start: () => {},
+            stop: () => {},
+            disconnect: () => {},
+            onended: null
+        };
+    }
+
+    createPanner() {
+        return {
+            panningModel: 'equalpower',
+            distanceModel: 'inverse',
+            positionX: { value: 0 },
+            positionY: { value: 0 },
+            positionZ: { value: 0 },
+            orientationX: { value: 0 },
+            orientationY: { value: 0 },
+            orientationZ: { value: 0 },
+            coneInnerAngle: 360,
+            coneOuterAngle: 360,
+            coneOuterGain: 0,
+            connect: () => {},
+            disconnect: () => {},
+            setPosition: () => {},
+            setOrientation: () => {}
+        }
+    }
+
+    createBuffer(numOfChannels: number, length: number, sampleRate: number) {
+        return {
+            duration: length / sampleRate,
+            length,
+            sampleRate,
+            numberOfChannels: numOfChannels,
+            getChannelData: () => new Float32Array(length)
+        }
+    }
+
+    decodeAudioData(data: ArrayBuffer, success?: (buffer: any) => void) {
+        const buffer = this.createBuffer(2, 100, 44100);
+        if (success) success(buffer);
+        return Promise.resolve(buffer);
+    }
+
+    resume() { return Promise.resolve(); }
+    suspend() { return Promise.resolve(); }
+    close() { return Promise.resolve(); }
+  }
+
+  global.AudioContext = MockAudioContext as any;
+  // @ts-ignore
+  global.webkitAudioContext = MockAudioContext as any;
+}
+
+/**
+ * Restores original AudioContext.
+ */
+export function teardownMockAudioContext(): void {
+  // @ts-ignore
+  delete global.AudioContext;
+  // @ts-ignore
+  delete global.webkitAudioContext;
+}
+
+export interface AudioEvent {
+  type: string;
+  data?: any;
+}
+
+/**
+ * Captures audio events from a context.
+ * Requires the context to be instrumented or mocked to emit events.
+ * This helper currently works with the `setupMockAudioContext` mock if extended.
+ */
+export function captureAudioEvents(context: AudioContext): AudioEvent[] {
+  // Placeholder for capturing events.
+  // Real implementation would attach spies to context methods.
+  return [];
+}

package/src/setup/browser.ts

@@ -0,0 +1,249 @@
+import { JSDOM } from 'jsdom';
+import { Canvas, Image, ImageData } from '@napi-rs/canvas';
+import 'fake-indexeddb/auto';
+import { MockPointerLock } from '../client/mocks/input.js';
+import { createMockWebGL2Context } from './webgl.js';
+
+export interface BrowserSetupOptions {
+  url?: string;
+  pretendToBeVisual?: boolean;
+  resources?: "usable";
+  enableWebGL2?: boolean;
+  enablePointerLock?: boolean;
+}
+
+/**
+ * Sets up a browser environment for testing using JSDOM and napi-rs/canvas.
+ * This should be called in your vitest.setup.ts file.
+ */
+export function setupBrowserEnvironment(options: BrowserSetupOptions = {}) {
+  const {
+    url = 'http://localhost',
+    pretendToBeVisual = true,
+    resources = undefined,
+    enableWebGL2 = false,
+    enablePointerLock = false
+  } = options;
+
+  // Create a JSDOM instance
+  const dom = new JSDOM('<!DOCTYPE html><html><head></head><body></body></html>', {
+    url,
+    pretendToBeVisual,
+    resources: resources as any
+  });
+
+  // Set up global variables
+  global.window = dom.window as any;
+  global.document = dom.window.document;
+
+  // Polyfill global DOM Constructors
+  global.Document = dom.window.Document;
+  global.Element = dom.window.Element;
+  global.Node = dom.window.Node;
+
+  // Handle navigator assignment safely
+  try {
+    // @ts-ignore
+    global.navigator = dom.window.navigator;
+  } catch (e) {
+    try {
+      Object.defineProperty(global, 'navigator', {
+        value: dom.window.navigator,
+        writable: true,
+        configurable: true
+      });
+    } catch (e2) {
+      console.warn('Could not assign global.navigator, skipping.');
+    }
+  }
+
+  global.location = dom.window.location;
+  global.HTMLElement = dom.window.HTMLElement;
+  global.HTMLCanvasElement = dom.window.HTMLCanvasElement;
+
+  // Polyfill global Event constructors
+  global.Event = dom.window.Event;
+  global.CustomEvent = dom.window.CustomEvent;
+  global.DragEvent = dom.window.DragEvent as any;
+  global.MouseEvent = dom.window.MouseEvent;
+  global.KeyboardEvent = dom.window.KeyboardEvent;
+  global.FocusEvent = dom.window.FocusEvent;
+  global.WheelEvent = dom.window.WheelEvent;
+  global.InputEvent = dom.window.InputEvent;
+  global.UIEvent = dom.window.UIEvent;
+
+  // Setup Storage mocks
+  try {
+      global.localStorage = dom.window.localStorage;
+  } catch (e) {
+      // Ignore if it fails
+  }
+
+  if (!global.localStorage) {
+    const storage = new Map<string, string>();
+    global.localStorage = {
+      getItem: (key: string) => storage.get(key) || null,
+      setItem: (key: string, value: string) => storage.set(key, value),
+      removeItem: (key: string) => storage.delete(key),
+      clear: () => storage.clear(),
+      key: (index: number) => Array.from(storage.keys())[index] || null,
+      get length() { return storage.size; }
+    } as Storage;
+  }
+
+  // Override document.createElement for canvas elements
+  const originalCreateElement = document.createElement.bind(document);
+  document.createElement = function (tagName: string, options?: any) {
+    if (tagName.toLowerCase() === 'canvas') {
+      const napiCanvas = new Canvas(300, 150);
+      const domCanvas = originalCreateElement('canvas', options);
+
+      Object.defineProperty(domCanvas, 'width', {
+        get: () => napiCanvas.width,
+        set: (value) => { napiCanvas.width = value; },
+        enumerable: true,
+        configurable: true
+      });
+
+      Object.defineProperty(domCanvas, 'height', {
+        get: () => napiCanvas.height,
+        set: (value) => { napiCanvas.height = value; },
+        enumerable: true,
+        configurable: true
+      });
+
+      const originalGetContext = domCanvas.getContext.bind(domCanvas);
+      domCanvas.getContext = function(contextId: string, options?: any) {
+        if (contextId === '2d') {
+          return napiCanvas.getContext('2d', options);
+        }
+
+        if (enableWebGL2 && contextId === 'webgl2') {
+           return createMockWebGL2Context(domCanvas as HTMLCanvasElement);
+        }
+
+        if (contextId === 'webgl' || contextId === 'webgl2') {
+          return originalGetContext(contextId, options);
+        }
+        return napiCanvas.getContext(contextId as any, options);
+      } as any;
+
+      (domCanvas as any).__napiCanvas = napiCanvas;
+
+      return domCanvas;
+    }
+    return originalCreateElement(tagName, options);
+  } as any;
+
+  if (enableWebGL2) {
+      const originalProtoGetContext = global.HTMLCanvasElement.prototype.getContext;
+      global.HTMLCanvasElement.prototype.getContext = function (
+        contextId: string,
+        options?: any
+      ): any {
+        if (contextId === 'webgl2') {
+          return createMockWebGL2Context(this);
+        }
+        // @ts-ignore
+        return originalProtoGetContext.call(this, contextId as any, options);
+      };
+  }
+
+  global.Image = Image as any;
+  global.ImageData = ImageData as any;
+
+  if (typeof global.createImageBitmap === 'undefined') {
+    global.createImageBitmap = async function (
+      image: any,
+      _options?: ImageBitmapOptions
+    ): Promise<any> {
+      if (image && typeof image.width === 'number' && typeof image.height === 'number') {
+        const canvas = new Canvas(image.width, image.height);
+        const ctx = canvas.getContext('2d');
+        if (image.data) {
+           ctx.putImageData(image as any, 0, 0);
+        }
+        return canvas;
+      }
+      const canvas = new Canvas(100, 100);
+      return canvas;
+    } as unknown as any;
+  }
+
+  if (typeof global.btoa === 'undefined') {
+    global.btoa = function (str: string): string {
+      return Buffer.from(str, 'binary').toString('base64');
+    };
+  }
+
+  if (typeof global.atob === 'undefined') {
+    global.atob = function (str: string): string {
+      return Buffer.from(str, 'base64').toString('binary');
+    };
+  }
+
+  if (enablePointerLock) {
+      new MockPointerLock(global.document);
+  }
+
+  if (typeof global.requestAnimationFrame === 'undefined') {
+      let lastTime = 0;
+      global.requestAnimationFrame = (callback: FrameRequestCallback) => {
+        const currTime = Date.now();
+        const timeToCall = Math.max(0, 16 - (currTime - lastTime));
+        const id = setTimeout(() => {
+            callback(currTime + timeToCall);
+        }, timeToCall);
+        lastTime = currTime + timeToCall;
+        return id as unknown as number;
+      };
+
+      global.cancelAnimationFrame = (id: number) => {
+        clearTimeout(id);
+      };
+  }
+}
+
+/**
+ * Cleans up the browser environment.
+ */
+export function teardownBrowserEnvironment() {
+  // @ts-ignore
+  delete global.window;
+  // @ts-ignore
+  delete global.document;
+  // @ts-ignore
+  delete global.navigator;
+  // @ts-ignore
+  delete global.localStorage;
+  // @ts-ignore
+  delete global.location;
+  // @ts-ignore
+  delete global.HTMLElement;
+  // @ts-ignore
+  delete global.HTMLCanvasElement;
+  // @ts-ignore
+  delete global.Image;
+  // @ts-ignore
+  delete global.ImageData;
+  // @ts-ignore
+  delete global.createImageBitmap;
+  // @ts-ignore
+  delete global.Event;
+  // @ts-ignore
+  delete global.CustomEvent;
+  // @ts-ignore
+  delete global.DragEvent;
+  // @ts-ignore
+  delete global.MouseEvent;
+  // @ts-ignore
+  delete global.KeyboardEvent;
+  // @ts-ignore
+  delete global.FocusEvent;
+  // @ts-ignore
+  delete global.WheelEvent;
+  // @ts-ignore
+  delete global.InputEvent;
+  // @ts-ignore
+  delete global.UIEvent;
+}

package/src/setup/canvas.ts

@@ -0,0 +1,142 @@
+import { Canvas, ImageData } from '@napi-rs/canvas';
+import { createMockWebGL2Context } from '../engine/mocks/webgl.js';
+
+/**
+ * Creates a mock HTMLCanvasElement backed by napi-rs/canvas,
+ * with support for both 2D and WebGL2 contexts.
+ */
+export function createMockCanvas(width: number = 300, height: number = 150): HTMLCanvasElement {
+  // Use a real JSDOM canvas if available in the environment (setupBrowserEnvironment)
+  if (typeof document !== 'undefined' && document.createElement) {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    return canvas;
+  }
+
+  // Fallback for non-JSDOM environments or specialized testing
+  const napiCanvas = new Canvas(width, height);
+  const canvas = {
+    width,
+    height,
+    getContext: (contextId: string, options?: any) => {
+      if (contextId === '2d') {
+        return napiCanvas.getContext('2d', options);
+      }
+      if (contextId === 'webgl2') {
+         return createMockWebGL2Context(canvas as any);
+      }
+      return null;
+    },
+    toDataURL: () => napiCanvas.toDataURL(),
+    toBuffer: (mime: any) => napiCanvas.toBuffer(mime),
+    // Add other properties as needed
+  } as unknown as HTMLCanvasElement;
+
+  return canvas;
+}
+
+/**
+ * Creates a mock CanvasRenderingContext2D.
+ */
+export function createMockCanvasContext2D(canvas?: HTMLCanvasElement): CanvasRenderingContext2D {
+  const c = canvas || createMockCanvas();
+  const ctx = c.getContext('2d');
+  if (!ctx) {
+      throw new Error('Failed to create 2D context');
+  }
+  return ctx as CanvasRenderingContext2D;
+}
+
+/**
+ * Information about a captured draw call.
+ */
+export interface DrawCall {
+  method: string;
+  args: any[];
+}
+
+/**
+ * Wraps a CanvasRenderingContext2D to capture all method calls.
+ */
+export function captureCanvasDrawCalls(context: CanvasRenderingContext2D): DrawCall[] {
+  const calls: DrawCall[] = [];
+  const proto = Object.getPrototypeOf(context);
+
+  // Iterate over all properties of the context prototype
+  for (const key of Object.getOwnPropertyNames(proto)) {
+     const value = (context as any)[key];
+     if (typeof value === 'function') {
+         // Override function
+         (context as any)[key] = function(...args: any[]) {
+             calls.push({ method: key, args });
+             return value.apply(context, args);
+         };
+     }
+  }
+
+  return calls;
+}
+
+/**
+ * Creates a mock ImageData object.
+ */
+export function createMockImageData(width: number, height: number, fillColor?: [number, number, number, number]): ImageData {
+  // Check if global ImageData is available (polyfilled by setupBrowserEnvironment)
+  if (typeof global.ImageData !== 'undefined') {
+      const data = new Uint8ClampedArray(width * height * 4);
+      if (fillColor) {
+          for (let i = 0; i < data.length; i += 4) {
+              data[i] = fillColor[0];
+              data[i + 1] = fillColor[1];
+              data[i + 2] = fillColor[2];
+              data[i + 3] = fillColor[3];
+          }
+      }
+      return new global.ImageData(data, width, height) as unknown as ImageData;
+  }
+
+  // Fallback if not globally available, though it should be with @napi-rs/canvas
+  const data = new Uint8ClampedArray(width * height * 4);
+    if (fillColor) {
+        for (let i = 0; i < data.length; i += 4) {
+            data[i] = fillColor[0];
+            data[i + 1] = fillColor[1];
+            data[i + 2] = fillColor[2];
+            data[i + 3] = fillColor[3];
+        }
+    }
+  return new ImageData(data, width, height);
+}
+
+/**
+ * Creates a mock HTMLImageElement.
+ */
+export function createMockImage(width: number = 100, height: number = 100, src: string = ''): HTMLImageElement {
+    if (typeof document !== 'undefined' && document.createElement) {
+        const img = document.createElement('img');
+        img.width = width;
+        img.height = height;
+        if (src) img.src = src;
+        return img;
+    }
+
+    // Fallback
+    const img = {
+        width,
+        height,
+        src,
+        complete: true,
+        onload: null,
+        onerror: null,
+    } as unknown as HTMLImageElement;
+
+    // Simulate async load if src is provided
+    if (src) {
+        setTimeout(() => {
+            if (img.onload) (img.onload as any)();
+        }, 0);
+    }
+
+    return img;
+}

package/src/setup/node.ts

@@ -0,0 +1,21 @@
+/**
+ * Setup helpers for Node.js environments.
+ */
+export interface NodeSetupOptions {
+  // Add options as needed, e.g. mocking fs, process.env, etc.
+}
+
+/**
+ * Sets up a Node.js environment for testing.
+ * Currently a placeholder for future Node-specific setup.
+ */
+export function setupNodeEnvironment(options: NodeSetupOptions = {}) {
+  // No-op for now, but provides a hook for future setup
+}
+
+/**
+ * Teardown for Node.js environment.
+ */
+export function teardownNodeEnvironment() {
+  // No-op for now
+}