@quake2ts/test-utils 0.0.1

package/src/shared/mocks.ts

@@ -0,0 +1,243 @@
+import { vi, type Mock } from 'vitest';
+
+/**
+ * Interface for the BinaryWriter mock.
+ */
+export interface BinaryWriterMock {
+    writeByte: Mock<[number], void>;
+    writeShort: Mock<[number], void>;
+    writeLong: Mock<[number], void>;
+    writeString: Mock<[string], void>;
+    writeBytes: Mock<[Uint8Array], void>;
+    getBuffer: Mock<[], Uint8Array>;
+    reset: Mock<[], void>;
+    writeInt8: Mock<[number], void>;
+    writeUint8: Mock<[number], void>;
+    writeInt16: Mock<[number], void>;
+    writeUint16: Mock<[number], void>;
+    writeInt32: Mock<[number], void>;
+    writeUint32: Mock<[number], void>;
+    writeFloat: Mock<[number], void>;
+    getData: Mock<[], Uint8Array>;
+    writePos: Mock<[any], void>;
+    writeDir: Mock<[any], void>;
+}
+
+/**
+ * Creates a mock BinaryWriter for testing binary data writing.
+ *
+ * @returns A BinaryWriterMock object with all methods mocked using vi.fn().
+ */
+export const createBinaryWriterMock = (): BinaryWriterMock => ({
+  writeByte: vi.fn(),
+  writeShort: vi.fn(),
+  writeLong: vi.fn(),
+  writeString: vi.fn(),
+  writeBytes: vi.fn(),
+  getBuffer: vi.fn<[], Uint8Array>(() => new Uint8Array(0)),
+  reset: vi.fn(),
+  // Legacy methods (if any)
+  writeInt8: vi.fn(),
+  writeUint8: vi.fn(),
+  writeInt16: vi.fn(),
+  writeUint16: vi.fn(),
+  writeInt32: vi.fn(),
+  writeUint32: vi.fn(),
+  writeFloat: vi.fn(),
+  getData: vi.fn<[], Uint8Array>(() => new Uint8Array(0)),
+  writePos: vi.fn(),
+  writeDir: vi.fn(),
+});
+
+/**
+ * Creates a mock NetChan (Network Channel) for testing network communication.
+ * Includes mocks for sequencing, reliable messaging, and fragmentation.
+ *
+ * @returns A mocked NetChan object.
+ */
+export const createNetChanMock = () => ({
+  qport: 1234,
+
+  // Sequencing
+  incomingSequence: 0,
+  outgoingSequence: 0,
+  incomingAcknowledged: 0,
+
+  // Reliable messaging
+  incomingReliableAcknowledged: false,
+  incomingReliableSequence: 0,
+  outgoingReliableSequence: 0,
+  reliableMessage: createBinaryWriterMock(),
+  reliableLength: 0,
+
+  // Fragmentation
+  fragmentSendOffset: 0,
+  fragmentBuffer: null,
+  fragmentLength: 0,
+  fragmentReceived: 0,
+
+  // Timing
+  lastReceived: 0,
+  lastSent: 0,
+
+  remoteAddress: { type: 'IP', port: 1234 },
+
+  // Methods
+  setup: vi.fn(),
+  reset: vi.fn(),
+  transmit: vi.fn(),
+  process: vi.fn(),
+  canSendReliable: vi.fn(() => true),
+  writeReliableByte: vi.fn(),
+  writeReliableShort: vi.fn(),
+  writeReliableLong: vi.fn(),
+  writeReliableString: vi.fn(),
+  getReliableData: vi.fn<[], Uint8Array>(() => new Uint8Array(0)),
+  needsKeepalive: vi.fn(() => false),
+  isTimedOut: vi.fn(() => false),
+});
+
+/**
+ * Interface for the BinaryStream mock.
+ */
+export interface BinaryStreamMock {
+    getPosition: Mock<[], number>;
+    getReadPosition: Mock<[], number>;
+    getLength: Mock<[], number>;
+    getRemaining: Mock<[], number>;
+    seek: Mock<[number], void>;
+    setReadPosition: Mock<[number], void>;
+    hasMore: Mock<[], boolean>;
+    hasBytes: Mock<[number], boolean>;
+
+    readChar: Mock<[], number>;
+    readByte: Mock<[], number>;
+    readShort: Mock<[], number>;
+    readUShort: Mock<[], number>;
+    readLong: Mock<[], number>;
+    readULong: Mock<[], number>;
+    readFloat: Mock<[], number>;
+
+    readString: Mock<[], string>;
+    readStringLine: Mock<[], string>;
+
+    readCoord: Mock<[], number>;
+    readAngle: Mock<[], number>;
+    readAngle16: Mock<[], number>;
+
+    readData: Mock<[number], Uint8Array>;
+
+    readPos: Mock<[], any>; // Use proper type if available, e.g., Vec3
+    readDir: Mock<[], any>;
+}
+
+/**
+ * Creates a mock BinaryStream for testing binary data reading.
+ *
+ * @returns A BinaryStreamMock object with all methods mocked.
+ */
+export const createBinaryStreamMock = (): BinaryStreamMock => ({
+  getPosition: vi.fn(() => 0),
+  getReadPosition: vi.fn(() => 0),
+  getLength: vi.fn(() => 0),
+  getRemaining: vi.fn(() => 0),
+  seek: vi.fn(),
+  setReadPosition: vi.fn(),
+  hasMore: vi.fn(() => true),
+  hasBytes: vi.fn((amount: number) => true),
+
+  readChar: vi.fn(() => 0),
+  readByte: vi.fn(() => 0),
+  readShort: vi.fn(() => 0),
+  readUShort: vi.fn(() => 0),
+  readLong: vi.fn(() => 0),
+  readULong: vi.fn(() => 0),
+  readFloat: vi.fn(() => 0),
+
+  readString: vi.fn(() => ''),
+  readStringLine: vi.fn(() => ''),
+
+  readCoord: vi.fn(() => 0),
+  readAngle: vi.fn(() => 0),
+  readAngle16: vi.fn(() => 0),
+
+  readData: vi.fn<[number], Uint8Array>((length: number) => new Uint8Array(length)),
+
+  readPos: vi.fn(),
+  readDir: vi.fn(),
+});
+
+/**
+ * Interface for MessageWriter mock, extending BinaryWriterMock with additional message-specific methods.
+ */
+export interface MessageWriterMock extends BinaryWriterMock {
+    writeInt: Mock<[number], void>;
+    writeVector: Mock<[any], void>;
+}
+
+/**
+ * Creates a mock MessageWriter, aliasing writeInt to writeInt32 and writeVector to writePos.
+ *
+ * @param overrides - Optional overrides for the mock.
+ * @returns A MessageWriterMock object.
+ */
+export const createMessageWriterMock = (overrides?: Partial<MessageWriterMock>): MessageWriterMock => {
+    const mock = createBinaryWriterMock();
+    const writer: MessageWriterMock = {
+        ...mock,
+        writeInt: mock.writeInt32, // Alias writeInt to writeInt32
+        writeVector: mock.writePos, // Alias writeVector to writePos
+        ...overrides
+    };
+    return writer;
+};
+
+/**
+ * Interface for MessageReader mock, extending BinaryStreamMock with additional message-specific methods.
+ */
+export interface MessageReaderMock extends BinaryStreamMock {
+    readInt: Mock<[], number>;
+    readVector: Mock<[], any>;
+}
+
+/**
+ * Creates a mock MessageReader, aliasing readInt to readLong and readVector to readPos.
+ *
+ * @param data - Optional initial data for the reader.
+ * @returns A MessageReaderMock object.
+ */
+export const createMessageReaderMock = (data?: Uint8Array): MessageReaderMock => {
+    const mock = createBinaryStreamMock();
+    const reader: MessageReaderMock = {
+        ...mock,
+        readInt: mock.readLong, // Alias readInt to readLong (int32)
+        readVector: mock.readPos, // Alias readVector to readPos
+    };
+    return reader;
+};
+
+/**
+ * Interface for a generic network packet mock.
+ */
+export interface PacketMock {
+    type: 'connection' | 'data' | 'ack' | 'disconnect';
+    sequence: number;
+    ack: number;
+    qport: number;
+    data: Uint8Array;
+}
+
+/**
+ * Creates a mock network packet.
+ *
+ * @param overrides - Optional overrides for packet properties.
+ * @returns A PacketMock object.
+ */
+export const createPacketMock = (overrides?: Partial<PacketMock>): PacketMock => ({
+    type: 'data',
+    sequence: 0,
+    ack: 0,
+    qport: 0,
+    data: new Uint8Array(0),
+    ...overrides
+});

