quake2ts 0.0.581 → 0.0.584

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

@@ -1,5 +1,5 @@
 import * as vitest from 'vitest';
-import { Mock } from 'vitest';
+import { Mock, vi } from 'vitest';
 import { Vec3, CollisionPlane, CollisionBrush, CollisionNode, CollisionLeaf, CollisionModel, PlayerState, EntityState, createRandomGenerator, NetDriver, TraceResult, UserCommand } from '@quake2ts/shared';
 export { intersects, ladderTrace, stairTrace } from '@quake2ts/shared';
 import { GameStateSnapshot, Entity, ScriptHookRegistry, SpawnContext, EntitySystem, SpawnRegistry, MonsterMove, DamageMod, PlayerInventory, BaseItem, WeaponId, WeaponItem, HealthItem, ArmorItem, AmmoItemId, PowerupItem, GameExports } from '@quake2ts/game';
@@ -7,8 +7,6 @@ import { NetworkTransport, Server, ServerStatic, Client, ClientState, ClientFram
 import { ImageData } from '@napi-rs/canvas';
 import { vec3 } from 'gl-matrix';
 import { Camera } from '@quake2ts/engine';
-import { LaunchOptions, BrowserContextOptions, Browser, BrowserContext, Page } from 'playwright';
-import { Server as Server$1 } from 'http';
 
 interface BinaryWriterMock {
     writeByte: Mock<[number], void>;
@@ -678,21 +676,24 @@ declare function setupBrowserEnvironment(options?: BrowserSetupOptions): void;
  */
 declare function teardownBrowserEnvironment(): void;
 
-interface DrawCall {
-    method: string;
-    args: any[];
-}
 /**
- * Creates a mock canvas element with WebGL2 support.
+ * Creates a mock HTMLCanvasElement backed by napi-rs/canvas,
+ * with support for both 2D and WebGL2 contexts.
  */
 declare function createMockCanvas(width?: number, height?: number): HTMLCanvasElement;
 /**
- * Creates a mock 2D rendering context.
+ * Creates a mock CanvasRenderingContext2D.
  */
 declare function createMockCanvasContext2D(canvas?: HTMLCanvasElement): CanvasRenderingContext2D;
 /**
- * Spies on draw operations for verification.
- * Note: This modifies the context prototype or instance methods.
+ * Information about a captured draw call.
+ */
+interface DrawCall {
+    method: string;
+    args: any[];
+}
+/**
+ * Wraps a CanvasRenderingContext2D to capture all method calls.
  */
 declare function captureCanvasDrawCalls(context: CanvasRenderingContext2D): DrawCall[];
 /**
@@ -700,7 +701,7 @@ declare function captureCanvasDrawCalls(context: CanvasRenderingContext2D): Draw
  */
 declare function createMockImageData(width: number, height: number, fillColor?: [number, number, number, number]): ImageData;
 /**
- * Creates a mock Image element.
+ * Creates a mock HTMLImageElement.
  */
 declare function createMockImage(width?: number, height?: number, src?: string): HTMLImageElement;
 
@@ -709,54 +710,76 @@ declare function createMockGPUDevice(): Partial<GPUDevice>;
 declare function createMockGPUCanvasContext(): Partial<GPUCanvasContext>;
 declare function setupWebGPUMocks(): void;
 
+/**
+ * Interface for the mock RequestAnimationFrame implementation.
+ */
 interface MockRAF {
-    tick(timestamp?: number): void;
-    advance(deltaMs?: number): void;
-    getCallbacks(): FrameRequestCallback[];
-    reset(): void;
-    enable(): void;
-    disable(): void;
+    /**
+     * Advances time by one tick (simulating one frame).
+     * @param time Timestamp to pass to callbacks (default: calls Date.now())
+     */
+    tick(time?: number): void;
+    /**
+     * Advances time by a specific amount, triggering multiple frames if necessary.
+     * Not fully implemented in simple version, acts as alias to tick() with specific time.
+     */
+    advance(ms: number): void;
+    /**
+     * Returns current pending callbacks.
+     */
+    getCallbacks(): Array<{
+        id: number;
+        callback: FrameRequestCallback;
+    }>;
 }
 /**
- * Creates a mock implementation of requestAnimationFrame that allows manual control.
- * It replaces the global requestAnimationFrame and cancelAnimationFrame.
+ * Creates a mock RequestAnimationFrame implementation.
+ * Replaces global.requestAnimationFrame and cancelAnimationFrame.
  */
 declare function createMockRAF(): MockRAF;
 /**
- * Creates a mock Performance object with controllable time.
+ * Creates a mock Performance object.
  */
 declare function createMockPerformance(startTime?: number): Performance;
 interface ControlledTimer {
-    tick(): void;
+    /**
+     * Advances virtual time by ms.
+     */
     advanceBy(ms: number): void;
+    /**
+     * Runs all pending timers.
+     */
+    runAll(): void;
+    /**
+     * Restores original timer functions.
+     */
     clear(): void;
-    restore(): void;
 }
 /**
- * Creates a controlled timer that replaces global setTimeout/setInterval.
- * Allows deterministic time advancement.
+ * Creates controlled timers (setTimeout/setInterval).
+ * Note: Use verify's useFakeTimers() for better integration with test runner.
+ * This is a lightweight alternative or specific helper.
  */
 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)
+ * Simulates multiple RAF frames.
  */
-declare function simulateFrames(count: number, frameTimeMs?: number, callback?: (frameIndex: number) => void): void;
+declare function simulateFrames(count: number, frameTime?: number, callback?: (frameIndex: number) => void): void;
+
 /**
- * Simulates frames using a provided MockRAF controller.
+ * Setup helpers for Node.js environments.
  */
-declare function simulateFramesWithMock(mock: MockRAF, count: number, frameTimeMs?: number, callback?: (frameIndex: number) => void): void;
-
 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.
+ * Currently a placeholder for future Node-specific setup.
  */
 declare function setupNodeEnvironment(options?: NodeSetupOptions): void;
+/**
+ * Teardown for Node.js environment.
+ */
+declare function teardownNodeEnvironment(): void;
 
 interface ShaderRecord {
     readonly id: number;
@@ -904,47 +927,82 @@ declare class MockWebGL2RenderingContext {
 }
 declare function createMockWebGL2Context(overridesOrCanvas?: Partial<WebGL2RenderingContext> | HTMLCanvasElement): MockWebGL2RenderingContext;
 
+interface MockPipeline {
+    render: ReturnType<typeof vi.fn>;
+    init: ReturnType<typeof vi.fn>;
+    resize: ReturnType<typeof vi.fn>;
+}
+interface MockCamera {
+    update: ReturnType<typeof vi.fn>;
+    getViewMatrix: ReturnType<typeof vi.fn>;
+    getProjectionMatrix: ReturnType<typeof vi.fn>;
+    getViewProjectionMatrix: ReturnType<typeof vi.fn>;
+    getPosition: ReturnType<typeof vi.fn>;
+    getForward: ReturnType<typeof vi.fn>;
+    getRight: ReturnType<typeof vi.fn>;
+    getUp: ReturnType<typeof vi.fn>;
+    extractFrustumPlanes: ReturnType<typeof vi.fn>;
+    transform: {
+        origin: number[];
+        angles: number[];
+        fov: number;
+    };
+}
+interface MockRenderingContext {
+    gl: MockWebGL2RenderingContext;
+    camera: MockCamera;
+    pipelines: {
+        md2: MockPipeline;
+        bsp: MockPipeline;
+        sprite: MockPipeline;
+        poly: MockPipeline;
+        particle: MockPipeline;
+    };
+}
+declare function createMockRenderingContext(): MockRenderingContext;
+
 /**
- * Creates a mock Storage implementation (localStorage/sessionStorage).
+ * Creates a mock LocalStorage instance.
  */
 declare function createMockLocalStorage(initialData?: Record<string, string>): Storage;
 /**
- * Creates a mock SessionStorage implementation.
- * Functionally identical to LocalStorage mock but distinct for testing isolation.
+ * Creates a mock SessionStorage instance.
  */
 declare function createMockSessionStorage(initialData?: Record<string, string>): Storage;
 /**
  * Creates a mock IndexedDB factory.
- * Currently relies on 'fake-indexeddb/auto' being imported which mocks the global indexedDB.
- * This helper ensures the global is available or resets it.
+ * Wraps fake-indexeddb.
  */
-declare function createMockIndexedDB(): IDBFactory;
+declare function createMockIndexedDB(databases?: IDBDatabase[]): IDBFactory;
 interface StorageScenario {
-    storage: Storage | IDBFactory;
-    populate(data: Record<string, any>): Promise<void> | void;
-    verify(key: string, value: any): Promise<boolean> | boolean;
+    localStorage: Storage;
+    sessionStorage: Storage;
+    indexedDB: IDBFactory;
 }
 /**
- * Helper to setup a storage test scenario.
+ * Creates a complete storage test scenario.
  */
 declare function createStorageTestScenario(storageType?: 'local' | 'session' | 'indexed'): StorageScenario;
 
-declare function createMockAudioContext(): AudioContext;
 /**
- * Replaces the global AudioContext with a mock.
+ * Mocks for Web Audio API.
+ */
+/**
+ * Sets up a mock AudioContext globally.
  */
 declare function setupMockAudioContext(): void;
 /**
- * Restores the original AudioContext (if it was mocked).
+ * Restores original AudioContext.
  */
 declare function teardownMockAudioContext(): void;
 interface AudioEvent {
     type: string;
-    args: any[];
+    data?: any;
 }
 /**
- * Captures audio operations for verification.
- * Note: Only works if the context was created via createMockAudioContext which proxies calls.
+ * Captures audio events from a context.
+ * Requires the context to be instrumented or mocked to emit events.
+ * This helper currently works with the `setupMockAudioContext` mock if extended.
  */
 declare function captureAudioEvents(context: AudioContext): AudioEvent[];
 
@@ -1068,93 +1126,80 @@ declare function createViewTestScenario(scenarioType: 'firstPerson' | 'thirdPers
  */
 declare function simulateCameraMovement(camera: Camera, input: CameraInput, deltaTime: number): Camera;
 
-/**
- * Interface for Test Client options
- */
 interface PlaywrightOptions {
     headless?: boolean;
-    width?: number;
-    height?: number;
-    clientUrl?: string;
-    serverUrl?: string;
-    rootPath?: string;
-    launchOptions?: LaunchOptions;
-    contextOptions?: BrowserContextOptions;
+    viewport?: {
+        width: number;
+        height: number;
+    };
 }
 interface PlaywrightTestClient {
-    browser: Browser;
-    context: BrowserContext;
-    page: Page;
-    server?: Server$1;
-    close: () => Promise<void>;
-    navigate: (url?: string) => Promise<void>;
-    waitForGame: (timeout?: number) => Promise<void>;
-    injectInput: (type: string, data: any) => Promise<void>;
+    page: any;
+    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-controlled browser environment for testing.
- * Can start a static server to serve the game client if no clientUrl is provided.
+ * Creates a Playwright test client.
+ * Note: Requires playwright to be installed in the project.
  */
 declare function createPlaywrightTestClient(options?: PlaywrightOptions): Promise<PlaywrightTestClient>;
-declare function waitForGameReady(page: Page, timeout?: number): Promise<void>;
+/**
+ * Waits for the game to be ready.
+ */
+declare function waitForGameReady(page: any, timeout?: number): Promise<void>;
 interface GameStateCapture {
-    [key: string]: any;
+    time: number;
+    entities: number;
 }
-declare function captureGameState(page: Page): Promise<GameStateCapture>;
+/**
+ * Captures current game state from the browser.
+ */
+declare function captureGameState(page: any): Promise<GameStateCapture>;
 
+type NetworkCondition = 'good' | 'slow' | 'unstable' | 'offline' | 'custom';
 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;
+    jitter: number;
+    packetLoss: number;
+    bandwidth: number;
 }
 /**
- * Simulates network conditions using Chrome DevTools Protocol (CDP) via Playwright.
+ * Simulates network conditions.
  */
 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.
+ * Creates a custom network condition.
  */
-declare function createCustomNetworkCondition(latency: number, jitter?: number, packetLoss?: number, baseConfig?: NetworkConfig): NetworkSimulator;
+declare function createCustomNetworkCondition(latency: number, jitter: number, packetLoss: number): NetworkSimulator;
 /**
- * Throttles bandwidth for the given page.
+ * Helper to throttle bandwidth (e.g. for Playwright).
  */
-declare function throttleBandwidth(page: any, bytesPerSecond: number): Promise<void>;
+declare function throttleBandwidth(bytesPerSecond: number): void;
 
 interface VisualDiff {
-    pixelDiff: number;
-    diffPath?: string;
-    matched: boolean;
+    diffPercentage: number;
+    diffImage?: Buffer;
 }
 /**
- * Captures a screenshot of the current game state.
+ * Captures a screenshot of the game.
  */
-declare function captureGameScreenshot(page: Page, name: string, options?: {
-    dir?: string;
-    fullPage?: boolean;
-}): Promise<Buffer>;
+declare function captureGameScreenshot(page: any, name: string): 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.
+ * Compares two screenshots (Buffers).
+ * Uses a pixel comparison library if available, or simple buffer check.
  */
-declare function compareScreenshots(baseline: Buffer, current: Buffer, threshold?: number): Promise<VisualDiff>;
+declare function compareScreenshots(baseline: Buffer, current: Buffer, threshold?: number): VisualDiff;
 interface VisualScenario {
-    capture(name: string): Promise<Buffer>;
-    compare(name: string, baselineDir: string): Promise<VisualDiff>;
+    sceneName: string;
+    setup: () => Promise<void>;
 }
 /**
- * Creates a helper for visual regression testing scenarios.
+ * Creates a visual test scenario.
  */
-declare function createVisualTestScenario(page: Page, sceneName: string): VisualScenario;
+declare function createVisualTestScenario(sceneName: string): VisualScenario;
 
-export { type AudioEvent, type BandwidthScenario, type BinaryStreamMock, type BinaryWriterMock, type BrowserSetupOptions, type CameraInput, type Connection, type ConsistencyReport, type ControlledTimer, type DeltaSnapshot, type DrawCall, type GameState, type GameStateCapture, type Handshake, HandshakeStage, InputInjector, type KeyModifiers, type MasterServer, type Message, type MockAI, type MockCollisionEntityIndex, type MockDamageInfo, type MockEngine, type MockGame, type MockMonsterAI, MockPointerLock, type MockRAF, type MockRConClient, type MockServer, type MockServerConsole, type MockServerContext, MockTransport, type MockUDPSocket, MockWebGL2RenderingContext, type MultiplayerScenario, type NetworkAddress, type NetworkCondition, type NetworkConfig, type NetworkSimulator, type NodeSetupOptions, type PlaywrightOptions, type PlaywrightTestClient, type RateLimiter, type RefDef, type ServerInfo, type ServerListFilter, type Snapshot, type StorageScenario, type TestContext, type UserInfo, type ViewScenario, type ViewState, type VisualDiff, type VisualScenario, captureAudioEvents, captureCanvasDrawCalls, captureGameScreenshot, captureGameState, compareScreenshots, createBandwidthTestScenario, createBinaryStreamMock, createBinaryWriterMock, createCombatTestContext, createControlledTimer, createCustomNetworkCondition, createDeltaSnapshot, createEntity, createEntityFactory, createEntityStateFactory, createGameStateSnapshotFactory, createInputInjector, createItemEntityFactory, createMockAI, createMockAmmoItem, createMockArmorItem, createMockAudioContext, createMockCamera, createMockCanvas, createMockCanvasContext2D, createMockCollisionEntityIndex, createMockConnection, createMockDamageInfo, createMockEngine, createMockGPUAdapter, createMockGPUCanvasContext, createMockGPUDevice, createMockGame, createMockGameExports, createMockGameState, createMockHandshake, createMockHealthItem, createMockImage, createMockImageData, createMockIndexedDB, createMockInventory, createMockItem, createMockKeyboardEvent, createMockLocalStorage, createMockMasterServer, createMockMonsterAI, createMockMonsterMove, createMockMouseEvent, createMockNetDriver, createMockNetworkAddress, createMockPerformance, createMockPointerLock, createMockPowerupItem, createMockRAF, createMockRConClient, createMockRateLimiter, createMockRefDef, createMockServer, createMockServerClient, createMockServerConsole, createMockServerInfo, createMockServerState, createMockServerStatic, createMockSessionStorage, createMockTransport, createMockUDPSocket, createMockUserInfo, createMockViewState, createMockWeapon, createMockWeaponItem, createMockWebGL2Context, createMockWheelEvent, createMonsterEntityFactory, createMultiplayerTestScenario, createNetChanMock, createPhysicsTestContext, createPlayerEntityFactory, createPlayerStateFactory, createPlaywrightTestClient, createProjectileEntityFactory, createServerSnapshot, createSpawnTestContext, createStorageTestScenario, createTestContext, createTriggerEntityFactory, createViewTestScenario, createVisualTestScenario, makeAxisBrush, makeBrushFromMinsMaxs, makeBspModel, makeLeaf, makeLeafModel, makeNode, makePlane, measureSnapshotSize, mockMonsterAttacks, serializeUserInfo, setupBrowserEnvironment, setupMockAudioContext, setupNodeEnvironment, setupWebGPUMocks, simulateBandwidthLimit, simulateCameraMovement, simulateFrames, simulateFramesWithMock, simulateHandshake, simulateNetworkCondition, simulatePlayerInput, simulatePlayerJoin, simulatePlayerLeave, simulateServerCommand, simulateServerRegistration, simulateServerTick, simulateSnapshotDelivery, teardownBrowserEnvironment, teardownMockAudioContext, throttleBandwidth, verifySnapshotConsistency, waitForGameReady };
+export { type AudioEvent, type BandwidthScenario, type BinaryStreamMock, type BinaryWriterMock, type BrowserSetupOptions, type CameraInput, type Connection, type ConsistencyReport, type ControlledTimer, type DeltaSnapshot, type DrawCall, type GameState, type GameStateCapture, type Handshake, HandshakeStage, InputInjector, type KeyModifiers, type MasterServer, type Message, type MockAI, type MockCollisionEntityIndex, type MockDamageInfo, type MockEngine, type MockGame, type MockMonsterAI, MockPointerLock, type MockRAF, type MockRConClient, type MockRenderingContext, type MockServer, type MockServerConsole, type MockServerContext, MockTransport, type MockUDPSocket, MockWebGL2RenderingContext, type MultiplayerScenario, type NetworkAddress, type NetworkCondition, type NetworkSimulator, type NodeSetupOptions, type PlaywrightOptions, type PlaywrightTestClient, type RateLimiter, type RefDef, type ServerInfo, type ServerListFilter, type Snapshot, type StorageScenario, type TestContext, type UserInfo, type ViewScenario, type ViewState, type VisualDiff, type VisualScenario, captureAudioEvents, captureCanvasDrawCalls, captureGameScreenshot, captureGameState, compareScreenshots, createBandwidthTestScenario, createBinaryStreamMock, createBinaryWriterMock, createCombatTestContext, createControlledTimer, createCustomNetworkCondition, createDeltaSnapshot, createEntity, createEntityFactory, createEntityStateFactory, createGameStateSnapshotFactory, createInputInjector, createItemEntityFactory, createMockAI, createMockAmmoItem, createMockArmorItem, createMockCamera, createMockCanvas, createMockCanvasContext2D, createMockCollisionEntityIndex, createMockConnection, createMockDamageInfo, createMockEngine, createMockGPUAdapter, createMockGPUCanvasContext, createMockGPUDevice, createMockGame, createMockGameExports, createMockGameState, createMockHandshake, createMockHealthItem, createMockImage, createMockImageData, createMockIndexedDB, createMockInventory, createMockItem, createMockKeyboardEvent, createMockLocalStorage, createMockMasterServer, createMockMonsterAI, createMockMonsterMove, createMockMouseEvent, createMockNetDriver, createMockNetworkAddress, createMockPerformance, createMockPointerLock, createMockPowerupItem, createMockRAF, createMockRConClient, createMockRateLimiter, createMockRefDef, createMockRenderingContext, createMockServer, createMockServerClient, createMockServerConsole, createMockServerInfo, createMockServerState, createMockServerStatic, createMockSessionStorage, createMockTransport, createMockUDPSocket, createMockUserInfo, createMockViewState, createMockWeapon, createMockWeaponItem, createMockWebGL2Context, createMockWheelEvent, createMonsterEntityFactory, createMultiplayerTestScenario, createNetChanMock, createPhysicsTestContext, createPlayerEntityFactory, createPlayerStateFactory, createPlaywrightTestClient, createProjectileEntityFactory, createServerSnapshot, createSpawnTestContext, createStorageTestScenario, createTestContext, createTriggerEntityFactory, createViewTestScenario, createVisualTestScenario, makeAxisBrush, makeBrushFromMinsMaxs, makeBspModel, makeLeaf, makeLeafModel, makeNode, makePlane, measureSnapshotSize, mockMonsterAttacks, serializeUserInfo, setupBrowserEnvironment, setupMockAudioContext, setupNodeEnvironment, setupWebGPUMocks, simulateBandwidthLimit, simulateCameraMovement, simulateFrames, simulateHandshake, simulateNetworkCondition, simulatePlayerInput, simulatePlayerJoin, simulatePlayerLeave, simulateServerCommand, simulateServerRegistration, simulateServerTick, simulateSnapshotDelivery, teardownBrowserEnvironment, teardownMockAudioContext, teardownNodeEnvironment, throttleBandwidth, verifySnapshotConsistency, waitForGameReady };