quake2ts 0.0.553 → 0.0.557

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

@@ -2,6 +2,8 @@ import { Mock } from 'vitest';
 import { Vec3, CollisionPlane, CollisionBrush, CollisionNode, CollisionLeaf, CollisionModel, PlayerState, EntityState, createRandomGenerator } from '@quake2ts/shared';
 export { intersects, ladderTrace, stairTrace } from '@quake2ts/shared';
 import { GameStateSnapshot, Entity, ScriptHookRegistry, SpawnContext, EntitySystem, SpawnRegistry } from '@quake2ts/game';
+import { ImageData } from '@napi-rs/canvas';
+import { Browser, BrowserContext, Page } from 'playwright';
 
 interface BinaryWriterMock {
     writeByte: Mock<[number], void>;
@@ -130,6 +132,9 @@ declare function createEntity(): Entity;
 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.
@@ -149,6 +154,111 @@ declare function setupNodeEnvironment(): void;
 
 declare function createMockWebGL2Context(canvas: HTMLCanvasElement): WebGL2RenderingContext;
 
+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;
+
+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.
+ */
+declare function simulateFramesWithMock(mock: MockRAF, count: number, frameTimeMs?: number, callback?: (frameIndex: number) => void): void;
+
+/**
+ * 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[];
+
 declare class MockPointerLock {
     static setup(doc: Document): void;
 }
@@ -164,4 +274,113 @@ declare class InputInjector {
     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 };
+interface PlaywrightOptions {
+    headless?: boolean;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    args?: string[];
+    recordVideo?: {
+        dir: string;
+        size?: {
+            width: number;
+            height: number;
+        };
+    };
+}
+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;
+}
+/**
+ * Creates a Playwright test client wrapper.
+ */
+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;
+}
+/**
+ * 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>;
+
+interface VisualDiff {
+    pixelDiff: number;
+    diffPath?: string;
+    matched: boolean;
+}
+/**
+ * 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>;
+}
+/**
+ * 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 };