@quake2ts/test-utils 0.0.1

package/src/client/mocks/input.ts

@@ -0,0 +1,246 @@
+
+/**
+ * Client Input System Mocks
+ *
+ * Provides utilities for simulating user input (keyboard, mouse, pointer lock)
+ * in a test environment (JSDOM/Browser).
+ */
+
+export interface KeyModifiers {
+  ctrl?: boolean;
+  alt?: boolean;
+  shift?: boolean;
+  meta?: boolean;
+}
+
+/**
+ * Factory for creating a mock KeyboardEvent.
+ */
+export function createMockKeyboardEvent(key: string, type: 'keydown' | 'keyup' = 'keydown', modifiers: KeyModifiers = {}): KeyboardEvent {
+  return new KeyboardEvent(type, {
+    key,
+    code: key, // Default code to key if not specified (caller can override property if needed)
+    ctrlKey: modifiers.ctrl,
+    altKey: modifiers.alt,
+    shiftKey: modifiers.shift,
+    metaKey: modifiers.meta,
+    bubbles: true,
+    cancelable: true,
+    view: window
+  });
+}
+
+/**
+ * Factory for creating a mock MouseEvent with support for movementX/Y.
+ */
+export function createMockMouseEvent(type: string, options: MouseEventInit = {}): MouseEvent {
+  const event = new MouseEvent(type, {
+    bubbles: true,
+    cancelable: true,
+    view: window,
+    ...options
+  });
+
+  // Patch movementX/Y if needed as JSDOM MouseEvent might not initialize them from options
+  if (options.movementX !== undefined) {
+    Object.defineProperty(event, 'movementX', { value: options.movementX });
+  }
+  if (options.movementY !== undefined) {
+    Object.defineProperty(event, 'movementY', { value: options.movementY });
+  }
+
+  return event;
+}
+
+/**
+ * Factory for creating a mock WheelEvent.
+ */
+export function createMockWheelEvent(deltaX: number = 0, deltaY: number = 0): WheelEvent {
+  return new WheelEvent('wheel', {
+    deltaX,
+    deltaY,
+    bubbles: true,
+    cancelable: true,
+    view: window
+  });
+}
+
+/**
+ * Class implementing a mock for the Pointer Lock API.
+ * Handles patching the document and element prototypes to simulate pointer lock.
+ */
+export class MockPointerLock {
+  private _doc: Document;
+
+  constructor(doc: Document = document) {
+    this._doc = doc;
+    this.setup();
+  }
+
+  private setup() {
+    // Check if already patched to avoid conflicts
+    if ((this._doc as any).__mockPointerLockInstalled) return;
+
+    let _pointerLockElement: Element | null = null;
+    const doc = this._doc;
+
+    // Patch document.pointerLockElement
+    Object.defineProperty(doc, 'pointerLockElement', {
+      get: () => _pointerLockElement,
+      configurable: true
+    });
+
+    // Patch document.exitPointerLock
+    doc.exitPointerLock = () => {
+      if (_pointerLockElement) {
+        _pointerLockElement = null;
+        doc.dispatchEvent(new Event('pointerlockchange'));
+      }
+    };
+
+    // Patch HTMLElement.prototype.requestPointerLock
+    // Save original if needed, but in JSDOM it might not exist or do nothing
+    if (!(global.HTMLElement.prototype as any).__originalRequestPointerLock) {
+        (global.HTMLElement.prototype as any).__originalRequestPointerLock = (global.HTMLElement.prototype as any).requestPointerLock;
+    }
+
+    (global.HTMLElement.prototype as any).requestPointerLock = function() {
+        _pointerLockElement = this;
+        doc.dispatchEvent(new Event('pointerlockchange'));
+    };
+
+    (doc as any).__mockPointerLockInstalled = true;
+  }
+
+  get element(): Element | null {
+    return this._doc.pointerLockElement;
+  }
+
+  get locked(): boolean {
+    return !!this.element;
+  }
+
+  request(element: HTMLElement) {
+    element.requestPointerLock();
+  }
+
+  exit() {
+    this._doc.exitPointerLock();
+  }
+
+  isLocked(): boolean {
+    return this.locked;
+  }
+}
+
+/**
+ * Class for simulating input events.
+ */
+export class InputInjector {
+  constructor(private doc: Document = document, private win: Window = window) {}
+
+  keyDown(key: string, code?: string, modifiers?: KeyModifiers) {
+    const event = createMockKeyboardEvent(key, 'keydown', modifiers);
+    if (code) {
+      Object.defineProperty(event, 'code', { value: code });
+    }
+    this.doc.dispatchEvent(event);
+  }
+
+  keyUp(key: string, code?: string, modifiers?: KeyModifiers) {
+    const event = createMockKeyboardEvent(key, 'keyup', modifiers);
+    if (code) {
+      Object.defineProperty(event, 'code', { value: code });
+    }
+    this.doc.dispatchEvent(event);
+  }
+
+  mouseMove(movementX: number, movementY: number, clientX = 0, clientY = 0) {
+    const event = createMockMouseEvent('mousemove', {
+      clientX,
+      clientY,
+      movementX,
+      movementY
+    });
+    this.dispatchToTarget(event);
+  }
+
+  mouseButton(button: number, state: 'down' | 'up' = 'down') {
+    if (state === 'down') {
+      this.mouseDown(button);
+    } else {
+      this.mouseUp(button);
+    }
+  }
+
+  mouseDown(button: number = 0) {
+    const event = createMockMouseEvent('mousedown', { button });
+    this.dispatchToTarget(event);
+  }
+
+  mouseUp(button: number = 0) {
+    const event = createMockMouseEvent('mouseup', { button });
+    this.dispatchToTarget(event);
+  }
+
+  mouseWheel(deltaY: number) {
+      const event = createMockWheelEvent(0, deltaY);
+      this.dispatchToTarget(event);
+  }
+
+  // Alias for backward compatibility/ease of use
+  wheel(deltaY: number) {
+      this.mouseWheel(deltaY);
+  }
+
+  private dispatchToTarget(event: Event) {
+    const target = this.doc.pointerLockElement || this.doc;
+    target.dispatchEvent(event);
+  }
+}
+
+/**
+ * An implementation of InputSource that listens to DOM events.
+ * Useful for tests that want to verify interaction with real/mocked DOM events.
+ */
+export class BrowserInputSource {
+  constructor(private target: EventTarget = document) {}
+
+  on(event: string, handler: Function): void {
+    if (event === 'keydown' || event === 'keyup') {
+      this.target.addEventListener(event, (e: any) => {
+        handler(e.code);
+      });
+    } else if (event === 'mousedown' || event === 'mouseup') {
+      this.target.addEventListener(event, (e: any) => {
+        handler(e.button);
+      });
+    } else if (event === 'mousemove') {
+      this.target.addEventListener(event, (e: any) => {
+        handler(e.movementX, e.movementY);
+      });
+    }
+  }
+}
+
+/**
+ * Factory for creating a MockPointerLock instance.
+ */
+export function createMockPointerLock(element?: HTMLElement): MockPointerLock {
+  const mock = new MockPointerLock();
+  if (element) {
+    mock.request(element);
+  }
+  return mock;
+}
+
+/**
+ * Factory for creating an InputInjector.
+ */
+export function createInputInjector(target?: EventTarget): InputInjector {
+  // If target is provided and is a Document, use it.
+  // Otherwise default to global document.
+  const doc = (target instanceof Document) ? target : document;
+  const win = (doc.defaultView) ? doc.defaultView : window;
+  return new InputInjector(doc, win);
+}

