@quake2ts/test-utils 0.0.1

package/src/index.ts

@@ -0,0 +1,93 @@
+// Export all test utilities
+export * from './shared/mocks.js';
+export * from './shared/bsp.js';
+export * from './shared/pak-loader.js';
+export * from './shared/math.js';
+export * from './shared/collision.js';
+export * from './shared/factories.js';
+export * from './game/factories.js';
+export * from './game/helpers.js';
+export * from './game/helpers/physics.js';
+export * from './game/helpers/save.js';
+export * from './game/mocks/ai.js';
+export * from './game/mocks/combat.js';
+export * from './game/mocks/items.js';
+export * from './game/mocks.js';
+export * from './server/mocks/transport.js';
+export * from './server/mockTransport.js';
+export * from './server/mockNetDriver.js';
+export * from './server/mocks/state.js';
+export * from './server/mocks/connection.js';
+export * from './server/mocks/commands.js';
+export * from './server/mocks/master.js';
+export * from './server/mocks/physics.js';
+export * from './server/helpers/multiplayer.js';
+export * from './server/helpers/snapshot.js';
+export * from './server/helpers/bandwidth.js';
+
+// Setup
+export * from './setup/browser.js';
+export * from './setup/canvas.js';
+export * from './setup/webgpu.js';
+export * from './engine/mocks/webgpu.js';
+export * from './setup/timing.js';
+export * from './setup/node.js';
+export * from './engine/mocks/webgl.js';
+export * from './engine/mocks/audio.js';
+export * from './engine/mocks/renderer.js';
+export * from './engine/mocks/assets.js';
+export * from './engine/mocks/buffers.js';
+export * from './engine/mocks/lighting.js';
+export * from './engine/mocks/particles.js';
+export * from './engine/rendering.js';
+export * from './setup/storage.js';
+export * from './setup/audio.js';
+export * from './engine/helpers/webgpu-rendering.js';
+export * from './engine/helpers/pipeline-test-template.js';
+
+// Client Mocks
+export * from './client/mocks/input.js';
+export * from './client/helpers/view.js';
+export * from './client/helpers/hud.js';
+export * from './client/mocks/network.js';
+export * from './client/mocks/download.js';
+export * from './client/mocks/state.js';
+export * from './client/mocks/console.js';
+export * from './client/helpers/prediction.js';
+
+// Visual Testing
+export * from './visual/snapshots.js';
+
+// E2E
+export * from './e2e/playwright.js';
+export * from './e2e/network.js';
+export * from './e2e/visual.js';
+
+// Export types
+export type { BrowserSetupOptions } from './setup/browser.js';
+export type { NodeSetupOptions } from './setup/node.js';
+export type { MockRAF } from './setup/timing.js';
+export type { StorageScenario } from './setup/storage.js';
+export type { NetworkSimulator, NetworkCondition } from './e2e/network.js';
+export type { VisualScenario, VisualDiff } from './e2e/visual.js';
+export type { HeadlessWebGPUSetup, WebGPUContextState } from './setup/webgpu.js';
+export type { RenderTestSetup, ComputeTestSetup } from './engine/helpers/webgpu-rendering.js';
+export type { GeometryBuffers } from './engine/helpers/pipeline-test-template.js';
+
+// Shared Types
+export type {
+    BinaryWriterMock,
+    BinaryStreamMock,
+    MessageWriterMock,
+    MessageReaderMock,
+    PacketMock
+} from './shared/mocks.js';
+export type { TraceMock, SurfaceMock } from './shared/collision.js';
+export type { Transform } from './shared/math.js';
+export type {
+    CaptureOptions,
+    ComparisonResult,
+    ComparisonOptions,
+    SnapshotTestOptions
+} from './visual/snapshots.js';
+export type { MockCollisionEntityIndex } from './server/mocks/physics.js';

package/src/server/helpers/bandwidth.ts

