@drmxrcy/tcg-core 0.0.0-202602060542

package/src/testing/test-replay-assertions.ts

@@ -0,0 +1,164 @@
+import type { RuleEngine } from "../engine/rule-engine";
+
+/**
+ * Test Replay Assertions
+ *
+ * Assertion helpers for testing deterministic replay behavior
+ */
+
+/**
+ * Assert that replaying the game produces the same final state
+ *
+ * This verifies that the game is deterministic by:
+ * 1. Capturing the current game state
+ * 2. Replaying all moves from the beginning
+ * 3. Comparing the final states
+ *
+ * This is crucial for:
+ * - Network synchronization
+ * - Game recordings/replays
+ * - Bug reproduction
+ * - Ensuring RNG is properly seeded
+ *
+ * @param engine - Rule engine instance with move history
+ * @throws Error if replay produces different state
+ *
+ * @example
+ * ```typescript
+ * const engine = new RuleEngine(gameDefinition, players, {
+ *   seed: 'test-seed'
+ * });
+ *
+ * // Execute some moves
+ * engine.executeMove('shuffle', { playerId: 'p1' });
+ * engine.executeMove('draw', { playerId: 'p1' });
+ * engine.executeMove('play', { playerId: 'p1', data: { cardId: 'card1' } });
+ *
+ * // Verify replay is deterministic
+ * expectDeterministicReplay(engine);
+ * ```
+ */
+export function expectDeterministicReplay<
+  TState,
+  TMoves extends Record<string, any>,
+>(engine: RuleEngine<TState, TMoves>): void {
+  // Get current state
+  const originalState = engine.getState();
+
+  // Replay from the beginning
+  const replayedState = engine.replay();
+
+  // Compare states
+  const originalJson = JSON.stringify(originalState);
+  const replayedJson = JSON.stringify(replayedState);
+
+  if (originalJson !== replayedJson) {
+    // Find differences for better error message
+    const diff = findStateDifferences(originalState, replayedState);
+
+    throw new Error(
+      "Replay produced different state than original execution.\n" +
+        "This indicates non-deterministic behavior in your game logic.\n\n" +
+        "Common causes:\n" +
+        "- Using Math.random() instead of context.rng\n" +
+        "- Using Date.now() or other time-based values\n" +
+        "- External state mutations\n" +
+        "- Non-deterministic array sorting\n\n" +
+        `Differences found:\n${diff}\n\n` +
+        `Original state: ${truncateString(originalJson, 500)}\n\n` +
+        `Replayed state: ${truncateString(replayedJson, 500)}`,
+    );
+  }
+}
+
+/**
+ * Find differences between two states for error reporting
+ *
+ * @param original - Original state
+ * @param replayed - Replayed state
+ * @returns String describing differences
+ */
+function findStateDifferences(original: any, replayed: any): string {
+  const differences: string[] = [];
+
+  const findDiffs = (obj1: any, obj2: any, path = "") => {
+    if (typeof obj1 !== typeof obj2) {
+      differences.push(
+        `${path || "root"}: type mismatch (${typeof obj1} vs ${typeof obj2})`,
+      );
+      return;
+    }
+
+    if (typeof obj1 !== "object" || obj1 === null || obj2 === null) {
+      if (obj1 !== obj2) {
+        differences.push(
+          `${path || "root"}: value mismatch (${JSON.stringify(obj1)} vs ${JSON.stringify(obj2)})`,
+        );
+      }
+      return;
+    }
+
+    // Check arrays
+    if (Array.isArray(obj1) && Array.isArray(obj2)) {
+      if (obj1.length !== obj2.length) {
+        differences.push(
+          `${path || "root"}: array length mismatch (${obj1.length} vs ${obj2.length})`,
+        );
+        return;
+      }
+
+      for (let i = 0; i < obj1.length; i++) {
+        findDiffs(obj1[i], obj2[i], `${path}[${i}]`);
+      }
+      return;
+    }
+
+    // Check objects
+    const keys1 = Object.keys(obj1).sort();
+    const keys2 = Object.keys(obj2).sort();
+
+    const allKeys = new Set([...keys1, ...keys2]);
+
+    for (const key of allKeys) {
+      if (!(key in obj1)) {
+        differences.push(`${path}.${key}: missing in original`);
+      } else if (key in obj2) {
+        findDiffs(obj1[key], obj2[key], path ? `${path}.${key}` : key);
+      } else {
+        differences.push(`${path}.${key}: missing in replay`);
+      }
+    }
+  };
+
+  findDiffs(original, replayed);
+
+  if (differences.length === 0) {
+    return "States are identical (this shouldn't happen)";
+  }
+
+  // Limit differences shown
+  const maxDiffs = 10;
+  const shown = differences.slice(0, maxDiffs);
+  const remaining = differences.length - maxDiffs;
+
+  let result = shown.join("\n");
+  if (remaining > 0) {
+    result += `\n... and ${remaining} more differences`;
+  }
+
+  return result;
+}
+
+/**
+ * Truncate a string for display
+ *
+ * @param str - String to truncate
+ * @param maxLength - Maximum length
+ * @returns Truncated string
+ */
+function truncateString(str: string, maxLength: number): string {
+  if (str.length <= maxLength) {
+    return str;
+  }
+  return `${str.substring(0, maxLength)}... (${str.length - maxLength} more chars)`;
+}

