@quake2ts/test-utils 0.0.1

package/src/e2e/visual.ts

@@ -0,0 +1,172 @@
+import { Canvas, Image } from '@napi-rs/canvas';
+import fs from 'fs/promises';
+import path from 'path';
+
+export interface VisualDiff {
+    diffPercentage: number;
+    diffImage?: Buffer;
+}
+
+/**
+ * Captures a screenshot of the game using Playwright.
+ * @param page Playwright Page object
+ * @param name Output filename (without extension)
+ */
+export async function captureGameScreenshot(page: any, name: string): Promise<Buffer> {
+    return await page.screenshot({ path: `${name}.png` });
+}
+
+/**
+ * Saves a canvas to a PNG file.
+ * Compatible with both JSDOM/HTMLCanvasElement and @napi-rs/canvas.
+ */
+export async function takeScreenshot(canvas: Canvas | HTMLCanvasElement, filepath: string): Promise<void> {
+    let buffer: Buffer;
+
+    // Handle @napi-rs/canvas Canvas object
+    if ('toBuffer' in canvas && typeof canvas.toBuffer === 'function') {
+        buffer = canvas.toBuffer('image/png');
+    }
+    // Handle JSDOM HTMLCanvasElement (if backed by node-canvas or similar)
+    else if ('toDataURL' in canvas) {
+        const dataUrl = canvas.toDataURL('image/png');
+        const base64 = dataUrl.replace(/^data:image\/png;base64,/, '');
+        buffer = Buffer.from(base64, 'base64');
+    } else {
+        throw new Error('Unsupported canvas type for screenshot');
+    }
+
+    await fs.mkdir(path.dirname(filepath), { recursive: true });
+    await fs.writeFile(filepath, buffer);
+}
+
+/**
+ * Compares a canvas state against a baseline image file.
+ * Returns true if they match (within optional threshold logic, currently strict pixel match).
+ * If baseline does not exist, it saves the current state as baseline and returns true.
+ */
+export async function compareScreenshot(canvas: Canvas | HTMLCanvasElement, baselinePath: string): Promise<boolean> {
+    try {
+        await fs.access(baselinePath);
+    } catch {
+        // Baseline doesn't exist, save current as baseline
+        console.warn(`Baseline not found at ${baselinePath}, saving current as baseline.`);
+        await takeScreenshot(canvas, baselinePath);
+        return true;
+    }
+
+    // Load baseline
+    const baselineBuffer = await fs.readFile(baselinePath);
+    const baselineImage = new Image();
+    baselineImage.src = baselineBuffer;
+
+    // Get dimensions (assume match for now, or fail)
+    const width = baselineImage.width;
+    const height = baselineImage.height;
+
+    // Get current image data
+    // We need to draw both to canvases to get pixel data easily with @napi-rs/canvas
+    // If input is already a canvas, we can use it.
+
+    // Helper to get buffer from input canvas
+    let currentBuffer: Buffer;
+    if ('toBuffer' in canvas && typeof canvas.toBuffer === 'function') {
+        currentBuffer = canvas.toBuffer('image/png');
+    } else if ('toDataURL' in canvas) {
+        const dataUrl = canvas.toDataURL('image/png');
+        currentBuffer = Buffer.from(dataUrl.replace(/^data:image\/png;base64,/, ''), 'base64');
+    } else {
+        throw new Error('Unsupported canvas type');
+    }
+
+    // Simple Buffer comparison first (fastest)
+    if (baselineBuffer.equals(currentBuffer)) {
+        return true;
+    }
+
+    // If buffers differ, it could be metadata or compression. Do pixel check.
+    // Note: Creating a new canvas to draw the image onto for pixel access
+    // This requires the 'Canvas' constructor which we imported.
+    const baselineCanvas = new Canvas(width, height);
+    const ctx = baselineCanvas.getContext('2d');
+    ctx.drawImage(baselineImage, 0, 0);
+    const baselineData = ctx.getImageData(0, 0, width, height).data;
+
+    // Load current buffer to image to draw (handles JSDOM/napi differences uniformally)
+    const currentImage = new Image();
+    currentImage.src = currentBuffer;
+
+    if (currentImage.width !== width || currentImage.height !== height) {
+        console.error(`Dimension mismatch: Baseline ${width}x${height} vs Current ${currentImage.width}x${currentImage.height}`);
+        return false;
+    }
+
+    const currentCanvas = new Canvas(width, height);
+    const ctx2 = currentCanvas.getContext('2d');
+    ctx2.drawImage(currentImage, 0, 0);
+    const currentData = ctx2.getImageData(0, 0, width, height).data;
+
+    let diffPixels = 0;
+    const totalPixels = width * height;
+
+    // Simple pixel diff
+    for (let i = 0; i < baselineData.length; i += 4) {
+        if (baselineData[i] !== currentData[i] ||         // R
+            baselineData[i+1] !== currentData[i+1] ||     // G
+            baselineData[i+2] !== currentData[i+2] ||     // B
+            baselineData[i+3] !== currentData[i+3]) {     // A
+            diffPixels++;
+        }
+    }
+
+    if (diffPixels > 0) {
+        console.error(`Visual regression: ${diffPixels} pixels differ (${(diffPixels/totalPixels*100).toFixed(2)}%)`);
+        // Save diff image? (Optional, skipping for now)
+        return false;
+    }
+
+    return true;
+}
+
+/**
+ * Compares two screenshots (Buffers).
+ * Uses simple buffer check. Kept for backward compatibility or direct buffer comparison.
+ */
+export function compareScreenshots(baseline: Buffer, current: Buffer, threshold: number = 0.01): VisualDiff {
+    // Basic length check first
+    if (baseline.length !== current.length) {
+        return { diffPercentage: 1.0 };
+    }
+
+    let diffPixels = 0;
+    const totalPixels = baseline.length; // Approximate bytes
+
+    for (let i = 0; i < baseline.length; i++) {
+        if (baseline[i] !== current[i]) {
+            diffPixels++;
+        }
+    }
+
+    const diffPercentage = diffPixels / totalPixels;
+
+    return {
+        diffPercentage,
+    };
+}
+
+export interface VisualScenario {
+    sceneName: string;
+    setup: () => Promise<void>;
+}
+
+/**
+ * Creates a visual test scenario.
+ */
+export function createVisualTestScenario(sceneName: string): VisualScenario {
+    return {
+        sceneName,
+        setup: async () => {
+            // Setup scene logic
+        }
+    };
+}