package/src/client/mocks/network.ts

@@ -0,0 +1,148 @@
+
+import {
+  ServerCommand,
+  ClientCommand,
+  Vec3
+} from '@quake2ts/shared';
+import {
+  EntityState,
+  FrameData,
+  ProtocolPlayerState,
+  createEmptyEntityState,
+  createEmptyProtocolPlayerState,
+  DamageIndicator,
+  FogData
+} from '@quake2ts/engine';
+
+/**
+ * Mocks a server message by just providing the type and data buffer.
+ * In a real scenario, this would be constructing a binary packet.
+ */
+export interface MockServerMessage {
+  type: number;
+  data: Uint8Array;
+}
+
+export function createMockServerMessage(type: number, data: Uint8Array = new Uint8Array()): MockServerMessage {
+  return { type, data };
+}
+
+/**
+ * Creates a mock Snapshot (FrameData) for testing.
+ */
+export function createMockSnapshot(
+    serverFrame: number,
+    entities: EntityState[] = [],
+    playerState?: Partial<ProtocolPlayerState>,
+    deltaFrame: number = 0
+): FrameData {
+    return {
+        serverFrame,
+        deltaFrame,
+        surpressCount: 0,
+        areaBytes: 0,
+        areaBits: new Uint8Array(),
+        playerState: {
+            ...createEmptyProtocolPlayerState(),
+            ...playerState
+        },
+        packetEntities: {
+            delta: false,
+            entities
+        }
+    };
+}
+
+/**
+ * Creates a mock Delta Frame (FrameData with delta flag).
+ */
+export function createMockDeltaFrame(
+    serverFrame: number,
+    deltaFrame: number,
+    entities: EntityState[] = [],
+    playerState?: Partial<ProtocolPlayerState>
+): FrameData {
+    return {
+        serverFrame,
+        deltaFrame,
+        surpressCount: 0,
+        areaBytes: 0,
+        areaBits: new Uint8Array(),
+        playerState: {
+            ...createEmptyProtocolPlayerState(),
+            ...playerState
+        },
+        packetEntities: {
+            delta: true,
+            entities
+        }
+    };
+}
+
+/**
+ * Simulates network delay for a sequence of messages.
+ */
+export function simulateNetworkDelay<T>(messages: T[], delayMs: number): Promise<T[]> {
+    return new Promise(resolve => {
+        setTimeout(() => {
+            resolve(messages);
+        }, delayMs);
+    });
+}
+
+/**
+ * Simulates packet loss by randomly filtering messages.
+ * @param messages The messages to process
+ * @param lossPercent Percentage of packet loss (0-100)
+ */
+export function simulatePacketLoss<T>(messages: T[], lossPercent: number): T[] {
+    return messages.filter(() => Math.random() * 100 >= lossPercent);
+}
+
+/**
+ * Factory for creating a mock EntityState.
+ */
+export function createMockEntityState(
+    number: number,
+    modelIndex: number = 0,
+    origin: Partial<Vec3> = { x: 0, y: 0, z: 0 },
+    overrides?: Partial<EntityState>
+): EntityState {
+    const state = createEmptyEntityState();
+    state.number = number;
+    state.modelindex = modelIndex;
+    state.origin.x = origin.x ?? 0;
+    state.origin.y = origin.y ?? 0;
+    state.origin.z = origin.z ?? 0;
+
+    if (overrides) {
+        Object.assign(state, overrides);
+    }
+    return state;
+}
+
+export function createMockDamageIndicator(
+  damage: number,
+  dir: Vec3 = { x: 0, y: 0, z: 0 },
+  health = true,
+  armor = false,
+  power = false
+): DamageIndicator {
+  return {
+    damage,
+    dir,
+    health,
+    armor,
+    power
+  };
+}
+
+export function createMockFogData(overrides: Partial<FogData> = {}): FogData {
+    return {
+        density: 0.1,
+        red: 100,
+        green: 100,
+        blue: 100,
+        ...overrides
+    };
+}

