@quake2ts/test-utils 0.0.1

package/src/server/mockNetDriver.ts

@@ -0,0 +1,106 @@
+import { NetDriver } from '@quake2ts/shared';
+import { vi } from 'vitest';
+
+export interface MockNetDriverState {
+    connected: boolean;
+    messagesSent: Uint8Array[];
+    messageHandlers: ((data: Uint8Array) => void)[];
+    closeHandlers: (() => void)[];
+    errorHandlers: ((err: Error) => void)[];
+}
+
+/**
+ * A mock implementation of NetDriver that provides testing hooks.
+ * Unlike the simple createMockNetDriver factory, this class maintains state
+ * and allows for stimulating events (receiving messages, triggering errors).
+ */
+export class MockNetDriver implements NetDriver {
+    public state: MockNetDriverState = {
+        connected: false,
+        messagesSent: [],
+        messageHandlers: [],
+        closeHandlers: [],
+        errorHandlers: []
+    };
+
+    public connectSpy = vi.fn().mockImplementation(async (url: string) => {
+        this.state.connected = true;
+    });
+
+    public disconnectSpy = vi.fn().mockImplementation(() => {
+        this.state.connected = false;
+        this.state.closeHandlers.forEach(h => h());
+    });
+
+    public sendSpy = vi.fn().mockImplementation((data: Uint8Array) => {
+        this.state.messagesSent.push(new Uint8Array(data));
+    });
+
+    public connect(url: string): Promise<void> {
+        return this.connectSpy(url);
+    }
+
+    public disconnect(): void {
+        this.disconnectSpy();
+    }
+
+    public send(data: Uint8Array): void {
+        this.sendSpy(data);
+    }
+
+    public onMessage(cb: (data: Uint8Array) => void): void {
+        this.state.messageHandlers.push(cb);
+    }
+
+    public onClose(cb: () => void): void {
+        this.state.closeHandlers.push(cb);
+    }
+
+    public onError(cb: (err: Error) => void): void {
+        this.state.errorHandlers.push(cb);
+    }
+
+    public isConnected(): boolean {
+        return this.state.connected;
+    }
+
+    // --- Test Helpers ---
+
+    /**
+     * Simulate receiving a message from the network.
+     */
+    public receiveMessage(data: Uint8Array): void {
+        this.state.messageHandlers.forEach(h => h(data));
+    }
+
+    /**
+     * Simulate a connection close event from the remote side.
+     */
+    public simulateClose(): void {
+        this.state.connected = false;
+        this.state.closeHandlers.forEach(h => h());
+    }
+
+    /**
+     * Simulate a connection error.
+     */
+    public simulateError(err: Error): void {
+        this.state.errorHandlers.forEach(h => h(err));
+    }
+
+    /**
+     * Get the last sent message.
+     */
+    public getLastSentMessage(): Uint8Array | undefined {
+        return this.state.messagesSent.length > 0
+            ? this.state.messagesSent[this.state.messagesSent.length - 1]
+            : undefined;
+    }
+
+    /**
+     * Clear recorded sent messages.
+     */
+    public clearSentMessages(): void {
+        this.state.messagesSent = [];
+    }
+}

package/src/server/mockTransport.ts

@@ -0,0 +1,50 @@
+import { NetChan } from '@quake2ts/shared';
+
+export interface RecordedPacket {
+  type: 'sent' | 'received';
+  timestamp: number;
+  data: Uint8Array;
+}
+
+export class MockNetworkTransport {
+  public netchan: NetChan;
+  public recordedPackets: RecordedPacket[] = [];
+  public sentPackets: Uint8Array[] = [];
+
+  constructor() {
+    this.netchan = new NetChan();
+    this.netchan.setup(1234, { type: 'loopback', port: 0 });
+  }
+
+  reset() {
+    this.recordedPackets = [];
+    this.sentPackets = [];
+    this.netchan.reset();
+  }
+
+  // Simulate receiving data from the "server"
+  receive(data: Uint8Array) {
+    this.recordedPackets.push({
+      type: 'received',
+      timestamp: Date.now(),
+      data: new Uint8Array(data)
+    });
+    return this.netchan.process(data);
+  }
+
+  // Simulate sending data (called by the client using this transport)
+  transmit(unreliableData?: Uint8Array) {
+    const packet = this.netchan.transmit(unreliableData);
+    this.recordedPackets.push({
+      type: 'sent',
+      timestamp: Date.now(),
+      data: new Uint8Array(packet)
+    });
+    this.sentPackets.push(new Uint8Array(packet));
+    return packet;
+  }
+
+  get lastSentPacket() {
+    return this.sentPackets.length > 0 ? this.sentPackets[this.sentPackets.length - 1] : undefined;
+  }
+}