package/src/engine/helpers/pipeline-test-template.ts

@@ -0,0 +1,113 @@
+import { expect } from 'vitest';
+import {
+  createRenderTestSetup,
+  renderAndCapture,
+  createComputeTestSetup,
+  runComputeAndReadback,
+  RenderTestSetup,
+  ComputeTestSetup
+} from './webgpu-rendering.js';
+
+export interface GeometryBuffers {
+  vertexBuffer: GPUBuffer;
+  indexBuffer?: GPUBuffer;
+  vertexCount: number;
+  indexCount?: number;
+}
+
+/**
+ * Template for testing a rendering pipeline
+ */
+export async function testPipelineRendering(
+  name: string,
+  createPipeline: (device: GPUDevice) => GPURenderPipeline,
+  setupGeometry: (device: GPUDevice) => GeometryBuffers,
+  expectedOutput?: Uint8ClampedArray
+) {
+  const setup = await createRenderTestSetup(256, 256);
+
+  try {
+    const pipeline = createPipeline(setup.context.device);
+    const geometry = setupGeometry(setup.context.device);
+
+    const pixels = await renderAndCapture(setup, (pass) => {
+      pass.setPipeline(pipeline);
+      pass.setVertexBuffer(0, geometry.vertexBuffer);
+      if (geometry.indexBuffer) {
+        pass.setIndexBuffer(geometry.indexBuffer, 'uint16'); // Assuming uint16 for simplicity
+        pass.drawIndexed(geometry.indexCount || 0);
+      } else {
+        pass.draw(geometry.vertexCount);
+      }
+    });
+
+    if (expectedOutput) {
+      expect(pixels).toEqual(expectedOutput);
+    } else {
+      // At least verify we got pixels
+      expect(pixels.length).toBe(256 * 256 * 4);
+    }
+  } finally {
+    await setup.cleanup();
+  }
+}
+
+/**
+ * Template for testing compute shaders
+ */
+export async function testComputeShader(
+  name: string,
+  createComputePipeline: (device: GPUDevice) => GPUComputePipeline,
+  inputData: Float32Array,
+  expectedOutput?: Float32Array
+) {
+  const setup = await createComputeTestSetup(inputData.byteLength);
+  const { device } = setup.context;
+
+  try {
+     const pipeline = createComputePipeline(device);
+
+     // Initialize input data
+     const stagingBuffer = device.createBuffer({
+       size: inputData.byteLength,
+       usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE,
+       mappedAtCreation: true
+     });
+     new Float32Array(stagingBuffer.getMappedRange()).set(inputData);
+     stagingBuffer.unmap();
+
+     // Copy input to output buffer for processing
+     const encoder = device.createCommandEncoder();
+     encoder.copyBufferToBuffer(stagingBuffer, 0, setup.outputBuffer, 0, inputData.byteLength);
+     device.queue.submit([encoder.finish()]);
+
+     // Create a bind group for the storage buffer
+     const bindGroup = device.createBindGroup({
+         layout: pipeline.getBindGroupLayout(0),
+         entries: [
+             {
+                 binding: 0,
+                 resource: {
+                     buffer: setup.outputBuffer
+                 }
+             }
+         ]
+     });
+
+     const resultBuffer = await runComputeAndReadback(setup, (pass) => {
+         pass.setPipeline(pipeline);
+         pass.setBindGroup(0, bindGroup);
+         pass.dispatchWorkgroups(Math.ceil(inputData.length / 64));
+     });
+
+     if (expectedOutput) {
+         const floatResult = new Float32Array(resultBuffer);
+         expect(floatResult).toEqual(expectedOutput);
+     }
+
+     stagingBuffer.destroy();
+
+  } finally {
+    await setup.cleanup();
+  }
+}