@@ -0,0 +1,127 @@
+import { Client, ClientFrame } from '@quake2ts/server';
+
+export interface RateLimiter {
+  bytesPerSecond: number;
+  allow(bytes: number): boolean;
+  update(deltaSeconds: number): void;
+  reset(): void;
+  getUsage(): number;
+}
+
+export interface Message {
+  data: Uint8Array;
+  size: number;
+  timestamp: number;
+}
+
+export interface BandwidthScenario {
+  bandwidth: number;
+  clients: Client[];
+  duration: number;
+  totalBytesSent: number;
+  totalBytesReceived: number;
+  droppedPackets: number;
+}
+
+/**
+ * Creates a mock rate limiter for bandwidth testing
+ * @param bytesPerSecond - Maximum bytes per second allowed
+ */
+export function createMockRateLimiter(bytesPerSecond: number): RateLimiter {
+  let bucket = bytesPerSecond;
+  const maxBucket = bytesPerSecond; // Max burst size equal to 1 second of bandwidth
+  let usage = 0;
+
+  return {
+    bytesPerSecond,
+    allow(bytes: number): boolean {
+      if (bucket >= bytes) {
+        bucket -= bytes;
+        usage += bytes;
+        return true;
+      }
+      return false;
+    },
+    update(deltaSeconds: number): void {
+      bucket += bytesPerSecond * deltaSeconds;
+      if (bucket > maxBucket) {
+        bucket = maxBucket;
+      }
+    },
+    reset(): void {
+      bucket = maxBucket;
+      usage = 0;
+    },
+    getUsage(): number {
+      return usage;
+    }
+  };
+}
+
+/**
+ * Simulates bandwidth limiting on a stream of messages
+ * @param messages - Array of messages to process
+ * @param bandwidth - Bandwidth limit in bytes per second
+ * @returns Filtered array of messages that passed the bandwidth check
+ */
+export function simulateBandwidthLimit(messages: Message[], bandwidth: number): Message[] {
+  const limiter = createMockRateLimiter(bandwidth);
+  const result: Message[] = [];
+  let lastTime = messages.length > 0 ? messages[0].timestamp : 0;
+
+  for (const msg of messages) {
+    const delta = (msg.timestamp - lastTime) / 1000;
+    if (delta > 0) {
+      limiter.update(delta);
+    }
+    lastTime = msg.timestamp;
+
+    if (limiter.allow(msg.size)) {
+      result.push(msg);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Calculates the size of a client snapshot in bytes
+ * @param snapshot - The client frame snapshot
+ */
+export function measureSnapshotSize(snapshot: ClientFrame): number {
+  let size = 0;
+
+  // Area bits
+  size += snapshot.areaBytes;
+
+  // Player state (approximate based on struct size or serialization)
+  // This is an estimation, as actual network serialization compresses this
+  size += 200; // Baseline size for PlayerState
+
+  // Entities
+  // Each EntityState is approx 20-30 bytes compressed
+  size += snapshot.entities.length * 20;
+
+  return size;
+}
+
+/**
+ * Creates a scenario for testing bandwidth limits with multiple clients
+ * @param bandwidth - Bandwidth limit per client or total
+ * @param numClients - Number of clients to simulate
+ */
+export function createBandwidthTestScenario(bandwidth: number, numClients: number): BandwidthScenario {
+  const clients: Client[] = [];
+  // Populate with mock clients if needed (currently creating dummy objects to satisfy type)
+  // In a real scenario we might use createClient factory but that requires net driver
+  // For now we assume caller will populate fully or we return empty array if 0
+
+  return {
+    bandwidth,
+    clients,
+    duration: 0,
+    totalBytesSent: 0,
+    totalBytesReceived: 0,
+    droppedPackets: 0
+  };
+}

package/src/server/helpers/multiplayer.ts

@@ -0,0 +1,158 @@
+import { Server, Client, ClientState, ServerState, ServerStatic } from '@quake2ts/server';
+import { Entity } from '@quake2ts/game';
+import { UserCommand } from '@quake2ts/shared';
+import { createMockServerState } from '../mocks/state.js';
+import { createMockServerClient } from '../mocks/state.js';
+import { createMockUserInfo, serializeUserInfo, UserInfo } from '../mocks/connection.js';
+
+// Define a type that combines Server and ServerStatic for convenience in tests
+// since the real server implementation splits these but tests often need both.
+export type MockServerContext = Server & {
+    clients: (Client | null)[];
+    entities?: Entity[];
+};
+
+export interface MultiplayerScenario {
+    server: MockServerContext;
+    clients: Client[];
+    entities: Entity[];
+}
+
+/**
+ * Creates a multiplayer test scenario with a mock server and a number of clients.
+ * @param numPlayers Number of players to simulate.
+ */
+export function createMultiplayerTestScenario(numPlayers: number = 2): MultiplayerScenario {
+    const baseServer = createMockServerState();
+    const clients: Client[] = [];
+    const entities: Entity[] = [];
+
+    const server: MockServerContext = {
+        ...baseServer,
+        clients: new Array(numPlayers).fill(null),
+        entities: []
+    };
+
+    for (let i = 0; i < numPlayers; i++) {
+        // Create client
+        const client = createMockServerClient(i, {
+            state: ClientState.Active,
+            userInfo: serializeUserInfo(createMockUserInfo({ name: `Player${i}` }))
+        });
+
+        // Create player entity
+        const entity = {
+            classname: 'player',
+            s: { origin: { x: 0, y: 0, z: 0 }, number: i + 1 },
+            client: client
+        } as unknown as Entity;
+
+        client.edict = entity;
+        server.clients[i] = client;
+        clients.push(client);
+        entities.push(entity);
+    }
+
+    // Assign entities to server
+    server.entities = entities;
+
+    return {
+        server,
+        clients,
+        entities
+    };
+}
+
+/**
+ * Simulates a player joining the server.
+ * @param server The mock server instance.
+ * @param userInfo Optional user info overrides.
+ */
+export async function simulatePlayerJoin(server: MockServerContext, userInfo?: Partial<UserInfo>): Promise<Client> {
+    // Find free client slot
+    const index = server.clients.findIndex((c) => !c || c.state === ClientState.Free);
+    if (index === -1) {
+        throw new Error('Server full');
+    }
+
+    const client = createMockServerClient(index, {
+        state: ClientState.Connected,
+        userInfo: serializeUserInfo(createMockUserInfo(userInfo))
+    });
+
+    server.clients[index] = client;
+
+    // Simulate connection process
+    client.state = ClientState.Active;
+
+    // Create entity
+    const entity = {
+        classname: 'player',
+        s: { origin: { x: 0, y: 0, z: 0 }, number: index + 1 },
+        client: client
+    } as unknown as Entity;
+    client.edict = entity;
+
+    // Add to entities list if possible (mock behavior)
+    if (server.entities && Array.isArray(server.entities)) {
+         // This is a simplified view, normally entities are in a fixed array
+        (server.entities as Entity[])[index + 1] = entity;
+    }
+
+    return client;
+}
+
+/**
+ * Simulates a player leaving the server.
+ * @param server The mock server instance.
+ * @param clientNum The client number to disconnect.
+ */
+export function simulatePlayerLeave(server: MockServerContext, clientNum: number): void {
+    const client = server.clients[clientNum];
+    if (client) {
+        client.state = ClientState.Free;
+        client.edict = null;
+    }
+}
+
+/**
+ * Simulates a single server frame update.
+ * @param server The mock server instance.
+ * @param deltaTime Time step in seconds (default: 0.1).
+ */
+export function simulateServerTick(server: MockServerContext, deltaTime: number = 0.1): void {
+    server.time += deltaTime;
+    server.frame++;
+    // In a real server, we would call RunFrame, Physics, etc.
+    // For mocks, we might just update client lastCmd times
+
+    server.clients.forEach((client: Client | null) => {
+        if (client && client.state === ClientState.Active) {
+            // Update client logic if needed
+        }
+    });
+}
+
+/**
+ * Simulates player input for a specific client.
+ * @param client The server client.
+ * @param input The input command.
+ */
+export function simulatePlayerInput(client: Client, input: Partial<UserCommand>): void {
+    const cmd: UserCommand = {
+        msec: 100,
+        buttons: 0,
+        angles: { x: 0, y: 0, z: 0 },
+        forwardmove: 0,
+        sidemove: 0,
+        upmove: 0,
+        sequence: client.lastCmd.sequence + 1,
+        lightlevel: 0,
+        impulse: 0,
+        ...input
+    };
+
+    client.lastCmd = cmd;
+    client.commandQueue.push(cmd);
+    client.commandCount++;
+}

package/src/server/helpers/snapshot.ts

@@ -0,0 +1,241 @@
+import { Server } from '@quake2ts/server';
+import { EntityState, BinaryStream, ProtocolPlayerState } from '@quake2ts/shared';
+
+export interface Snapshot {
+    serverTime: number;
+    playerState: any; // Simplified PlayerState
+    entities: EntityState[];
+}
+
+export interface DeltaSnapshot {
+    snapshot: Snapshot;
+    deltaEntities: EntityState[];
+    removedEntities: number[];
+}
+
+export interface ConsistencyReport {
+    valid: boolean;
+    errors: string[];
+}
+
+/**
+ * Creates a client-specific snapshot from the server state.
+ * @param serverState The current server state.
+ * @param clientNum The client number to generate snapshot for.
+ */
+export function createServerSnapshot(serverState: Server, clientNum: number): Snapshot {
+    // Collect visible entities
+    const visibleEntities: EntityState[] = [];
+
+    // In a real implementation, this would use PVS/PHS
+    // For mock, we just take all entities that have a model or are solid
+    if (serverState.baselines) {
+        serverState.baselines.forEach((ent: EntityState | null, index: number) => {
+            if (ent && index !== clientNum + 1) { // Skip self in packet entities usually
+                visibleEntities.push({ ...ent });
+            }
+        });
+    }
+
+    return {
+        serverTime: serverState.time,
+        playerState: {
+            origin: { x: 0, y: 0, z: 0 },
+            viewangles: { x: 0, y: 0, z: 0 },
+            pm_type: 0
+        },
+        entities: visibleEntities
+    };
+}
+
+/**
+ * Calculates the delta between two snapshots.
+ * @param oldSnapshot The baseline snapshot.
+ * @param newSnapshot The current snapshot.
+ */
+export function createDeltaSnapshot(oldSnapshot: Snapshot, newSnapshot: Snapshot): DeltaSnapshot {
+    const deltaEntities: EntityState[] = [];
+    const removedEntities: number[] = [];
+
+    const oldMap = new Map(oldSnapshot.entities.map(e => [e.number, e]));
+    const newMap = new Map(newSnapshot.entities.map(e => [e.number, e]));
+
+    // Find changed or new entities
+    newSnapshot.entities.forEach(newEnt => {
+        const oldEnt = oldMap.get(newEnt.number);
+        if (!oldEnt) {
+            // New entity
+            deltaEntities.push(newEnt);
+        } else if (JSON.stringify(newEnt) !== JSON.stringify(oldEnt)) {
+            // Changed entity (simplified check)
+            deltaEntities.push(newEnt);
+        }
+    });
+
+    // Find removed entities
+    oldSnapshot.entities.forEach(oldEnt => {
+        if (!newMap.has(oldEnt.number)) {
+            removedEntities.push(oldEnt.number);
+        }
+    });
+
+    return {
+        snapshot: newSnapshot,
+        deltaEntities,
+        removedEntities
+    };
+}
+
+/**
+ * Verifies the consistency of a sequence of snapshots.
+ * @param snapshots Array of snapshots ordered by time.
+ */
+export function verifySnapshotConsistency(snapshots: Snapshot[]): ConsistencyReport {
+    const report: ConsistencyReport = { valid: true, errors: [] };
+
+    if (snapshots.length < 2) return report;
+
+    for (let i = 1; i < snapshots.length; i++) {
+        const prev = snapshots[i-1];
+        const curr = snapshots[i];
+
+        if (curr.serverTime <= prev.serverTime) {
+            report.valid = false;
+            report.errors.push(`Snapshot ${i} has time ${curr.serverTime} <= prev ${prev.serverTime}`);
+        }
+    }
+
+    return report;
+}
+
+/**
+ * Simulates network delivery of a snapshot with potential packet loss.
+ * @param snapshot The snapshot to deliver.
+ * @param reliability Probability of successful delivery (0.0 to 1.0).
+ */
+export async function simulateSnapshotDelivery(snapshot: Snapshot, reliability: number = 1.0): Promise<Snapshot | null> {
+    if (Math.random() > reliability) {
+        return null;
+    }
+    return snapshot;
+}
+
+/**
+ * Parses a ProtocolPlayerState from a binary buffer.
+ * Useful for testing player state serialization.
+ * logic adapted from packages/engine/src/demo/parser.ts
+ * @param data The binary data to parse.
+ */
+export function parseProtocolPlayerState(data: Uint8Array): ProtocolPlayerState {
+    const stream = new BinaryStream(data.buffer as ArrayBuffer);
+    const ps: ProtocolPlayerState = {
+        pm_type: 0,
+        origin: { x: 0, y: 0, z: 0 },
+        velocity: { x: 0, y: 0, z: 0 },
+        pm_time: 0,
+        pm_flags: 0,
+        gravity: 0,
+        delta_angles: { x: 0, y: 0, z: 0 },
+        viewoffset: { x: 0, y: 0, z: 0 },
+        viewangles: { x: 0, y: 0, z: 0 },
+        kick_angles: { x: 0, y: 0, z: 0 },
+        gun_index: 0,
+        gun_frame: 0,
+        gun_offset: { x: 0, y: 0, z: 0 },
+        gun_angles: { x: 0, y: 0, z: 0 },
+        blend: [0, 0, 0, 0],
+        fov: 0,
+        rdflags: 0,
+        stats: new Array(32).fill(0),
+        watertype: 0
+    };
+
+    const flags = stream.readShort();
+
+    if (flags & 1) ps.pm_type = stream.readByte();
+
+    if (flags & 2) {
+        const x = stream.readShort() * 0.125;
+        const y = stream.readShort() * 0.125;
+        const z = stream.readShort() * 0.125;
+        ps.origin = { x, y, z };
+    }
+
+    if (flags & 4) {
+        const x = stream.readShort() * 0.125;
+        const y = stream.readShort() * 0.125;
+        const z = stream.readShort() * 0.125;
+        ps.velocity = { x, y, z };
+    }
+
+    if (flags & 8) ps.pm_time = stream.readByte();
+    if (flags & 16) ps.pm_flags = stream.readByte();
+    if (flags & 32) ps.gravity = stream.readShort();
+
+    if (flags & 64) {
+        const x = stream.readShort() * (180 / 32768);
+        const y = stream.readShort() * (180 / 32768);
+        const z = stream.readShort() * (180 / 32768);
+        ps.delta_angles = { x, y, z };
+    }
+
+    if (flags & 128) {
+        const x = stream.readChar() * 0.25;
+        const y = stream.readChar() * 0.25;
+        const z = stream.readChar() * 0.25;
+        ps.viewoffset = { x, y, z };
+    }
+
+    if (flags & 256) {
+        const x = stream.readAngle16();
+        const y = stream.readAngle16();
+        const z = stream.readAngle16();
+        ps.viewangles = { x, y, z };
+    }
+
+    if (flags & 512) {
+        const x = stream.readChar() * 0.25;
+        const y = stream.readChar() * 0.25;
+        const z = stream.readChar() * 0.25;
+        ps.kick_angles = { x, y, z };
+    }
+
+    if (flags & 4096) ps.gun_index = stream.readByte();
+
+    if (flags & 8192) {
+        ps.gun_frame = stream.readByte();
+        const ox = stream.readChar() * 0.25;
+        const oy = stream.readChar() * 0.25;
+        const oz = stream.readChar() * 0.25;
+        ps.gun_offset = { x: ox, y: oy, z: oz };
+
+        const ax = stream.readChar() * 0.25;
+        const ay = stream.readChar() * 0.25;
+        const az = stream.readChar() * 0.25;
+        ps.gun_angles = { x: ax, y: ay, z: az };
+    }
+
+    if (flags & 1024) {
+        ps.blend = [
+            stream.readByte(),
+            stream.readByte(),
+            stream.readByte(),
+            stream.readByte()
+        ];
+    }
+
+    if (flags & 2048) ps.fov = stream.readByte();
+    if (flags & 16384) ps.rdflags = stream.readByte();
+
+    // New: watertype (bit 15)
+    if (flags & 32768) ps.watertype = stream.readByte();
+
+    const statbits = stream.readLong();
+    for (let i = 0; i < 32; i++) {
+        if (statbits & (1 << i)) {
+            ps.stats[i] = stream.readShort();
+        }
+    }
+
+    return ps;
+}