package/src/server/mocks/commands.ts

@@ -0,0 +1,93 @@
+import { vi } from 'vitest';
+import { ServerCommand } from '@quake2ts/shared';
+
+/**
+ * Interface for a mocked server console that can execute commands.
+ * Reference: quake2/server/sv_main.c (SV_ExecuteUserCommand)
+ */
+export interface MockServerConsole {
+    exec(cmd: string): string;
+    print(text: string): void;
+    broadcast(text: string): void;
+    commandBuffer: string[];
+    outputBuffer: string[];
+}
+
+/**
+ * Creates a mock server console.
+ * @param overrides Optional overrides for the mock console.
+ */
+export function createMockServerConsole(overrides?: Partial<MockServerConsole>): MockServerConsole {
+    const outputBuffer: string[] = [];
+    const commandBuffer: string[] = [];
+
+    return {
+        exec: vi.fn((cmd: string) => {
+            commandBuffer.push(cmd);
+            return `Executed: ${cmd}`;
+        }),
+        print: vi.fn((text: string) => {
+            outputBuffer.push(text);
+        }),
+        broadcast: vi.fn((text: string) => {
+            outputBuffer.push(`Broadcast: ${text}`);
+        }),
+        commandBuffer,
+        outputBuffer,
+        ...overrides
+    };
+}
+
+/**
+ * Interface for a mocked RCON client.
+ * Reference: quake2/server/sv_user.c (SV_ExecuteUserCommand for RCON handling)
+ */
+export interface MockRConClient {
+    connect(address: string, port: number, password?: string): Promise<boolean>;
+    sendCommand(cmd: string): Promise<string>;
+    disconnect(): void;
+    connected: boolean;
+    lastCommand: string;
+    lastResponse: string;
+}
+
+/**
+ * Creates a mock RCON client.
+ * @param password Optional password for the client to use.
+ */
+export function createMockRConClient(password: string = ''): MockRConClient {
+    return {
+        connected: false,
+        lastCommand: '',
+        lastResponse: '',
+        connect: vi.fn(async (address, port, pwd) => {
+            return pwd === password; // Simple mock: connect succeeds if password matches constructor password
+        }),
+        sendCommand: vi.fn(async (cmd) => {
+            return `RCON Response for: ${cmd}`;
+        }),
+        disconnect: vi.fn(),
+    };
+}
+
+/**
+ * Simulates a command execution on the server.
+ * @param server The mock server instance (assumed to have some command handling capability).
+ * @param command The command string to execute.
+ * @returns The output of the command.
+ */
+export function simulateServerCommand(server: any, command: string): string {
+    // This assumes the server has a method to execute commands, or we simulate the effect.
+    // In a real integration, this might interact with the server's command buffer.
+    if (server.executeBuffer) {
+        server.executeBuffer(command);
+        return "Executed";
+    }
+
+    // Fallback for mocked servers
+    if (server.exec) {
+        return server.exec(command);
+    }
+
+    return "Unknown command handler";
+}

package/src/server/mocks/connection.ts