package/src/testing/test-rng-helpers.test.ts

@@ -0,0 +1,260 @@
+import { describe, expect, it } from "bun:test";
+import type { SeededRNG } from "../rng/seeded-rng";
+import {
+  createDeterministicRNG,
+  expectDeterministicBehavior,
+  withSeed,
+} from "./test-rng-helpers";
+
+describe("test-rng-helpers", () => {
+  describe("withSeed", () => {
+    it("should execute function with deterministic RNG", () => {
+      const result1 = withSeed("test-seed", (rng) => {
+        return rng.randomInt(1, 100);
+      });
+
+      const result2 = withSeed("test-seed", (rng) => {
+        return rng.randomInt(1, 100);
+      });
+
+      // Same seed should produce same results
+      expect(result1).toBe(result2);
+    });
+
+    it("should produce different results with different seeds", () => {
+      const result1 = withSeed("seed-1", (rng) => {
+        return rng.randomInt(1, 100);
+      });
+
+      const result2 = withSeed("seed-2", (rng) => {
+        return rng.randomInt(1, 100);
+      });
+
+      // Different seeds should (very likely) produce different results
+      // This test could theoretically fail but probability is very low
+      expect(result1).not.toBe(result2);
+    });
+
+    it("should work with multiple RNG operations", () => {
+      const results1 = withSeed("test-seed", (rng) => {
+        return [
+          rng.randomInt(1, 10),
+          rng.randomInt(1, 10),
+          rng.randomInt(1, 10),
+        ];
+      });
+
+      const results2 = withSeed("test-seed", (rng) => {
+        return [
+          rng.randomInt(1, 10),
+          rng.randomInt(1, 10),
+          rng.randomInt(1, 10),
+        ];
+      });
+
+      // Same seed should produce same sequence
+      expect(results1).toEqual(results2);
+    });
+
+    it("should work with shuffle operations", () => {
+      const array = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+
+      const shuffled1 = withSeed("shuffle-seed", (rng) => {
+        return rng.shuffle(array);
+      });
+
+      const shuffled2 = withSeed("shuffle-seed", (rng) => {
+        return rng.shuffle(array);
+      });
+
+      // Same seed should produce same shuffle
+      expect(shuffled1).toEqual(shuffled2);
+    });
+
+    it("should work with pick operations", () => {
+      const array = ["a", "b", "c", "d", "e"];
+
+      const picked1 = withSeed("pick-seed", (rng) => {
+        return [rng.pick(array), rng.pick(array), rng.pick(array)];
+      });
+
+      const picked2 = withSeed("pick-seed", (rng) => {
+        return [rng.pick(array), rng.pick(array), rng.pick(array)];
+      });
+
+      // Same seed should produce same picks
+      expect(picked1).toEqual(picked2);
+    });
+
+    it("should return function result", () => {
+      const result = withSeed("test", (rng) => {
+        return { value: rng.randomInt(1, 10), text: "hello" };
+      });
+
+      expect(result).toHaveProperty("value");
+      expect(result).toHaveProperty("text");
+      expect(result.text).toBe("hello");
+    });
+  });
+
+  describe("createDeterministicRNG", () => {
+    it("should create RNG with specified seed", () => {
+      const rng = createDeterministicRNG("my-seed");
+
+      expect(rng.getSeed()).toBe("my-seed");
+    });
+
+    it("should use default seed if none provided", () => {
+      const rng = createDeterministicRNG();
+
+      expect(rng.getSeed()).toBe("test-seed");
+    });
+
+    it("should produce deterministic results", () => {
+      const rng1 = createDeterministicRNG("same-seed");
+      const rng2 = createDeterministicRNG("same-seed");
+
+      const value1 = rng1.randomInt(1, 1000);
+      const value2 = rng2.randomInt(1, 1000);
+
+      expect(value1).toBe(value2);
+    });
+
+    it("should be reusable", () => {
+      const rng = createDeterministicRNG("reuse-seed");
+
+      const results1 = [rng.randomInt(1, 10), rng.randomInt(1, 10)];
+
+      // Reset by creating new RNG with same seed
+      const rng2 = createDeterministicRNG("reuse-seed");
+      const results2 = [rng2.randomInt(1, 10), rng2.randomInt(1, 10)];
+
+      expect(results1).toEqual(results2);
+    });
+  });
+
+  describe("expectDeterministicBehavior", () => {
+    it("should pass when function produces same results", () => {
+      const fn = (rng: SeededRNG) => rng.randomInt(1, 100);
+
+      // Should not throw
+      expectDeterministicBehavior(fn, "test-seed");
+    });
+
+    it("should throw when function produces different results", () => {
+      let counter = 0;
+      const fn = (rng: SeededRNG) => {
+        // Add non-deterministic behavior
+        counter++;
+        return rng.randomInt(1, 100) + counter;
+      };
+
+      expect(() => {
+        expectDeterministicBehavior(fn, "test-seed");
+      }).toThrow(/deterministic/);
+    });
+
+    it("should work with complex return values", () => {
+      const fn = (rng: SeededRNG) => ({
+        roll: rng.randomInt(1, 6),
+        flip: rng.flipCoin(),
+        pick: rng.pick(["a", "b", "c"]),
+      });
+
+      // Should not throw
+      expectDeterministicBehavior(fn, "complex-seed");
+    });
+
+    it("should work with array returns", () => {
+      const fn = (rng: SeededRNG) => {
+        return Array.from({ length: 10 }, () => rng.randomInt(1, 100));
+      };
+
+      // Should not throw
+      expectDeterministicBehavior(fn, "array-seed");
+    });
+
+    it("should detect non-determinism from external state", () => {
+      let callCount = 0;
+      const fn = (rng: SeededRNG) => {
+        // Each call uses a different RNG seed due to external state
+        callCount++;
+        const tempRng = new (
+          rng.constructor as new (
+            seed: string,
+          ) => SeededRNG
+        )(`seed-${callCount}`);
+        return tempRng.randomInt(1, 100);
+      };
+
+      callCount = 0;
+      expect(() => {
+        expectDeterministicBehavior(fn, "shuffle-seed");
+      }).toThrow(/deterministic/);
+    });
+
+    it("should use default seed if none provided", () => {
+      const fn = (rng: SeededRNG) => rng.randomInt(1, 10);
+
+      // Should not throw
+      expectDeterministicBehavior(fn);
+    });
+
+    it("should provide helpful error message", () => {
+      let callCount = 0;
+      const fn = (_rng: SeededRNG) => {
+        callCount++;
+        return callCount; // Always different
+      };
+
+      expect(() => {
+        expectDeterministicBehavior(fn, "test");
+      }).toThrow(/Expected function to be deterministic/);
+    });
+  });
+
+  describe("integration", () => {
+    it("should help test game mechanics", () => {
+      // Simulate drawing cards deterministically
+      const drawCards = (rng: SeededRNG, count: number) => {
+        const deck = ["card1", "card2", "card3", "card4", "card5"];
+        const shuffled = rng.shuffle(deck);
+        return shuffled.slice(0, count);
+      };
+
+      const hand1 = withSeed("game-seed", (rng) => drawCards(rng, 3));
+      const hand2 = withSeed("game-seed", (rng) => drawCards(rng, 3));
+
+      expect(hand1).toEqual(hand2);
+    });
+
+    it("should help test dice rolls", () => {
+      const rollAttack = (rng: SeededRNG) => {
+        const attack = rng.rollDice(20) as number; // d20
+        const damage = rng.rollDice(6, 2) as number[]; // 2d6
+        return { attack, damage };
+      };
+
+      const result1 = withSeed("combat-seed", rollAttack);
+      const result2 = withSeed("combat-seed", rollAttack);
+
+      expect(result1).toEqual(result2);
+    });
+
+    it("should help test probability distributions", () => {
+      const generateResults = (rng: SeededRNG) => {
+        return Array.from({ length: 100 }, () => rng.randomInt(1, 6));
+      };
+
+      const results1 = withSeed("distribution-seed", generateResults);
+      const results2 = withSeed("distribution-seed", generateResults);
+
+      // Should be identical
+      expect(results1).toEqual(results2);
+
+      // Should have good distribution (all values 1-6 appear)
+      const uniqueValues = new Set(results1);
+      expect(uniqueValues.size).toBeGreaterThan(4); // At least 5 different values
+    });
+  });
+});