package/src/engine/helpers/webgpu-rendering.ts

@@ -0,0 +1,251 @@
+import { initHeadlessWebGPU, WebGPUContextState } from '../../setup/webgpu.js';
+
+/**
+ * Interface for render test setup
+ */
+export interface RenderTestSetup {
+  context: WebGPUContextState;
+  renderTarget: GPUTexture;
+  renderTargetView: GPUTextureView;
+  commandEncoder: GPUCommandEncoder;
+  cleanup: () => Promise<void>;
+  width: number;
+  height: number;
+}
+
+/**
+ * Creates a setup for testing rendering pipelines.
+ * Initializes a headless WebGPU context, a render target texture, and a command encoder.
+ */
+export async function createRenderTestSetup(
+  width: number = 256,
+  height: number = 256
+): Promise<RenderTestSetup> {
+  const setup = await initHeadlessWebGPU();
+  const { device } = setup;
+
+  // Create a render target texture
+  // We use RGBA8Unorm for easy readback and standard rendering
+  const renderTarget = device.createTexture({
+    size: { width, height, depthOrArrayLayers: 1 },
+    format: 'rgba8unorm',
+    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
+  });
+
+  const renderTargetView = renderTarget.createView();
+
+  const commandEncoder = device.createCommandEncoder();
+
+  // We need to create a context state object compatible with our engine expectations
+  const context: WebGPUContextState = {
+    adapter: setup.adapter,
+    device: setup.device,
+    queue: setup.device.queue,
+    format: 'rgba8unorm',
+  };
+
+  return {
+    context,
+    renderTarget,
+    renderTargetView,
+    commandEncoder,
+    width,
+    height,
+    cleanup: async () => {
+        renderTarget.destroy();
+        await setup.cleanup();
+    }
+  };
+}
+
+/**
+ * Captures texture content to Uint8ClampedArray (RGBA).
+ * Creates its own CommandEncoder and submits immediately.
+ */
+export async function captureTexture(
+    device: GPUDevice,
+    texture: GPUTexture,
+    width: number,
+    height: number
+): Promise<Uint8ClampedArray> {
+  const commandEncoder = device.createCommandEncoder();
+
+  // Create a buffer to read back the texture data
+  // Bytes per row must be a multiple of 256 for copyTextureToBuffer
+  const bytesPerPixel = 4;
+  const unpaddedBytesPerRow = width * bytesPerPixel;
+  const align = 256;
+  const paddedBytesPerRow = Math.max(
+      bytesPerPixel * width,
+      Math.ceil((bytesPerPixel * width) / align) * align
+  );
+
+  const bufferSize = paddedBytesPerRow * height;
+
+  const readbackBuffer = device.createBuffer({
+    size: bufferSize,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+  });
+
+  // Copy texture to buffer
+  commandEncoder.copyTextureToBuffer(
+    {
+      texture: texture,
+    },
+    {
+      buffer: readbackBuffer,
+      bytesPerRow: paddedBytesPerRow,
+    },
+    {
+      width,
+      height,
+      depthOrArrayLayers: 1,
+    }
+  );
+
+  device.queue.submit([commandEncoder.finish()]);
+
+  await readbackBuffer.mapAsync(GPUMapMode.READ);
+
+  const arrayBuffer = readbackBuffer.getMappedRange();
+
+  // Create a new buffer to hold the tightly packed data
+  const output = new Uint8ClampedArray(width * height * 4);
+
+  // Copy row by row to remove padding
+  const srcBytes = new Uint8Array(arrayBuffer);
+  for (let y = 0; y < height; y++) {
+    const srcOffset = y * paddedBytesPerRow;
+    const dstOffset = y * unpaddedBytesPerRow;
+    output.set(srcBytes.subarray(srcOffset, srcOffset + unpaddedBytesPerRow), dstOffset);
+  }
+
+  readbackBuffer.unmap();
+  readbackBuffer.destroy();
+
+  return output;
+}
+
+/**
+ * Helper to render and capture the output as pixel data.
+ * It manages the render pass, submission, and buffer readback.
+ */
+export async function renderAndCapture(
+  setup: RenderTestSetup,
+  renderFn: (pass: GPURenderPassEncoder) => void
+): Promise<Uint8ClampedArray> {
+  const { device, queue } = setup.context;
+  const { renderTargetView, commandEncoder, width, height } = setup;
+
+  // Begin render pass
+  const passEncoder = commandEncoder.beginRenderPass({
+    colorAttachments: [
+      {
+        view: renderTargetView,
+        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+        loadOp: 'clear',
+        storeOp: 'store',
+      },
+    ],
+  });
+
+  // Invoke user render function
+  renderFn(passEncoder);
+
+  // End pass
+  passEncoder.end();
+
+  // Submit the render commands
+  queue.submit([commandEncoder.finish()]);
+
+  // Capture the texture (using a new encoder)
+  return captureTexture(device, setup.renderTarget, width, height);
+}
+
+/**
+ * Interface for compute test setup
+ */
+export interface ComputeTestSetup {
+  context: WebGPUContextState;
+  outputBuffer: GPUBuffer;
+  commandEncoder: GPUCommandEncoder;
+  cleanup: () => Promise<void>;
+  outputSize: number;
+}
+
+/**
+ * Creates a setup for testing compute shaders.
+ */
+export async function createComputeTestSetup(
+  outputSize: number
+): Promise<ComputeTestSetup> {
+  const setup = await initHeadlessWebGPU();
+  const { device } = setup;
+
+  // Create output buffer (storage and copy source)
+  const outputBuffer = device.createBuffer({
+    size: outputSize,
+    usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+  });
+
+  const commandEncoder = device.createCommandEncoder();
+
+  const context: WebGPUContextState = {
+    adapter: setup.adapter,
+    device: setup.device,
+    queue: setup.device.queue,
+    format: 'rgba8unorm',
+  };
+
+  return {
+    context,
+    outputBuffer,
+    commandEncoder,
+    outputSize,
+    cleanup: async () => {
+      outputBuffer.destroy();
+      await setup.cleanup();
+    }
+  };
+}
+
+/**
+ * Helper to run a compute pass and read back the output buffer.
+ */
+export async function runComputeAndReadback(
+  setup: ComputeTestSetup,
+  computeFn: (pass: GPUComputePassEncoder) => void
+): Promise<ArrayBuffer> {
+  const { device, queue } = setup.context;
+  const { outputBuffer, commandEncoder, outputSize } = setup;
+
+  const passEncoder = commandEncoder.beginComputePass();
+  computeFn(passEncoder);
+  passEncoder.end();
+
+  // Create staging buffer for readback
+  const stagingBuffer = device.createBuffer({
+    size: outputSize,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+  });
+
+  commandEncoder.copyBufferToBuffer(
+    outputBuffer,
+    0,
+    stagingBuffer,
+    0,
+    outputSize
+  );
+
+  queue.submit([commandEncoder.finish()]);
+
+  await stagingBuffer.mapAsync(GPUMapMode.READ);
+
+  const mappedRange = stagingBuffer.getMappedRange();
+  const result = mappedRange.slice(0); // Copy data
+
+  stagingBuffer.unmap();
+  stagingBuffer.destroy();
+
+  return result;
+}