@@ -0,0 +1,139 @@
+import { Client, ClientState } from '@quake2ts/server';
+import { createMockServerClient } from './state.js';
+
+/**
+ * Interface representing connection state for testing.
+ */
+export interface Connection {
+    state: ClientState;
+    address: string;
+    challenge: number;
+    userInfo: UserInfo;
+}
+
+/**
+ * Stages of the client connection handshake.
+ */
+export enum HandshakeStage {
+    None = 0,
+    Challenge = 1,
+    Connect = 2,
+    Info = 3,
+    Active = 4
+}
+
+/**
+ * Interface representing a handshake state.
+ */
+export interface Handshake {
+    stage: HandshakeStage;
+    clientNum: number;
+    challenge: number;
+    qport: number;
+}
+
+/**
+ * Interface for UserInfo structure.
+ */
+export interface UserInfo {
+    name: string;
+    skin: string;
+    model: string;
+    fov: number;
+    hand: number;
+    rate: number;
+    msg: number;
+    spectator?: number;
+    [key: string]: string | number | undefined;
+}
+
+/**
+ * Helper to serialize UserInfo to Quake 2 info string format.
+ * Format: \key\value\key2\value2
+ */
+export function serializeUserInfo(info: UserInfo): string {
+    return Object.entries(info).reduce((acc, [key, value]) => {
+        if (value !== undefined) {
+            return `${acc}\\${key}\\${value}`;
+        }
+        return acc;
+    }, '');
+}
+
+/**
+ * Creates a mock UserInfo object.
+ * @param overrides Optional overrides for the user info.
+ */
+export function createMockUserInfo(overrides?: Partial<UserInfo>): UserInfo {
+    return {
+        name: 'Player',
+        skin: 'male/grunt',
+        model: 'male/grunt',
+        fov: 90,
+        hand: 0,
+        rate: 25000,
+        msg: 1,
+        ...overrides
+    };
+}
+
+/**
+ * Creates a mock connection object (Client) with specific state.
+ * @param state The client state (default: Connected).
+ * @param overrides Optional overrides for the client.
+ */
+export function createMockConnection(state: ClientState = ClientState.Connected, overrides?: Partial<Client>): Client {
+    return createMockServerClient(0, {
+        state,
+        userInfo: serializeUserInfo(createMockUserInfo()),
+        challenge: Math.floor(Math.random() * 100000),
+        ...overrides
+    });
+}
+
+/**
+ * Creates a mock handshake object.
+ * @param stage The stage of the handshake (default: None).
+ */
+export function createMockHandshake(stage: HandshakeStage = HandshakeStage.None): Handshake {
+    return {
+        stage,
+        clientNum: -1,
+        challenge: 0,
+        qport: Math.floor(Math.random() * 65536)
+    };
+}
+
+/**
+ * Simulates a handshake between a mock client and server.
+ * Note: This is a high-level simulation helper.
+ * @param client The mock client connection.
+ * @param server The mock server instance.
+ * @returns Promise that resolves to true if handshake succeeded.
+ */
+export async function simulateHandshake(client: Client, server: any): Promise<boolean> {
+    // 1. Get Challenge
+    // In a real scenario, client sends getchallenge, server responds with challenge
+    const challenge = Math.floor(Math.random() * 100000);
+    client.challenge = challenge;
+
+    // 2. Connect
+    // Client sends connect command with qport, challenge, userinfo
+    // Server assigns client slot
+    if (server && server.clients) {
+         // rudimentary check if server has space
+    }
+
+    // 3. Update state to Connected
+    client.state = ClientState.Connected;
+
+    // 4. Send configstrings (usually handled by server)
+
+    // 5. Client enters game (prespawn)
+    // Server sends stuff
+
+    // 6. Client ready
+    client.state = ClientState.Active;
+
+    return true;
+}

package/src/server/mocks/master.ts