package/src/shared/pak-loader.ts

@@ -0,0 +1,45 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { PakArchive } from '@quake2ts/engine';
+
+export function findPakFile(): string | null {
+  const possiblePaths = [
+    path.resolve(process.cwd(), 'pak.pak'),
+    path.resolve(process.cwd(), '../pak.pak'),
+    path.resolve(process.cwd(), '../../pak.pak'),
+    path.resolve(process.cwd(), '../../../pak.pak'),
+    path.resolve(process.cwd(), 'baseq2/pak.pak'),
+    path.resolve('/app/quake2ts/pak.pak'), // Common docker/env path
+    // Fallback for when running deeply nested tests
+    path.resolve(process.cwd(), 'quake2ts/pak.pak'),
+  ];
+
+  return possiblePaths.find(p => fs.existsSync(p)) || null;
+}
+
+export function loadMapFromPak(mapName: string): ArrayBuffer | null {
+  const pakPath = findPakFile();
+  if (!pakPath) {
+    console.warn('pak.pak not found');
+    return null;
+  }
+
+  try {
+    const pakBuffer = fs.readFileSync(pakPath);
+    // Cast to ArrayBuffer because node Buffer is compatible but types might mismatch
+    const arrayBuffer = pakBuffer.buffer.slice(pakBuffer.byteOffset, pakBuffer.byteOffset + pakBuffer.byteLength) as ArrayBuffer;
+
+    const pak = PakArchive.fromArrayBuffer('pak.pak', arrayBuffer);
+    const entry = pak.getEntry(mapName);
+
+    if (entry) {
+        // PakArchive.readFile returns Uint8Array, we might want ArrayBuffer
+        const data = pak.readFile(mapName);
+        return data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength) as ArrayBuffer;
+    }
+    return null;
+  } catch (e) {
+    console.error(`Failed to load map ${mapName} from pak:`, e);
+    return null;
+  }
+}