package/src/engine/mocks/assets.ts

@@ -0,0 +1,129 @@
+import { vi } from 'vitest';
+import {
+  AssetManager,
+  Md2Model,
+  Md3Model,
+  BspMap,
+  PreparedTexture
+} from '@quake2ts/engine';
+
+export function createMockAssetManager(overrides?: Partial<AssetManager>): AssetManager {
+  return {
+    textures: {
+        get: vi.fn(),
+        set: vi.fn(),
+        has: vi.fn(),
+        clear: vi.fn(),
+        memoryUsage: 0
+    } as any,
+    audio: {
+        load: vi.fn(),
+        get: vi.fn(),
+        clearAll: vi.fn()
+    } as any,
+    loadTexture: vi.fn().mockResolvedValue({} as PreparedTexture),
+    registerTexture: vi.fn(),
+    loadSound: vi.fn().mockResolvedValue({} as any),
+    loadMd2Model: vi.fn().mockResolvedValue({} as Md2Model),
+    getMd2Model: vi.fn(),
+    loadMd3Model: vi.fn().mockResolvedValue({} as Md3Model),
+    getMd3Model: vi.fn(),
+    loadSprite: vi.fn().mockResolvedValue({} as any),
+    loadMap: vi.fn().mockResolvedValue({} as BspMap),
+    getMap: vi.fn(),
+    loadPalette: vi.fn().mockResolvedValue(undefined),
+    isAssetLoaded: vi.fn().mockReturnValue(true),
+    listFiles: vi.fn().mockReturnValue([]),
+    resetForLevelChange: vi.fn(),
+    getMemoryUsage: vi.fn().mockReturnValue({ textures: 0, audio: 0 }),
+    clearCache: vi.fn(),
+    preloadAssets: vi.fn().mockResolvedValue(undefined),
+    queueLoad: vi.fn().mockImplementation((path) => Promise.resolve({} as any)),
+    ...overrides
+  } as unknown as AssetManager;
+}
+
+export function createMockTexture(width: number = 1, height: number = 1, data?: Uint8Array): PreparedTexture {
+    return {
+        width,
+        height,
+        data: data || new Uint8Array(width * height * 4).fill(255),
+        format: 0, // RGBA
+        name: 'mock_texture',
+        uploaded: false
+    } as unknown as PreparedTexture;
+}
+
+export function createMockMd2Model(overrides?: Partial<Md2Model>): Md2Model {
+    return {
+        header: {
+            skinWidth: 0,
+            skinHeight: 0,
+            frameSize: 0,
+            numSkins: 0,
+            numVertices: 0,
+            numSt: 0,
+            numTriangles: 0,
+            numGlCmds: 0,
+            numFrames: 0,
+            offsetSkins: 0,
+            offsetSt: 0,
+            offsetTriangles: 0,
+            offsetFrames: 0,
+            offsetGlCmds: 0,
+            offsetEnd: 0
+        },
+        skins: [],
+        texCoords: [],
+        triangles: [],
+        frames: [],
+        glCommands: new Int32Array(0),
+        ...overrides
+    } as Md2Model;
+}
+
+export function createMockMd3Model(overrides?: Partial<Md3Model>): Md3Model {
+    return {
+        header: {
+            ident: 0,
+            version: 0,
+            name: '',
+            flags: 0,
+            numFrames: 0,
+            numTags: 0,
+            numSurfaces: 0,
+            numSkins: 0,
+            offsetFrames: 0,
+            offsetTags: 0,
+            offsetSurfaces: 0,
+            offsetEnd: 0
+        },
+        frames: [],
+        tags: [],
+        surfaces: [],
+        ...overrides
+    } as Md3Model;
+}
+
+export function createMockBspMap(overrides?: Partial<BspMap>): BspMap {
+    return {
+        version: 38,
+        entities: [],
+        planes: [],
+        vertices: [],
+        visibility: new Uint8Array(0),
+        nodes: [],
+        texInfo: [],
+        faces: [],
+        lightmaps: [],
+        leafs: [],
+        leafFaces: [],
+        leafBrushes: [],
+        edges: [],
+        faceEdges: [],
+        models: [],
+        brushes: [],
+        brushSides: [],
+        ...overrides
+    } as BspMap;
+}