quake2ts 0.0.561 → 0.0.563

package/packages/test-utils/dist/index.d.ts

@@ -1,10 +1,271 @@
-import { ImageData } from '@napi-rs/canvas';
-import { LaunchOptions, BrowserContextOptions, Browser, BrowserContext, Page } from 'playwright';
-import { Server } from 'http';
-import { Vec3, CollisionPlane, CollisionBrush, CollisionNode, CollisionLeaf, CollisionModel, PlayerState, EntityState, createRandomGenerator } from '@quake2ts/shared';
-export { intersects, ladderTrace, stairTrace } from '@quake2ts/shared';
+import * as vitest from 'vitest';
 import { Mock } from 'vitest';
+import { Vec3, CollisionPlane, CollisionBrush, CollisionNode, CollisionLeaf, CollisionModel, PlayerState, EntityState, createRandomGenerator, NetDriver } from '@quake2ts/shared';
+export { intersects, ladderTrace, stairTrace } from '@quake2ts/shared';
 import { GameStateSnapshot, Entity, ScriptHookRegistry, SpawnContext, EntitySystem, SpawnRegistry } from '@quake2ts/game';
+import { NetworkTransport, Server, ServerStatic, Client } from '@quake2ts/server';
+import { ImageData } from '@napi-rs/canvas';
+import { LaunchOptions, BrowserContextOptions, Browser, BrowserContext, Page } from 'playwright';
+import { Server as Server$1 } from 'http';
+
+interface BinaryWriterMock {
+    writeByte: Mock<[number], void>;
+    writeShort: Mock<[number], void>;
+    writeLong: Mock<[number], void>;
+    writeString: Mock<[string], void>;
+    writeBytes: Mock<[Uint8Array], void>;
+    getBuffer: Mock<[], Uint8Array>;
+    reset: Mock<[], void>;
+    writeInt8: Mock<[number], void>;
+    writeUint8: Mock<[number], void>;
+    writeInt16: Mock<[number], void>;
+    writeUint16: Mock<[number], void>;
+    writeInt32: Mock<[number], void>;
+    writeUint32: Mock<[number], void>;
+    writeFloat: Mock<[number], void>;
+    getData: Mock<[], Uint8Array>;
+}
+declare const createBinaryWriterMock: () => BinaryWriterMock;
+declare const createNetChanMock: () => {
+    qport: number;
+    incomingSequence: number;
+    outgoingSequence: number;
+    incomingAcknowledged: number;
+    incomingReliableAcknowledged: boolean;
+    incomingReliableSequence: number;
+    outgoingReliableSequence: number;
+    reliableMessage: BinaryWriterMock;
+    reliableLength: number;
+    fragmentSendOffset: number;
+    fragmentBuffer: null;
+    fragmentLength: number;
+    fragmentReceived: number;
+    lastReceived: number;
+    lastSent: number;
+    remoteAddress: {
+        type: string;
+        port: number;
+    };
+    setup: Mock<any, any>;
+    reset: Mock<any, any>;
+    transmit: Mock<any, any>;
+    process: Mock<any, any>;
+    canSendReliable: Mock<[], boolean>;
+    writeReliableByte: Mock<any, any>;
+    writeReliableShort: Mock<any, any>;
+    writeReliableLong: Mock<any, any>;
+    writeReliableString: Mock<any, any>;
+    getReliableData: Mock<[], Uint8Array<ArrayBufferLike>>;
+    needsKeepalive: Mock<[], boolean>;
+    isTimedOut: Mock<[], boolean>;
+};
+interface BinaryStreamMock {
+    getPosition: Mock<[], number>;
+    getReadPosition: Mock<[], number>;
+    getLength: Mock<[], number>;
+    getRemaining: Mock<[], number>;
+    seek: Mock<[number], void>;
+    setReadPosition: Mock<[number], void>;
+    hasMore: Mock<[], boolean>;
+    hasBytes: Mock<[number], boolean>;
+    readChar: Mock<[], number>;
+    readByte: Mock<[], number>;
+    readShort: Mock<[], number>;
+    readUShort: Mock<[], number>;
+    readLong: Mock<[], number>;
+    readULong: Mock<[], number>;
+    readFloat: Mock<[], number>;
+    readString: Mock<[], string>;
+    readStringLine: Mock<[], string>;
+    readCoord: Mock<[], number>;
+    readAngle: Mock<[], number>;
+    readAngle16: Mock<[], number>;
+    readData: Mock<[number], Uint8Array>;
+    readPos: Mock<[], any>;
+    readDir: Mock<[], any>;
+}
+declare const createBinaryStreamMock: () => BinaryStreamMock;
+
+declare function makePlane(normal: Vec3, dist: number): CollisionPlane;
+declare function makeAxisBrush(size: number, contents?: number): CollisionBrush;
+declare function makeNode(plane: CollisionPlane, children: [number, number]): CollisionNode;
+declare function makeBspModel(planes: CollisionPlane[], nodes: CollisionNode[], leaves: CollisionLeaf[], brushes: CollisionBrush[], leafBrushes: number[]): CollisionModel;
+declare function makeLeaf(contents: number, firstLeafBrush: number, numLeafBrushes: number): CollisionLeaf;
+declare function makeLeafModel(brushes: CollisionBrush[]): CollisionModel;
+declare function makeBrushFromMinsMaxs(mins: Vec3, maxs: Vec3, contents?: number): CollisionBrush;
+
+declare const createPlayerStateFactory: (overrides?: Partial<PlayerState>) => PlayerState;
+declare const createEntityStateFactory: (overrides?: Partial<EntityState>) => EntityState;
+declare const createGameStateSnapshotFactory: (overrides?: Partial<GameStateSnapshot>) => GameStateSnapshot;
+
+interface MockEngine {
+    sound: Mock<[Entity, number, string, number, number, number], void>;
+    soundIndex: Mock<[string], number>;
+    modelIndex: Mock<[string], number>;
+    centerprintf: Mock<[Entity, string], void>;
+}
+interface MockGame {
+    random: ReturnType<typeof createRandomGenerator>;
+    registerEntitySpawn: Mock<[string, (entity: Entity) => void], void>;
+    unregisterEntitySpawn: Mock<[string], void>;
+    getCustomEntities: Mock<[], string[]>;
+    hooks: ScriptHookRegistry;
+    registerHooks: Mock<[any], any>;
+    spawnWorld: Mock<[], void>;
+    clientBegin: Mock<[any], void>;
+    damage: Mock<[number], void>;
+}
+interface TestContext extends SpawnContext {
+    entities: EntitySystem;
+    game: MockGame;
+    engine: MockEngine;
+}
+declare const createMockEngine: () => MockEngine;
+declare const createMockGame: (seed?: number) => {
+    game: MockGame;
+    spawnRegistry: SpawnRegistry;
+};
+declare function createTestContext(options?: {
+    seed?: number;
+    initialEntities?: Entity[];
+}): TestContext;
+declare function createSpawnContext(): SpawnContext;
+declare function createEntity(): Entity;
+
+interface GameState {
+    levelName: string;
+    time: number;
+    entities: Entity[];
+    clients: any[];
+}
+/**
+ * Creates a mock game state object.
+ * @param overrides Optional overrides for the game state.
+ */
+declare function createMockGameState(overrides?: Partial<GameState>): GameState;
+
+/**
+ * Mock implementation of the NetworkTransport interface for server testing.
+ * Allows simulating connections and errors.
+ */
+declare class MockTransport implements NetworkTransport {
+    onConnectionCallback?: (driver: NetDriver, info?: any) => void;
+    onErrorCallback?: (error: Error) => void;
+    address: string;
+    port: number;
+    sentMessages: Uint8Array[];
+    receivedMessages: Uint8Array[];
+    listening: boolean;
+    listenSpy: vitest.Mock<any, any>;
+    closeSpy: vitest.Mock<any, any>;
+    /**
+     * Start listening on the specified port.
+     */
+    listen(port: number): Promise<void>;
+    /**
+     * Close the transport.
+     */
+    close(): void;
+    /**
+     * Register a callback for new connections.
+     */
+    onConnection(callback: (driver: NetDriver, info?: any) => void): void;
+    /**
+     * Register a callback for errors.
+     */
+    onError(callback: (error: Error) => void): void;
+    /**
+     * Check if the transport is currently listening.
+     */
+    isListening(): boolean;
+    /**
+     * Helper to simulate a new connection.
+     * @param driver The network driver for the connection.
+     * @param info Optional connection info.
+     */
+    simulateConnection(driver: NetDriver, info?: any): void;
+    /**
+     * Helper to simulate an error.
+     * @param error The error to simulate.
+     */
+    simulateError(error: Error): void;
+}
+/**
+ * Interface for mock UDP socket.
+ * This is a partial mock of Node.js dgram.Socket or similar.
+ */
+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.
+ */
+declare function createMockUDPSocket(overrides?: Partial<MockUDPSocket>): MockUDPSocket;
+/**
+ * Interface for network address.
+ */
+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)
+ */
+declare function createMockNetworkAddress(ip?: string, port?: number): NetworkAddress;
+/**
+ * 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.
+ */
+declare function createMockTransport(address?: string, port?: number, overrides?: Partial<MockTransport>): MockTransport;
+
+/**
+ * Creates a mock server state object.
+ * @param overrides Optional overrides for the server state.
+ */
+declare function createMockServerState(overrides?: Partial<Server>): Server;
+/**
+ * Creates a mock server static object.
+ * @param maxClients Maximum number of clients.
+ * @param overrides Optional overrides for the server static state.
+ */
+declare function createMockServerStatic(maxClients?: number, overrides?: Partial<ServerStatic>): ServerStatic;
+/**
+ * Creates a mock server client.
+ * @param clientNum The client index.
+ * @param overrides Optional overrides for the client.
+ */
+declare function createMockServerClient(clientNum: number, overrides?: Partial<Client>): Client;
+/**
+ * Mock interface for the Server class (DedicatedServer).
+ * This allows mocking the server instance itself.
+ */
+interface MockServer {
+    start(mapName: string): Promise<void>;
+    stop(): void;
+    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>;
+}
+/**
+ * Creates a mock server instance.
+ * @param overrides Optional overrides for server methods.
+ */
+declare function createMockServer(overrides?: Partial<MockServer>): MockServer;
 
 interface BrowserSetupOptions {
     url?: string;
@@ -49,11 +310,14 @@ declare function createMockImageData(width: number, height: number, fillColor?:
  */
 declare function createMockImage(width?: number, height?: number, src?: string): HTMLImageElement;
 
+interface NodeSetupOptions {
+    polyfillFetch?: boolean;
+}
 /**
  * Sets up a Node.js environment for testing.
  * This is primarily for backend or shared logic that doesn't rely on browser APIs.
  */
-declare function setupNodeEnvironment(): void;
+declare function setupNodeEnvironment(options?: NodeSetupOptions): void;
 
 declare function createMockWebGL2Context(canvas: HTMLCanvasElement): WebGL2RenderingContext;
 
@@ -73,14 +337,14 @@ declare function createMockSessionStorage(initialData?: Record<string, string>):
  */
 declare function createMockIndexedDB(): IDBFactory;
 interface StorageScenario {
-    storage: Storage;
-    populate(data: Record<string, string>): void;
-    verify(key: string, value: string): boolean;
+    storage: Storage | IDBFactory;
+    populate(data: Record<string, any>): Promise<void> | void;
+    verify(key: string, value: any): Promise<boolean> | boolean;
 }
 /**
  * Helper to setup a storage test scenario.
  */
-declare function createStorageTestScenario(storageType?: 'local' | 'session'): StorageScenario;
+declare function createStorageTestScenario(storageType?: 'local' | 'session' | 'indexed'): StorageScenario;
 
 declare function createMockAudioContext(): AudioContext;
 /**
@@ -97,8 +361,7 @@ interface AudioEvent {
 }
 /**
  * Captures audio operations for verification.
- * Currently requires manual instrumentation or a more sophisticated Proxy mock.
- * This is a placeholder for future implementation.
+ * Note: Only works if the context was created via createMockAudioContext which proxies calls.
  */
 declare function captureAudioEvents(context: AudioContext): AudioEvent[];
 
@@ -159,7 +422,7 @@ interface PlaywrightTestClient {
     browser: Browser;
     context: BrowserContext;
     page: Page;
-    server?: Server;
+    server?: Server$1;
     close: () => Promise<void>;
     navigate: (url?: string) => Promise<void>;
     waitForGame: (timeout?: number) => Promise<void>;
@@ -191,128 +454,59 @@ declare class InputInjector {
     wheel(deltaY: number): void;
 }
 
-declare function makePlane(normal: Vec3, dist: number): CollisionPlane;
-declare function makeAxisBrush(size: number, contents?: number): CollisionBrush;
-declare function makeNode(plane: CollisionPlane, children: [number, number]): CollisionNode;
-declare function makeBspModel(planes: CollisionPlane[], nodes: CollisionNode[], leaves: CollisionLeaf[], brushes: CollisionBrush[], leafBrushes: number[]): CollisionModel;
-declare function makeLeaf(contents: number, firstLeafBrush: number, numLeafBrushes: number): CollisionLeaf;
-declare function makeLeafModel(brushes: CollisionBrush[]): CollisionModel;
-declare function makeBrushFromMinsMaxs(mins: Vec3, maxs: Vec3, contents?: number): CollisionBrush;
-
-interface BinaryWriterMock {
-    writeByte: Mock<[number], void>;
-    writeShort: Mock<[number], void>;
-    writeLong: Mock<[number], void>;
-    writeString: Mock<[string], void>;
-    writeBytes: Mock<[Uint8Array], void>;
-    getBuffer: Mock<[], Uint8Array>;
-    reset: Mock<[], void>;
-    writeInt8: Mock<[number], void>;
-    writeUint8: Mock<[number], void>;
-    writeInt16: Mock<[number], void>;
-    writeUint16: Mock<[number], void>;
-    writeInt32: Mock<[number], void>;
-    writeUint32: Mock<[number], void>;
-    writeFloat: Mock<[number], void>;
-    getData: Mock<[], Uint8Array>;
+interface NetworkSimulator {
+    apply(page: any): Promise<void>;
+    clear(page: any): Promise<void>;
 }
-declare const createBinaryWriterMock: () => BinaryWriterMock;
-declare const createNetChanMock: () => {
-    qport: number;
-    incomingSequence: number;
-    outgoingSequence: number;
-    incomingAcknowledged: number;
-    incomingReliableAcknowledged: boolean;
-    incomingReliableSequence: number;
-    outgoingReliableSequence: number;
-    reliableMessage: BinaryWriterMock;
-    reliableLength: number;
-    fragmentSendOffset: number;
-    fragmentBuffer: null;
-    fragmentLength: number;
-    fragmentReceived: number;
-    lastReceived: number;
-    lastSent: number;
-    remoteAddress: {
-        type: string;
-        port: number;
-    };
-    setup: Mock<any, any>;
-    reset: Mock<any, any>;
-    transmit: Mock<any, any>;
-    process: Mock<any, any>;
-    canSendReliable: Mock<[], boolean>;
-    writeReliableByte: Mock<any, any>;
-    writeReliableShort: Mock<any, any>;
-    writeReliableLong: Mock<any, any>;
-    writeReliableString: Mock<any, any>;
-    getReliableData: Mock<[], Uint8Array<ArrayBufferLike>>;
-    needsKeepalive: Mock<[], boolean>;
-    isTimedOut: Mock<[], boolean>;
-};
-interface BinaryStreamMock {
-    getPosition: Mock<[], number>;
-    getReadPosition: Mock<[], number>;
-    getLength: Mock<[], number>;
-    getRemaining: Mock<[], number>;
-    seek: Mock<[number], void>;
-    setReadPosition: Mock<[number], void>;
-    hasMore: Mock<[], boolean>;
-    hasBytes: Mock<[number], boolean>;
-    readChar: Mock<[], number>;
-    readByte: Mock<[], number>;
-    readShort: Mock<[], number>;
-    readUShort: Mock<[], number>;
-    readLong: Mock<[], number>;
-    readULong: Mock<[], number>;
-    readFloat: Mock<[], number>;
-    readString: Mock<[], string>;
-    readStringLine: Mock<[], string>;
-    readCoord: Mock<[], number>;
-    readAngle: Mock<[], number>;
-    readAngle16: Mock<[], number>;
-    readData: Mock<[number], Uint8Array>;
-    readPos: Mock<[], any>;
-    readDir: Mock<[], any>;
+type NetworkCondition = 'good' | 'slow' | 'unstable' | 'offline';
+interface NetworkConfig {
+    offline: boolean;
+    downloadThroughput: number;
+    uploadThroughput: number;
+    latency: number;
 }
-declare const createBinaryStreamMock: () => BinaryStreamMock;
-
-declare const createPlayerStateFactory: (overrides?: Partial<PlayerState>) => PlayerState;
-declare const createEntityStateFactory: (overrides?: Partial<EntityState>) => EntityState;
-declare const createGameStateSnapshotFactory: (overrides?: Partial<GameStateSnapshot>) => GameStateSnapshot;
+/**
+ * Simulates network conditions using Chrome DevTools Protocol (CDP) via Playwright.
+ */
+declare function simulateNetworkCondition(condition: NetworkCondition): NetworkSimulator;
+/**
+ * Creates a custom network condition simulator.
+ *
+ * @param latency Latency in milliseconds
+ * @param jitter Approximate jitter (variation in latency) - Note: CDP doesn't support jitter natively.
+ * @param packetLoss Packet loss percentage (0-100) - Ignored for basic CDP emulation.
+ */
+declare function createCustomNetworkCondition(latency: number, jitter?: number, packetLoss?: number, baseConfig?: NetworkConfig): NetworkSimulator;
+/**
+ * Throttles bandwidth for the given page.
+ */
+declare function throttleBandwidth(page: any, bytesPerSecond: number): Promise<void>;
 
-interface MockEngine {
-    sound: Mock<[Entity, number, string, number, number, number], void>;
-    soundIndex: Mock<[string], number>;
-    modelIndex: Mock<[string], number>;
-    centerprintf: Mock<[Entity, string], void>;
-}
-interface MockGame {
-    random: ReturnType<typeof createRandomGenerator>;
-    registerEntitySpawn: Mock<[string, (entity: Entity) => void], void>;
-    unregisterEntitySpawn: Mock<[string], void>;
-    getCustomEntities: Mock<[], string[]>;
-    hooks: ScriptHookRegistry;
-    registerHooks: Mock<[any], any>;
-    spawnWorld: Mock<[], void>;
-    clientBegin: Mock<[any], void>;
-    damage: Mock<[number], void>;
+interface VisualDiff {
+    pixelDiff: number;
+    diffPath?: string;
+    matched: boolean;
 }
-interface TestContext extends SpawnContext {
-    entities: EntitySystem;
-    game: MockGame;
-    engine: MockEngine;
+/**
+ * Captures a screenshot of the current game state.
+ */
+declare function captureGameScreenshot(page: Page, name: string, options?: {
+    dir?: string;
+    fullPage?: boolean;
+}): Promise<Buffer>;
+/**
+ * Compares two image buffers pixel-by-pixel.
+ * Note: A robust implementation would use a library like 'pixelmatch' or 'looks-same'.
+ * For now, we provide a basic placeholder or rely on simple buffer comparison.
+ */
+declare function compareScreenshots(baseline: Buffer, current: Buffer, threshold?: number): Promise<VisualDiff>;
+interface VisualScenario {
+    capture(name: string): Promise<Buffer>;
+    compare(name: string, baselineDir: string): Promise<VisualDiff>;
 }
-declare const createMockEngine: () => MockEngine;
-declare const createMockGame: (seed?: number) => {
-    game: MockGame;
-    spawnRegistry: SpawnRegistry;
-};
-declare function createTestContext(options?: {
-    seed?: number;
-    initialEntities?: Entity[];
-}): TestContext;
-declare function createSpawnContext(): SpawnContext;
-declare function createEntity(): Entity;
+/**
+ * Creates a helper for visual regression testing scenarios.
+ */
+declare function createVisualTestScenario(page: Page, sceneName: string): VisualScenario;
 
-export { type AudioEvent, type BinaryStreamMock, type BinaryWriterMock, type BrowserSetupOptions, type ControlledTimer, type DrawCall, type GameStateCapture, InputInjector, type MockEngine, type MockGame, MockPointerLock, type MockRAF, type PlaywrightOptions, type PlaywrightTestClient, type StorageScenario, type TestContext, captureAudioEvents, captureCanvasDrawCalls, captureGameState, createBinaryStreamMock, createBinaryWriterMock, createControlledTimer, createEntity, createEntityStateFactory, createGameStateSnapshotFactory, createMockAudioContext, createMockCanvas, createMockCanvasContext2D, createMockEngine, createMockGame, createMockImage, createMockImageData, createMockIndexedDB, createMockLocalStorage, createMockPerformance, createMockRAF, createMockSessionStorage, createMockWebGL2Context, createNetChanMock, createPlayerStateFactory, createPlaywrightTestClient, createSpawnContext, createStorageTestScenario, createTestContext, makeAxisBrush, makeBrushFromMinsMaxs, makeBspModel, makeLeaf, makeLeafModel, makeNode, makePlane, setupBrowserEnvironment, setupMockAudioContext, setupNodeEnvironment, simulateFrames, simulateFramesWithMock, teardownBrowserEnvironment, teardownMockAudioContext, waitForGameReady };
+export { type AudioEvent, type BinaryStreamMock, type BinaryWriterMock, type BrowserSetupOptions, type ControlledTimer, type DrawCall, type GameState, type GameStateCapture, InputInjector, type MockEngine, type MockGame, MockPointerLock, type MockRAF, type MockServer, MockTransport, type MockUDPSocket, type NetworkAddress, type NetworkCondition, type NetworkConfig, type NetworkSimulator, type NodeSetupOptions, type PlaywrightOptions, type PlaywrightTestClient, type StorageScenario, type TestContext, type VisualDiff, type VisualScenario, captureAudioEvents, captureCanvasDrawCalls, captureGameScreenshot, captureGameState, compareScreenshots, createBinaryStreamMock, createBinaryWriterMock, createControlledTimer, createCustomNetworkCondition, createEntity, createEntityStateFactory, createGameStateSnapshotFactory, createMockAudioContext, createMockCanvas, createMockCanvasContext2D, createMockEngine, createMockGame, createMockGameState, createMockImage, createMockImageData, createMockIndexedDB, createMockLocalStorage, createMockNetworkAddress, createMockPerformance, createMockRAF, createMockServer, createMockServerClient, createMockServerState, createMockServerStatic, createMockSessionStorage, createMockTransport, createMockUDPSocket, createMockWebGL2Context, createNetChanMock, createPlayerStateFactory, createPlaywrightTestClient, createSpawnContext, createStorageTestScenario, createTestContext, createVisualTestScenario, makeAxisBrush, makeBrushFromMinsMaxs, makeBspModel, makeLeaf, makeLeafModel, makeNode, makePlane, setupBrowserEnvironment, setupMockAudioContext, setupNodeEnvironment, simulateFrames, simulateFramesWithMock, simulateNetworkCondition, teardownBrowserEnvironment, teardownMockAudioContext, throttleBandwidth, waitForGameReady };