package/src/testing/test-rng-helpers.ts

@@ -0,0 +1,190 @@
+import { SeededRNG } from "../rng/seeded-rng";
+
+/**
+ * Test RNG Helpers
+ *
+ * Utilities for testing with deterministic randomness
+ */
+
+/**
+ * Execute a function with a seeded RNG
+ *
+ * Creates a temporary RNG instance with the specified seed,
+ * executes the function, and returns its result.
+ *
+ * @param seed - Seed for deterministic behavior
+ * @param fn - Function to execute with RNG
+ * @returns Result of the function
+ *
+ * @example
+ * ```typescript
+ * const result = withSeed('test-seed', (rng) => {
+ *   return rng.shuffle([1, 2, 3, 4, 5]);
+ * });
+ *
+ * // Same seed produces same result
+ * const result2 = withSeed('test-seed', (rng) => {
+ *   return rng.shuffle([1, 2, 3, 4, 5]);
+ * });
+ * expect(result).toEqual(result2);
+ * ```
+ */
+export function withSeed<T>(seed: string, fn: (rng: SeededRNG) => T): T {
+  const rng = new SeededRNG(seed);
+  return fn(rng);
+}
+
+/**
+ * Create a deterministic RNG for testing
+ *
+ * Creates an RNG instance with a known seed for predictable testing.
+ *
+ * @param seed - Optional seed (default: 'test-seed')
+ * @returns Seeded RNG instance
+ *
+ * @example
+ * ```typescript
+ * const rng = createDeterministicRNG('my-test');
+ * const value1 = rng.randomInt(1, 100);
+ *
+ * // Recreate with same seed for same results
+ * const rng2 = createDeterministicRNG('my-test');
+ * const value2 = rng2.randomInt(1, 100);
+ *
+ * expect(value1).toBe(value2);
+ * ```
+ */
+export function createDeterministicRNG(seed = "test-seed"): SeededRNG {
+  return new SeededRNG(seed);
+}
+
+/**
+ * Assert that a function produces deterministic results with same seed
+ *
+ * Executes the function twice with the same seed and verifies
+ * that the results are identical.
+ *
+ * @param fn - Function to test for determinism
+ * @param seed - Optional seed (default: 'determinism-test')
+ * @throws Error if function produces different results
+ *
+ * @example
+ * ```typescript
+ * // Test that shuffle is deterministic
+ * expectDeterministicBehavior((rng) => {
+ *   return rng.shuffle([1, 2, 3, 4, 5]);
+ * });
+ *
+ * // Test game mechanic
+ * expectDeterministicBehavior((rng) => {
+ *   const deck = createDeck();
+ *   return drawCards(deck, 5, rng);
+ * }, 'draw-test-seed');
+ * ```
+ */
+export function expectDeterministicBehavior<T>(
+  fn: (rng: SeededRNG) => T,
+  seed = "determinism-test",
+): void {
+  const result1 = withSeed(seed, fn);
+  const result2 = withSeed(seed, fn);
+
+  // Deep equality check
+  if (JSON.stringify(result1) !== JSON.stringify(result2)) {
+    throw new Error(
+      `Expected function to be deterministic with seed '${seed}', but got different results:\n` +
+        `Run 1: ${JSON.stringify(result1)}\n` +
+        `Run 2: ${JSON.stringify(result2)}`,
+    );
+  }
+}
+
+/**
+ * Create multiple RNG instances with related seeds
+ *
+ * Useful for testing scenarios with multiple independent RNG streams
+ * (e.g., one per player) that need to be reproducible.
+ *
+ * @param count - Number of RNG instances to create
+ * @param baseSeed - Base seed for determinism
+ * @returns Array of seeded RNG instances
+ *
+ * @example
+ * ```typescript
+ * // Create RNG for each player
+ * const [p1Rng, p2Rng] = createMultipleRNGs(2, 'game-seed');
+ *
+ * // Each player gets deterministic but independent randomness
+ * const p1Roll = p1Rng.rollDice(20);
+ * const p2Roll = p2Rng.rollDice(20);
+ * ```
+ */
+export function createMultipleRNGs(
+  count: number,
+  baseSeed = "test",
+): SeededRNG[] {
+  return Array.from({ length: count }, (_, i) => {
+    return new SeededRNG(`${baseSeed}-${i}`);
+  });
+}
+
+/**
+ * Test a random operation multiple times with different seeds
+ *
+ * Useful for ensuring that random operations cover a good range
+ * of possible outcomes.
+ *
+ * @param fn - Function to test
+ * @param iterations - Number of iterations to run
+ * @returns Array of results
+ *
+ * @example
+ * ```typescript
+ * // Test that shuffle produces variety
+ * const results = testWithMultipleSeeds(
+ *   (rng) => rng.shuffle([1, 2, 3, 4, 5]),
+ *   100
+ * );
+ *
+ * // Verify we got different shuffles
+ * const uniqueResults = new Set(results.map(r => JSON.stringify(r)));
+ * expect(uniqueResults.size).toBeGreaterThan(10);
+ * ```
+ */
+export function testWithMultipleSeeds<T>(
+  fn: (rng: SeededRNG) => T,
+  iterations = 10,
+): T[] {
+  return Array.from({ length: iterations }, (_, i) => {
+    return withSeed(`test-iteration-${i}`, fn);
+  });
+}
+
+/**
+ * Create a predictable sequence of random values
+ *
+ * Useful for testing specific scenarios with known random values.
+ *
+ * @param seed - Seed for the sequence
+ * @param count - Number of values to generate
+ * @param min - Minimum value (inclusive)
+ * @param max - Maximum value (inclusive)
+ * @returns Array of random integers
+ *
+ * @example
+ * ```typescript
+ * // Generate predictable dice rolls for testing
+ * const rolls = createPredictableSequence('combat', 10, 1, 20);
+ * // Always gets same sequence of rolls with this seed
+ * ```
+ */
+export function createPredictableSequence(
+  seed: string,
+  count: number,
+  min: number,
+  max: number,
+): number[] {
+  return withSeed(seed, (rng) => {
+    return Array.from({ length: count }, () => rng.randomInt(min, max));
+  });
+}