package/src/visual/snapshots.ts

@@ -0,0 +1,292 @@
+import { PNG } from 'pngjs';
+import pixelmatch from 'pixelmatch';
+import fs from 'fs/promises';
+import { createReadStream, createWriteStream, existsSync } from 'fs';
+import path from 'path';
+import { RenderTestSetup, renderAndCapture } from '../engine/helpers/webgpu-rendering.js';
+
+export interface CaptureOptions {
+  width: number;
+  height: number;
+  format?: GPUTextureFormat;
+}
+
+// Helper to pad bytes to 256 byte alignment (WebGPU requirement)
+function getBytesPerRow(width: number): number {
+  const bytesPerPixel = 4;
+  const unpaddedBytesPerRow = width * bytesPerPixel;
+  const align = 256;
+  const paddedBytesPerRow = Math.max(
+    unpaddedBytesPerRow,
+    Math.ceil(unpaddedBytesPerRow / align) * align
+  );
+  return paddedBytesPerRow;
+}
+
+export async function captureFramebufferAsPNG(
+  device: GPUDevice,
+  texture: GPUTexture,
+  options: CaptureOptions
+): Promise<Buffer> {
+  const { width, height, format = 'rgba8unorm' } = options;
+
+  const bytesPerRow = getBytesPerRow(width);
+  const bufferSize = bytesPerRow * height;
+
+  const outputBuffer = device.createBuffer({
+    size: bufferSize,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    label: 'captureFramebufferAsPNG output buffer'
+  });
+
+  const commandEncoder = device.createCommandEncoder({ label: 'captureFramebufferAsPNG encoder' });
+  commandEncoder.copyTextureToBuffer(
+    { texture },
+    { buffer: outputBuffer, bytesPerRow, rowsPerImage: height },
+    { width, height, depthOrArrayLayers: 1 }
+  );
+  device.queue.submit([commandEncoder.finish()]);
+
+  await outputBuffer.mapAsync(GPUMapMode.READ);
+  const mappedRange = outputBuffer.getMappedRange();
+  const rawData = new Uint8Array(mappedRange);
+
+  // Remove padding to get tight packed RGBA
+  const bytesPerPixel = 4;
+  const tightData = new Uint8ClampedArray(width * height * bytesPerPixel);
+
+  for (let y = 0; y < height; y++) {
+    const srcOffset = y * bytesPerRow;
+    const dstOffset = y * width * bytesPerPixel;
+    const rowSize = width * bytesPerPixel;
+    // Copy row
+    for (let i = 0; i < rowSize; i++) {
+        tightData[dstOffset + i] = rawData[srcOffset + i];
+    }
+  }
+
+  outputBuffer.unmap();
+
+  // Handle BGRA to RGBA conversion if needed
+  // Note: WebGPU usually prefers bgra8unorm for swapchains, but pngjs expects rgba
+  if (format === 'bgra8unorm' || format === 'bgra8unorm-srgb') {
+    for (let i = 0; i < tightData.length; i += 4) {
+      const b = tightData[i];
+      const r = tightData[i + 2];
+      tightData[i] = r;
+      tightData[i + 2] = b;
+    }
+  }
+
+  // Create PNG
+  const png = new PNG({ width, height });
+  png.data = Buffer.from(tightData);
+
+  return PNG.sync.write(png);
+}
+
+export async function savePNG(
+  pixels: Uint8ClampedArray,
+  width: number,
+  height: number,
+  filepath: string
+): Promise<void> {
+    const png = new PNG({ width, height });
+    png.data = Buffer.from(pixels);
+
+    await fs.mkdir(path.dirname(filepath), { recursive: true });
+
+    return new Promise((resolve, reject) => {
+        const stream = createWriteStream(filepath);
+        stream.on('error', reject);
+        stream.on('finish', resolve);
+        png.pack().pipe(stream);
+    });
+}
+
+export async function loadPNG(
+  filepath: string
+): Promise<{ data: Uint8ClampedArray; width: number; height: number }> {
+    return new Promise((resolve, reject) => {
+        const stream = createReadStream(filepath);
+        stream.on('error', reject);
+
+        const png = new PNG();
+        png.on('error', reject);
+        png.on('parsed', (data) => {
+            resolve({
+                data: new Uint8ClampedArray(data),
+                width: png.width,
+                height: png.height
+            });
+        });
+
+        stream.pipe(png);
+    });
+}
+
+export interface ComparisonResult {
+  pixelsDifferent: number;
+  totalPixels: number;
+  percentDifferent: number;
+  passed: boolean;
+  diffImage?: Uint8ClampedArray;
+}
+
+export interface ComparisonOptions {
+  threshold?: number;        // Pixel difference threshold (0-1), default 0.1
+  includeAA?: boolean;       // Include anti-aliasing detection
+  diffColor?: [number, number, number];  // Color for diff pixels
+  maxDifferencePercent?: number;  // Max % difference to pass, default 0.1%
+}
+
+export async function compareSnapshots(
+  actual: Uint8ClampedArray,
+  expected: Uint8ClampedArray,
+  width: number,
+  height: number,
+  options?: ComparisonOptions
+): Promise<ComparisonResult> {
+    const {
+        threshold = 0.1,
+        includeAA = false,
+        diffColor = [255, 0, 0],
+        maxDifferencePercent = 0.1
+    } = options || {};
+
+    if (actual.length !== expected.length) {
+        throw new Error(`Size mismatch: actual length ${actual.length} vs expected length ${expected.length}`);
+    }
+
+    const diff = new Uint8ClampedArray(width * height * 4);
+    const numDiffPixels = pixelmatch(
+        actual,
+        expected,
+        diff,
+        width,
+        height,
+        {
+            threshold,
+            includeAA,
+            diffColor: diffColor as [number, number, number],
+            alpha: 1 // Default alpha
+        }
+    );
+
+    const totalPixels = width * height;
+    const percentDifferent = (numDiffPixels / totalPixels) * 100;
+    const passed = percentDifferent <= (maxDifferencePercent || 0);
+
+    return {
+        pixelsDifferent: numDiffPixels,
+        totalPixels,
+        percentDifferent,
+        passed,
+        diffImage: diff
+    };
+}
+
+export interface SnapshotTestOptions extends ComparisonOptions {
+  name: string;
+  width?: number;
+  height?: number;
+  updateBaseline?: boolean;
+  snapshotDir?: string; // Root snapshot directory
+}
+
+export function getSnapshotPath(name: string, type: 'baseline' | 'actual' | 'diff', snapshotDir: string = '__snapshots__'): string {
+    const dirMap = {
+        baseline: 'baselines',
+        actual: 'actual',
+        diff: 'diff'
+    };
+    return path.join(snapshotDir, dirMap[type], `${name}.png`);
+}
+
+export async function expectSnapshot(
+  pixels: Uint8ClampedArray,
+  options: SnapshotTestOptions
+): Promise<void> {
+    const {
+        name,
+        width,
+        height,
+        updateBaseline = false,
+        snapshotDir = path.join(process.cwd(), 'tests', '__snapshots__') // Default to current working dir/tests/__snapshots__
+    } = options;
+
+    if (!width || !height) {
+        throw new Error('Width and height are required for expectSnapshot');
+    }
+
+    const baselinePath = getSnapshotPath(name, 'baseline', snapshotDir);
+    const actualPath = getSnapshotPath(name, 'actual', snapshotDir);
+    const diffPath = getSnapshotPath(name, 'diff', snapshotDir);
+
+    const alwaysSave = process.env.ALWAYS_SAVE_SNAPSHOTS === '1';
+
+    // If update baseline is requested or baseline doesn't exist, save as baseline and return
+    if (updateBaseline || !existsSync(baselinePath)) {
+        console.log(`Creating/Updating baseline for ${name} at ${baselinePath}`);
+        await savePNG(pixels, width, height, baselinePath);
+        return;
+    }
+
+    // Load baseline
+    let baseline: { data: Uint8ClampedArray; width: number; height: number };
+    try {
+        baseline = await loadPNG(baselinePath);
+    } catch (e) {
+        throw new Error(`Failed to load baseline for ${name} at ${baselinePath}: ${e}`);
+    }
+
+    if (baseline.width !== width || baseline.height !== height) {
+        // Save actual for debugging
+        await savePNG(pixels, width, height, actualPath);
+        throw new Error(`Snapshot dimension mismatch for ${name}: expected ${baseline.width}x${baseline.height}, got ${width}x${height}`);
+    }
+
+    // Compare
+    const result = await compareSnapshots(pixels, baseline.data, width, height, options);
+
+    // Save stats
+    const statsPath = path.join(snapshotDir, 'stats', `${name}.json`);
+    await fs.mkdir(path.dirname(statsPath), { recursive: true });
+    await fs.writeFile(statsPath, JSON.stringify({
+        passed: result.passed,
+        percentDifferent: result.percentDifferent,
+        pixelsDifferent: result.pixelsDifferent,
+        totalPixels: result.totalPixels,
+        threshold: options.threshold ?? 0.1,
+        maxDifferencePercent: options.maxDifferencePercent ?? 0.1
+    }, null, 2));
+
+    if (!result.passed || alwaysSave) {
+        // Save actual and diff
+        await savePNG(pixels, width, height, actualPath);
+        if (result.diffImage) {
+            await savePNG(result.diffImage, width, height, diffPath);
+        }
+    }
+
+    if (!result.passed) {
+        throw new Error(
+            `Snapshot comparison failed for ${name}: ${result.percentDifferent.toFixed(2)}% different ` +
+            `(${result.pixelsDifferent} pixels). ` +
+            `See ${diffPath} for details.`
+        );
+    }
+}
+
+export async function renderAndExpectSnapshot(
+  setup: RenderTestSetup,
+  renderFn: (pass: GPURenderPassEncoder) => void,
+  options: Omit<SnapshotTestOptions, 'width' | 'height'>
+): Promise<void> {
+    const pixels = await renderAndCapture(setup, renderFn);
+    await expectSnapshot(pixels, {
+        ...options,
+        width: setup.width,
+        height: setup.height
+    });
+}