package/src/client/mocks/state.ts

@@ -0,0 +1,148 @@
+import { EntityState, PmoveTraceResult, Vec3 } from '@quake2ts/shared';
+
+// Mock ConfigStringIndex to match shared
+enum ConfigStringIndex {
+  Models = 32,
+  Sounds = 288,
+  Images = 544,
+  Players = 544 + 256, // Base for players, usually logic handles offset
+}
+
+const MAX_MODELS = 256;
+const MAX_SOUNDS = 256;
+const MAX_IMAGES = 256;
+
+// Minimal ClientConfigStrings implementation for testing
+export class MockClientConfigStrings {
+  private readonly strings: Map<number, string> = new Map();
+  private readonly models: string[] = [];
+  private readonly sounds: string[] = [];
+  private readonly images: string[] = [];
+
+  constructor() {}
+
+  public set(index: number, value: string): void {
+    this.strings.set(index, value);
+
+    if (index >= ConfigStringIndex.Models && index < ConfigStringIndex.Models + MAX_MODELS) {
+      this.models[index - ConfigStringIndex.Models] = value;
+    } else if (index >= ConfigStringIndex.Sounds && index < ConfigStringIndex.Sounds + MAX_SOUNDS) {
+      this.sounds[index - ConfigStringIndex.Sounds] = value;
+    } else if (index >= ConfigStringIndex.Images && index < ConfigStringIndex.Images + MAX_IMAGES) {
+      this.images[index - ConfigStringIndex.Images] = value;
+    }
+  }
+
+  public get(index: number): string | undefined {
+    return this.strings.get(index);
+  }
+
+  public getModelName(index: number): string | undefined {
+    return this.models[index];
+  }
+
+  public getSoundName(index: number): string | undefined {
+    return this.sounds[index];
+  }
+
+  public getImageName(index: number): string | undefined {
+    return this.images[index];
+  }
+
+  public getPlayerName(playernum: number): string | undefined {
+     // Stub logic
+     const info = this.strings.get(ConfigStringIndex.Players + playernum);
+     if (!info) return undefined;
+     const parts = info.split('\\');
+    for (let i = 1; i < parts.length; i += 2) {
+      if (parts[i] === 'name') {
+        return parts[i + 1];
+      }
+    }
+    return undefined;
+  }
+
+  public clear(): void {
+    this.strings.clear();
+    this.models.length = 0;
+    this.sounds.length = 0;
+    this.images.length = 0;
+  }
+}
+
+// Define ClientState interface locally as it's not exported from client
+export interface ClientStateProvider {
+  tickRate: number;
+  frameTimeMs: number;
+  serverFrame: number;
+  serverProtocol: number;
+  configStrings: MockClientConfigStrings;
+  getClientName(num: number): string;
+  getKeyBinding(key: string): string;
+  inAutoDemo: boolean;
+}
+
+export interface ClientInfo {
+  name: string;
+  skin: string;
+  model: string;
+  icon: string;
+}
+
+export interface ClientState extends ClientStateProvider {
+  playerNum: number;
+  serverTime: number;
+  parseEntities: number;
+}
+
+export interface Frame {
+  serverFrame: number;
+  deltaFrame: number;
+  valid: boolean;
+  entities: EntityState[];
+}
+
+export interface ConnectionState {
+  state: 'disconnected' | 'connecting' | 'connected' | 'active';
+}
+
+// -- Factories --
+
+export const createMockClientState = (overrides?: Partial<ClientState>): ClientState => {
+  const configStrings = new MockClientConfigStrings();
+
+  return {
+    tickRate: 10,
+    frameTimeMs: 100,
+    serverFrame: 0,
+    serverProtocol: 34,
+    configStrings,
+    playerNum: 0,
+    serverTime: 0,
+    parseEntities: 0,
+    inAutoDemo: false,
+    getClientName: (num: number) => `Player${num}`,
+    getKeyBinding: (key: string) => '',
+    ...overrides
+  };
+};
+
+export const createMockFrame = (overrides?: Partial<Frame>): Frame => ({
+  serverFrame: 0,
+  deltaFrame: -1,
+  valid: true,
+  entities: [],
+  ...overrides
+});
+
+export const createMockClientInfo = (overrides?: Partial<ClientInfo>): ClientInfo => ({
+  name: 'Player',
+  skin: 'male/grunt',
+  model: 'male',
+  icon: 'pics/icon.pcx',
+  ...overrides
+});
+
+export const createMockConnectionState = (state: ConnectionState['state'] = 'connected'): ConnectionState => ({
+  state
+});