@@ -0,0 +1,97 @@
+import { Client } from '@quake2ts/server';
+
+export interface MasterServer {
+  registerServer(info: ServerInfo): Promise<boolean>;
+  heartbeat(serverAddress: string): Promise<boolean>;
+  getServerList(filter?: ServerListFilter): Promise<ServerInfo[]>;
+}
+
+export interface ServerInfo {
+  address: string;
+  name: string;
+  map: string;
+  players: number;
+  maxPlayers: number;
+  gametype: string;
+  version: string;
+  password?: boolean;
+}
+
+export interface ServerListFilter {
+  gametype?: string;
+  map?: string;
+  notEmpty?: boolean;
+  notFull?: boolean;
+}
+
+/**
+ * Creates a mock master server for testing server registration and browsing
+ * @param overrides - Optional overrides for the master server behavior
+ */
+export function createMockMasterServer(overrides: Partial<MasterServer> = {}): MasterServer {
+  const servers = new Map<string, ServerInfo>();
+
+  return {
+    registerServer: async (info: ServerInfo): Promise<boolean> => {
+      servers.set(info.address, info);
+      return true;
+    },
+    heartbeat: async (serverAddress: string): Promise<boolean> => {
+      return servers.has(serverAddress);
+    },
+    getServerList: async (filter?: ServerListFilter): Promise<ServerInfo[]> => {
+      let list = Array.from(servers.values());
+
+      if (filter) {
+        if (filter.gametype) {
+          list = list.filter(s => s.gametype === filter.gametype);
+        }
+        if (filter.map) {
+          list = list.filter(s => s.map === filter.map);
+        }
+        if (filter.notEmpty) {
+          list = list.filter(s => s.players > 0);
+        }
+        if (filter.notFull) {
+          list = list.filter(s => s.players < s.maxPlayers);
+        }
+      }
+
+      return list;
+    },
+    ...overrides
+  };
+}
+
+/**
+ * Creates a mock server info object
+ * @param overrides - Optional overrides
+ */
+export function createMockServerInfo(overrides: Partial<ServerInfo> = {}): ServerInfo {
+  return {
+    address: '127.0.0.1:27910',
+    name: 'Quake 2 Test Server',
+    map: 'q2dm1',
+    players: 0,
+    maxPlayers: 16,
+    gametype: 'deathmatch',
+    version: '1.0',
+    ...overrides
+  };
+}
+
+/**
+ * Simulates the process of a game server registering with the master server
+ * @param server - The mock game server instance (typed as any to accept mock)
+ * @param master - The mock master server
+ */
+export async function simulateServerRegistration(server: any, master: MasterServer): Promise<boolean> {
+  const info = createMockServerInfo({
+    name: server.name || 'Test Server',
+    map: server.mapName || 'q2dm1',
+    players: server.clients ? server.clients.filter((c: Client | null) => c && c.state >= 2).length : 0,
+    maxPlayers: server.maxClients || 16
+  });
+
+  return master.registerServer(info);
+}

package/src/server/mocks/physics.ts

@@ -0,0 +1,32 @@
+import { vi } from 'vitest';
+import { TraceResult } from '@quake2ts/shared';
+
+/**
+ * Mock interface for CollisionEntityIndex.
+ */
+export interface MockCollisionEntityIndex {
+    trace: (start: any, mins: any, maxs: any, end: any, passEntity: any, contentMask: number) => TraceResult;
+    link: (entity: any) => void;
+    unlink: (entity: any) => void;
+    gatherTriggerTouches: (entity: any) => any[];
+}
+
+/**
+ * Creates a mock CollisionEntityIndex.
+ * @param overrides Optional overrides for the mock methods.
+ */
+export function createMockCollisionEntityIndex(overrides?: Partial<MockCollisionEntityIndex>): MockCollisionEntityIndex {
+    return {
+        trace: vi.fn().mockReturnValue({
+            fraction: 1.0,
+            allsolid: false,
+            startsolid: false,
+            endpos: { x: 0, y: 0, z: 0 },
+            entityId: null
+        }),
+        link: vi.fn(),
+        unlink: vi.fn(),
+        gatherTriggerTouches: vi.fn().mockReturnValue([]),
+        ...overrides
+    };
+}

package/src/server/mocks/state.ts

