quake2ts 0.0.556 → 0.0.561

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

@@ -1,8 +1,204 @@
-import { Mock } from 'vitest';
+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 { Mock } from 'vitest';
 import { GameStateSnapshot, Entity, ScriptHookRegistry, SpawnContext, EntitySystem, SpawnRegistry } from '@quake2ts/game';
 
+interface BrowserSetupOptions {
+    url?: string;
+    pretendToBeVisual?: boolean;
+    resources?: "usable";
+    enableWebGL2?: boolean;
+    enablePointerLock?: boolean;
+}
+/**
+ * Sets up a browser environment for testing using JSDOM and napi-rs/canvas.
+ * This should be called in your vitest.setup.ts file.
+ */
+declare function setupBrowserEnvironment(options?: BrowserSetupOptions): void;
+/**
+ * Cleans up the browser environment.
+ */
+declare function teardownBrowserEnvironment(): void;
+
+interface DrawCall {
+    method: string;
+    args: any[];
+}
+/**
+ * Creates a mock canvas element with WebGL2 support.
+ */
+declare function createMockCanvas(width?: number, height?: number): HTMLCanvasElement;
+/**
+ * Creates a mock 2D rendering context.
+ */
+declare function createMockCanvasContext2D(canvas?: HTMLCanvasElement): CanvasRenderingContext2D;
+/**
+ * Spies on draw operations for verification.
+ * Note: This modifies the context prototype or instance methods.
+ */
+declare function captureCanvasDrawCalls(context: CanvasRenderingContext2D): DrawCall[];
+/**
+ * Creates a mock ImageData object.
+ */
+declare function createMockImageData(width: number, height: number, fillColor?: [number, number, number, number]): ImageData;
+/**
+ * Creates a mock Image element.
+ */
+declare function createMockImage(width?: number, height?: number, src?: string): HTMLImageElement;
+
+/**
+ * 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;
+
+/**
+ * Creates a mock Storage implementation (localStorage/sessionStorage).
+ */
+declare function createMockLocalStorage(initialData?: Record<string, string>): Storage;
+/**
+ * Creates a mock SessionStorage implementation.
+ * Functionally identical to LocalStorage mock but distinct for testing isolation.
+ */
+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.
+ */
+declare function createMockIndexedDB(): IDBFactory;
+interface StorageScenario {
+    storage: Storage;
+    populate(data: Record<string, string>): void;
+    verify(key: string, value: string): boolean;
+}
+/**
+ * Helper to setup a storage test scenario.
+ */
+declare function createStorageTestScenario(storageType?: 'local' | 'session'): StorageScenario;
+
+declare function createMockAudioContext(): AudioContext;
+/**
+ * Replaces the global AudioContext with a mock.
+ */
+declare function setupMockAudioContext(): void;
+/**
+ * Restores the original AudioContext (if it was mocked).
+ */
+declare function teardownMockAudioContext(): void;
+interface AudioEvent {
+    type: string;
+    args: any[];
+}
+/**
+ * Captures audio operations for verification.
+ * Currently requires manual instrumentation or a more sophisticated Proxy mock.
+ * This is a placeholder for future implementation.
+ */
+declare function captureAudioEvents(context: AudioContext): AudioEvent[];
+
+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;
+    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;
+    width?: number;
+    height?: number;
+    clientUrl?: string;
+    serverUrl?: string;
+    rootPath?: string;
+    launchOptions?: LaunchOptions;
+    contextOptions?: BrowserContextOptions;
+}
+interface PlaywrightTestClient {
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+    server?: Server;
+    close: () => Promise<void>;
+    navigate: (url?: string) => Promise<void>;
+    waitForGame: (timeout?: number) => Promise<void>;
+    injectInput: (type: string, data: any) => 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.
+ */
+declare function createPlaywrightTestClient(options?: PlaywrightOptions): Promise<PlaywrightTestClient>;
+declare function waitForGameReady(page: Page, timeout?: number): Promise<void>;
+interface GameStateCapture {
+    [key: string]: any;
+}
+declare function captureGameState(page: Page): Promise<GameStateCapture>;
+
+declare class MockPointerLock {
+    static setup(doc: Document): 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;
+}
+
+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>;
@@ -81,14 +277,6 @@ interface BinaryStreamMock {
 }
 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;
@@ -127,41 +315,4 @@ declare function createTestContext(options?: {
 declare function createSpawnContext(): SpawnContext;
 declare function createEntity(): Entity;
 
-interface BrowserSetupOptions {
-    url?: string;
-    pretendToBeVisual?: boolean;
-}
-/**
- * Sets up a browser environment for testing using JSDOM and napi-rs/canvas.
- * This should be called in your vitest.setup.ts file.
- */
-declare function setupBrowserEnvironment(options?: BrowserSetupOptions): void;
-/**
- * Cleans up the browser environment.
- */
-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;
-
-declare class MockPointerLock {
-    static setup(doc: Document): 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;
-}
-
-export { type BinaryStreamMock, type BinaryWriterMock, type BrowserSetupOptions, InputInjector, type MockEngine, type MockGame, MockPointerLock, type TestContext, createBinaryStreamMock, createBinaryWriterMock, createEntity, createEntityStateFactory, createGameStateSnapshotFactory, createMockEngine, createMockGame, createMockWebGL2Context, createNetChanMock, createPlayerStateFactory, createSpawnContext, createTestContext, makeAxisBrush, makeBrushFromMinsMaxs, makeBspModel, makeLeaf, makeLeafModel, makeNode, makePlane, setupBrowserEnvironment, setupNodeEnvironment, teardownBrowserEnvironment };
+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 };