package/src/e2e/network.ts

@@ -0,0 +1,47 @@
+export type NetworkCondition = 'good' | 'slow' | 'unstable' | 'offline' | 'custom';
+
+export interface NetworkSimulator {
+  latency: number; // ms
+  jitter: number; // ms
+  packetLoss: number; // percentage 0-1
+  bandwidth: number; // bytes per second
+}
+
+/**
+ * Simulates network conditions.
+ */
+export function simulateNetworkCondition(condition: NetworkCondition): NetworkSimulator {
+  switch (condition) {
+    case 'good':
+      return { latency: 20, jitter: 5, packetLoss: 0, bandwidth: 10 * 1024 * 1024 };
+    case 'slow':
+      return { latency: 150, jitter: 20, packetLoss: 0.01, bandwidth: 1 * 1024 * 1024 };
+    case 'unstable':
+      return { latency: 100, jitter: 100, packetLoss: 0.05, bandwidth: 512 * 1024 };
+    case 'offline':
+      return { latency: 0, jitter: 0, packetLoss: 1, bandwidth: 0 };
+    case 'custom':
+    default:
+      return { latency: 0, jitter: 0, packetLoss: 0, bandwidth: Infinity };
+  }
+}
+
+/**
+ * Creates a custom network condition.
+ */
+export function createCustomNetworkCondition(latency: number, jitter: number, packetLoss: number): NetworkSimulator {
+  return {
+    latency,
+    jitter,
+    packetLoss,
+    bandwidth: Infinity // Default to unlimited unless specified
+  };
+}
+
+/**
+ * Helper to throttle bandwidth (e.g. for Playwright).
+ */
+export function throttleBandwidth(bytesPerSecond: number): void {
+  // This function would interface with Playwright's CDPSession in an E2E test.
+  // It returns void here as a placeholder for the logic to be used within a test context.
+}