@@ -0,0 +1,162 @@
+import { Server, ServerState, ServerStatic, Client, ClientState } from '@quake2ts/server';
+import { NetDriver, MAX_CONFIGSTRINGS, MAX_EDICTS, EntityState } from '@quake2ts/shared';
+import { Entity } from '@quake2ts/game';
+import { vi } from 'vitest';
+import { createMockNetDriver } from './transport.js';
+
+// Define GameState interface locally or import from where it should be.
+// Based on grep, GameStateSnapshot is in @quake2ts/game.
+// But test-utils/src/game/mocks.ts defines a local GameState interface.
+// Let's use that one or define a compatible one here.
+import { GameState } from '../../game/mocks.js';
+
+/**
+ * Creates a mock server state object.
+ * @param overrides Optional overrides for the server state.
+ */
+export function createMockServerState(overrides?: Partial<Server>): Server {
+    return {
+        state: ServerState.Game,
+        attractLoop: false,
+        loadGame: false,
+        startTime: Date.now(),
+        time: 0,
+        frame: 0,
+        name: 'test_map',
+        collisionModel: null,
+        configStrings: new Array(MAX_CONFIGSTRINGS).fill(''),
+        baselines: new Array(MAX_EDICTS).fill(null),
+        multicastBuf: new Uint8Array(0),
+        ...overrides
+    };
+}
+
+/**
+ * Creates a mock server static object.
+ * @param maxClients Maximum number of clients.
+ * @param overrides Optional overrides for the server static state.
+ */
+export function createMockServerStatic(maxClients: number = 16, overrides?: Partial<ServerStatic>): ServerStatic {
+    return {
+        initialized: true,
+        realTime: Date.now(),
+        mapCmd: '',
+        spawnCount: 1,
+        clients: new Array(maxClients).fill(null),
+        lastHeartbeat: 0,
+        challenges: [],
+        ...overrides
+    };
+}
+
+/**
+ * Creates a mock server client.
+ * @param clientNum The client index.
+ * @param overrides Optional overrides for the client.
+ */
+export function createMockServerClient(clientNum: number, overrides?: Partial<Client>): Client {
+    // Create a minimal mock net driver
+    const mockNet: NetDriver = createMockNetDriver();
+
+    return {
+        index: clientNum,
+        state: ClientState.Connected,
+        edict: { index: clientNum + 1 } as Entity,
+        net: mockNet,
+        netchan: {
+            qport: 0,
+            remoteAddress: '127.0.0.1',
+            incomingSequence: 0,
+            outgoingSequence: 0,
+            lastReceived: 0,
+            process: vi.fn(),
+            transmit: vi.fn(),
+            writeReliableByte: vi.fn(),
+            writeReliableShort: vi.fn(),
+            writeReliableLong: vi.fn(),
+            writeReliableString: vi.fn(),
+            writeReliableData: vi.fn(),
+        } as any, // Cast as any because NetChan might be complex to fully mock here
+        userInfo: '',
+        lastMessage: 0,
+        lastCommandTime: 0,
+        commandCount: 0,
+        messageQueue: [],
+        frames: [],
+        lastFrame: 0,
+        lastPacketEntities: [],
+        challenge: 0,
+        lastConnect: 0,
+        ping: 0,
+        rate: 0,
+        name: `Client${clientNum}`,
+        messageLevel: 0,
+        datagram: new Uint8Array(0),
+        downloadSize: 0,
+        downloadCount: 0,
+        commandMsec: 0,
+        frameLatency: [],
+        messageSize: [],
+        suppressCount: 0,
+        commandQueue: [],
+        lastCmd: {
+            msec: 0,
+            buttons: 0,
+            angles: { x: 0, y: 0, z: 0 },
+            forwardmove: 0,
+            sidemove: 0,
+            upmove: 0,
+            sequence: 0,
+            lightlevel: 0,
+            impulse: 0,
+            serverFrame: 0
+        },
+        ...overrides
+    };
+}
+
+/**
+ * Mock interface for the Server class (DedicatedServer).
+ * This allows mocking the server instance itself.
+ */
+export interface MockServer {
+    start(mapName: string): Promise<void>;
+    stop(): void;
+    // tick(): void; // runFrame is private in DedicatedServer, usually we simulate via game.frame
+    multicast(origin: any, type: any, event: any, ...args: any[]): void;
+    unicast(ent: Entity, reliable: boolean, event: any, ...args: any[]): void;
+    configstring(index: number, value: string): void;
+    kickPlayer(clientId: number): void;
+    changeMap(mapName: string): Promise<void>;
+    getClient(clientNum: number): Client | null;
+    broadcast(message: string): void;
+    tick(): void;
+}
+
+/**
+ * Creates a mock server instance.
+ * @param overrides Optional overrides for server methods.
+ */
+export function createMockServer(overrides?: Partial<MockServer>): MockServer {
+    return {
+        start: vi.fn().mockResolvedValue(undefined),
+        stop: vi.fn(),
+        multicast: vi.fn(),
+        unicast: vi.fn(),
+        configstring: vi.fn(),
+        kickPlayer: vi.fn(),
+        changeMap: vi.fn().mockResolvedValue(undefined),
+        getClient: vi.fn().mockReturnValue(null),
+        broadcast: vi.fn(),
+        tick: vi.fn(),
+        ...overrides
+    };
+}
+
+// Re-export GameState from game mocks if needed, or use the one from game/mocks
+// Since we have a createMockGameState in game/mocks.ts, we should probably use that or alias it.
+// The task says "Add createMockGameState() factory".
+// If it is already in game/mocks.ts, we can just export it from there or re-export it here.
+// But to avoid duplication, I will just re-export the one from game mocks if the intention is to have it available under server utils.
+
+export { createMockGameState, type GameState } from '../../game/mocks.js';