quake2ts 0.0.557 → 0.0.562

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

@@ -1,9 +1,12 @@
+import * as vitest from 'vitest';
 import { Mock } from 'vitest';
-import { Vec3, CollisionPlane, CollisionBrush, CollisionNode, CollisionLeaf, CollisionModel, PlayerState, EntityState, createRandomGenerator } from '@quake2ts/shared';
+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 { Browser, BrowserContext, Page } from 'playwright';
+import { LaunchOptions, BrowserContextOptions, Browser, BrowserContext, Page } from 'playwright';
+import { Server as Server$1 } from 'http';
 
 interface BinaryWriterMock {
     writeByte: Mock<[number], void>;
@@ -129,6 +132,141 @@ declare function createTestContext(options?: {
 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;
     pretendToBeVisual?: boolean;
@@ -146,14 +284,6 @@ declare function setupBrowserEnvironment(options?: BrowserSetupOptions): void;
  */
 declare function teardownBrowserEnvironment(): void;
 
-/**
- * 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 createMockWebGL2Context(canvas: HTMLCanvasElement): WebGL2RenderingContext;
-
 interface DrawCall {
     method: string;
     args: any[];
@@ -180,39 +310,13 @@ declare function createMockImageData(width: number, height: number, fillColor?:
  */
 declare function createMockImage(width?: number, height?: number, src?: string): HTMLImageElement;
 
-interface MockRAF {
-    tick(timestamp?: number): void;
-    advance(deltaMs?: number): void;
-    getCallbacks(): FrameRequestCallback[];
-    reset(): void;
-    enable(): void;
-    disable(): void;
-}
 /**
- * Creates a mock implementation of requestAnimationFrame that allows manual control.
- * It replaces the global requestAnimationFrame and cancelAnimationFrame.
- */
-declare function createMockRAF(): MockRAF;
-/**
- * Creates a mock Performance object with controllable time.
- */
-declare function createMockPerformance(startTime?: number): Performance;
-interface ControlledTimer {
-    tick(): void;
-    advanceBy(ms: number): void;
-    clear(): void;
-}
-/**
- * Helper to simulate multiple frames of a game loop.
- * @param count Number of frames to simulate
- * @param frameTimeMs Time per frame in milliseconds
- * @param callback Optional callback to run inside the loop (e.g. triggering inputs)
- */
-declare function simulateFrames(count: number, frameTimeMs?: number, callback?: (frameIndex: number) => void): void;
-/**
- * Simulates frames using a provided MockRAF controller.
+ * 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 simulateFramesWithMock(mock: MockRAF, count: number, frameTimeMs?: number, callback?: (frameIndex: number) => void): void;
+declare function setupNodeEnvironment(): void;
+
+declare function createMockWebGL2Context(canvas: HTMLCanvasElement): WebGL2RenderingContext;
 
 /**
  * Creates a mock Storage implementation (localStorage/sessionStorage).
@@ -259,128 +363,93 @@ interface AudioEvent {
  */
 declare function captureAudioEvents(context: AudioContext): AudioEvent[];
 
-declare class MockPointerLock {
-    static setup(doc: Document): void;
+interface MockRAF {
+    tick(timestamp?: number): void;
+    advance(deltaMs?: number): void;
+    getCallbacks(): FrameRequestCallback[];
+    reset(): void;
+    enable(): void;
+    disable(): void;
 }
-declare class InputInjector {
-    private doc;
-    private win;
-    constructor(doc: Document, win: any);
-    keyDown(key: string, code?: string): void;
-    keyUp(key: string, code?: string): void;
-    mouseMove(movementX: number, movementY: number, clientX?: number, clientY?: number): void;
-    mouseDown(button?: number): void;
-    mouseUp(button?: number): void;
-    wheel(deltaY: number): void;
+/**
+ * Creates a mock implementation of requestAnimationFrame that allows manual control.
+ * It replaces the global requestAnimationFrame and cancelAnimationFrame.
+ */
+declare function createMockRAF(): MockRAF;
+/**
+ * Creates a mock Performance object with controllable time.
+ */
+declare function createMockPerformance(startTime?: number): Performance;
+interface ControlledTimer {
+    tick(): void;
+    advanceBy(ms: number): void;
+    clear(): void;
+    restore(): void;
 }
+/**
+ * Creates a controlled timer that replaces global setTimeout/setInterval.
+ * Allows deterministic time advancement.
+ */
+declare function createControlledTimer(): ControlledTimer;
+/**
+ * Helper to simulate multiple frames of a game loop.
+ * @param count Number of frames to simulate
+ * @param frameTimeMs Time per frame in milliseconds
+ * @param callback Optional callback to run inside the loop (e.g. triggering inputs)
+ */
+declare function simulateFrames(count: number, frameTimeMs?: number, callback?: (frameIndex: number) => void): void;
+/**
+ * Simulates frames using a provided MockRAF controller.
+ */
+declare function simulateFramesWithMock(mock: MockRAF, count: number, frameTimeMs?: number, callback?: (frameIndex: number) => void): void;
 
+/**
+ * Interface for Test Client options
+ */
 interface PlaywrightOptions {
     headless?: boolean;
-    viewport?: {
-        width: number;
-        height: number;
-    };
-    args?: string[];
-    recordVideo?: {
-        dir: string;
-        size?: {
-            width: number;
-            height: number;
-        };
-    };
+    width?: number;
+    height?: number;
+    clientUrl?: string;
+    serverUrl?: string;
+    rootPath?: string;
+    launchOptions?: LaunchOptions;
+    contextOptions?: BrowserContextOptions;
 }
 interface PlaywrightTestClient {
     browser: Browser;
     context: BrowserContext;
     page: Page;
-    navigate(url: string): Promise<void>;
-    waitForGame(timeout?: number): Promise<void>;
-    injectInput(type: 'keydown' | 'keyup', key: string): Promise<void>;
-    injectMouse(type: 'move' | 'down' | 'up', x?: number, y?: number, button?: number): Promise<void>;
-    screenshot(path: string): Promise<void>;
-    close(): Promise<void>;
-}
-interface GameStateCapture {
-    origin?: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    angles?: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    health?: number;
+    server?: Server$1;
+    close: () => Promise<void>;
+    navigate: (url?: string) => Promise<void>;
+    waitForGame: (timeout?: number) => Promise<void>;
+    injectInput: (type: string, data: any) => Promise<void>;
 }
 /**
- * Creates a Playwright test client wrapper.
+ * Creates a Playwright-controlled browser environment for testing.
+ * Can start a static server to serve the game client if no clientUrl is provided.
  */
 declare function createPlaywrightTestClient(options?: PlaywrightOptions): Promise<PlaywrightTestClient>;
-/**
- * Waits for the game to be ready on the provided page.
- */
 declare function waitForGameReady(page: Page, timeout?: number): Promise<void>;
-/**
- * Captures the current game state from the browser.
- * Requires the game to expose state globally (e.g. window.game.state).
- */
-declare function captureGameState(page: Page): Promise<GameStateCapture>;
-
-interface NetworkSimulator {
-    apply(page: any): Promise<void>;
-    clear(page: any): Promise<void>;
-}
-type NetworkCondition = 'good' | 'slow' | 'unstable' | 'offline';
-interface NetworkConfig {
-    offline: boolean;
-    downloadThroughput: number;
-    uploadThroughput: number;
-    latency: number;
+interface GameStateCapture {
+    [key: string]: any;
 }
-/**
- * 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, so this is just a placeholder or requires manual delay injection.
- * @param packetLoss Packet loss percentage (0-100) - CDP doesn't strictly support packet loss, typically emulated via "offline" toggling or proxy. We will ignore 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>;
+declare function captureGameState(page: Page): Promise<GameStateCapture>;
 
-interface VisualDiff {
-    pixelDiff: number;
-    diffPath?: string;
-    matched: boolean;
+declare class MockPointerLock {
+    static setup(doc: Document): void;
 }
-/**
- * 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 if strict equality is needed,
- * but visual regression usually requires tolerance.
- */
-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 class InputInjector {
+    private doc;
+    private win;
+    constructor(doc: Document, win: any);
+    keyDown(key: string, code?: string): void;
+    keyUp(key: string, code?: string): void;
+    mouseMove(movementX: number, movementY: number, clientX?: number, clientY?: number): void;
+    mouseDown(button?: number): void;
+    mouseUp(button?: number): void;
+    wheel(deltaY: number): void;
 }
-/**
- * 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 NetworkCondition, type NetworkConfig, type NetworkSimulator, type PlaywrightOptions, type PlaywrightTestClient, type StorageScenario, type TestContext, type VisualDiff, type VisualScenario, captureAudioEvents, captureCanvasDrawCalls, captureGameScreenshot, captureGameState, compareScreenshots, createBinaryStreamMock, createBinaryWriterMock, createCustomNetworkCondition, createEntity, createEntityStateFactory, createGameStateSnapshotFactory, createMockAudioContext, createMockCanvas, createMockCanvasContext2D, createMockEngine, createMockGame, createMockImage, createMockImageData, createMockIndexedDB, createMockLocalStorage, createMockPerformance, createMockRAF, createMockSessionStorage, 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 };
+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 PlaywrightOptions, type PlaywrightTestClient, type StorageScenario, type TestContext, captureAudioEvents, captureCanvasDrawCalls, captureGameState, createBinaryStreamMock, createBinaryWriterMock, createControlledTimer, 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, makeAxisBrush, makeBrushFromMinsMaxs, makeBspModel, makeLeaf, makeLeafModel, makeNode, makePlane, setupBrowserEnvironment, setupMockAudioContext, setupNodeEnvironment, simulateFrames, simulateFramesWithMock, teardownBrowserEnvironment, teardownMockAudioContext, waitForGameReady };