package/src/e2e/playwright.ts

@@ -0,0 +1,90 @@
+export interface PlaywrightOptions {
+    headless?: boolean;
+    viewport?: { width: number; height: number };
+}
+
+export interface PlaywrightTestClient {
+    page: any; // Type as 'Page' from playwright in real usage, but keeping it generic here to avoid hard dependency on playwright types in this util file if not needed
+    browser: any;
+    navigate(url: string): Promise<void>;
+    waitForGame(): Promise<void>;
+    injectInput(type: string, data: any): Promise<void>;
+    screenshot(name: string): Promise<Buffer>;
+    close(): Promise<void>;
+}
+
+/**
+ * Creates a Playwright test client.
+ * Note: Requires playwright to be installed in the project.
+ */
+export async function createPlaywrightTestClient(options: PlaywrightOptions = {}): Promise<PlaywrightTestClient> {
+    // Dynamic import to avoid hard dependency if not used
+    let playwright;
+    try {
+        playwright = await import('playwright');
+    } catch (e) {
+        throw new Error('Playwright is not installed. Please install it to use this utility.');
+    }
+
+    const browser = await playwright.chromium.launch({
+        headless: options.headless ?? true,
+    });
+    const context = await browser.newContext({
+        viewport: options.viewport || { width: 1280, height: 720 },
+    });
+    const page = await context.newPage();
+
+    return {
+        page,
+        browser,
+        async navigate(url: string) {
+            await page.goto(url);
+        },
+        async waitForGame() {
+            await waitForGameReady(page);
+        },
+        async injectInput(type: string, data: any) {
+             // Simulate input injection via evaluate
+             await page.evaluate(({ type, data }: any) => {
+                 // Assumes a global function or event listener exists to receive injected input
+                 console.log('Injecting input', type, data);
+                 // (window as any).game.injectInput(type, data);
+             }, { type, data });
+        },
+        async screenshot(name: string) {
+            return await page.screenshot({ path: `${name}.png` });
+        },
+        async close() {
+            await browser.close();
+        }
+    };
+}
+
+/**
+ * Waits for the game to be ready.
+ */
+export async function waitForGameReady(page: any, timeout: number = 10000): Promise<void> {
+    await page.waitForFunction(() => {
+        // Check for some global game state or canvas presence
+        return (window as any).game && (window as any).game.isRunning;
+    }, { timeout });
+}
+
+export interface GameStateCapture {
+    time: number;
+    entities: number;
+    // Add other state properties
+}
+
+/**
+ * Captures current game state from the browser.
+ */
+export async function captureGameState(page: any): Promise<GameStateCapture> {
+    return await page.evaluate(() => {
+        const game = (window as any).game;
+        return {
+            time: game ? game.time : 0,
+            entities: game && game.entities ? game.entities.length : 0
+        };
+    });
+}