@drmxrcy/tcg-core 0.0.0-202602060542

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

@@ -0,0 +1,115 @@
+import type { RuleEngine } from "../engine/rule-engine";
+import type { MoveContext, MoveContextInput } from "../moves/move-system";
+
+/**
+ * Test Flow Assertions
+ *
+ * Assertion helpers for testing game flow and phase transitions
+ */
+
+/**
+ * Assert that a move causes a phase transition
+ *
+ * Verifies that executing a move transitions from one phase to another.
+ * Supports custom phase paths for games that store phase in nested state.
+ *
+ * @param engine - Rule engine instance
+ * @param moveId - Move to execute
+ * @param context - Move context
+ * @param fromPhase - Expected initial phase
+ * @param toPhase - Expected final phase
+ * @param phasePath - Optional path to phase in state (default: 'phase')
+ * @throws Error if phase transition doesn't match expectations
+ *
+ * @example
+ * ```typescript
+ * // Test phase transition
+ * expectPhaseTransition(
+ *   engine,
+ *   'endPhase',
+ *   { playerId: 'p1' },
+ *   'main',
+ *   'end'
+ * );
+ *
+ * // Test with custom phase path
+ * expectPhaseTransition(
+ *   engine,
+ *   'advance',
+ *   { playerId: 'p1' },
+ *   'draw',
+ *   'main',
+ *   'gameState.currentPhase'
+ * );
+ * ```
+ */
+export function expectPhaseTransition<
+  TState,
+  TMoves extends Record<string, any>,
+>(
+  engine: RuleEngine<TState, TMoves>,
+  moveId: string,
+  context: MoveContextInput,
+  fromPhase: string,
+  toPhase: string,
+  phasePath = "phase",
+): void {
+  // Get initial state
+  const initialState = engine.getState();
+  const initialPhase = getPropertyByPath(initialState, phasePath);
+
+  // Verify initial phase
+  if (initialPhase !== fromPhase) {
+    throw new Error(
+      `Expected initial phase to be '${fromPhase}', but found '${initialPhase}'`,
+    );
+  }
+
+  // Execute move
+  const result = engine.executeMove(moveId, context);
+
+  // Check if move succeeded
+  if (!result.success) {
+    throw new Error(
+      `Move failed during phase transition test: ${result.error}` +
+        (result.errorCode ? ` (code: ${result.errorCode})` : ""),
+    );
+  }
+
+  // Get final state
+  const finalState = engine.getState();
+  const finalPhase = getPropertyByPath(finalState, phasePath);
+
+  // Verify final phase
+  if (finalPhase !== toPhase) {
+    throw new Error(
+      `Expected final phase to be '${toPhase}', but found '${finalPhase}'`,
+    );
+  }
+}
+
+/**
+ * Get property value by path with dot notation
+ *
+ * Supports paths like:
+ * - 'phase'
+ * - 'gameState.currentPhase'
+ * - 'flow.phase'
+ *
+ * @param obj - Object to traverse
+ * @param path - Property path
+ * @returns Property value or undefined
+ */
+function getPropertyByPath(obj: any, path: string): any {
+  const parts = path.split(".");
+  let current = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    current = current[part];
+  }
+
+  return current;
+}

package/src/testing/test-player-builder.test.ts

@@ -0,0 +1,132 @@
+import { describe, expect, it } from "bun:test";
+import { createTestPlayers } from "./test-player-builder";
+
+/**
+ * Tests for createTestPlayers - Player builder for tests
+ *
+ * Task 2.1: Write tests for test builders (createTestPlayers)
+ *
+ * Tests verify:
+ * - Creating multiple players with default names
+ * - Creating players with custom names
+ * - Player IDs are unique and properly formatted
+ * - Type safety for Player objects
+ */
+
+describe("createTestPlayers", () => {
+  describe("Basic Functionality", () => {
+    it("should create specified number of players with default names", () => {
+      const players = createTestPlayers(2);
+
+      expect(players).toHaveLength(2);
+      expect(players[0]?.name).toBe("Player 1");
+      expect(players[1]?.name).toBe("Player 2");
+    });
+
+    it("should create players with custom names", () => {
+      const players = createTestPlayers(3, ["Alice", "Bob", "Charlie"]);
+
+      expect(players).toHaveLength(3);
+      expect(players[0]?.name).toBe("Alice");
+      expect(players[1]?.name).toBe("Bob");
+      expect(players[2]?.name).toBe("Charlie");
+    });
+
+    it("should handle partial custom names with defaults for remaining", () => {
+      const players = createTestPlayers(4, ["Alice", "Bob"]);
+
+      expect(players).toHaveLength(4);
+      expect(players[0]?.name).toBe("Alice");
+      expect(players[1]?.name).toBe("Bob");
+      expect(players[2]?.name).toBe("Player 3");
+      expect(players[3]?.name).toBe("Player 4");
+    });
+
+    it("should create single player", () => {
+      const players = createTestPlayers(1);
+
+      expect(players).toHaveLength(1);
+      expect(players[0]?.name).toBe("Player 1");
+    });
+
+    it("should create single player with custom name", () => {
+      const players = createTestPlayers(1, ["Alice"]);
+
+      expect(players).toHaveLength(1);
+      expect(players[0]?.name).toBe("Alice");
+    });
+  });
+
+  describe("Player IDs", () => {
+    it("should generate unique IDs for each player", () => {
+      const players = createTestPlayers(3);
+
+      const ids = players.map((p) => p.id);
+      const uniqueIds = new Set(ids);
+
+      expect(uniqueIds.size).toBe(3);
+    });
+
+    it("should generate properly formatted PlayerId brand", () => {
+      const players = createTestPlayers(2);
+
+      // IDs should be non-empty strings
+      for (const player of players) {
+        expect(player.id).toBeTypeOf("string");
+        expect(player.id.length).toBeGreaterThan(0);
+      }
+    });
+
+    it("should generate deterministic IDs based on index", () => {
+      const players1 = createTestPlayers(2);
+      const players2 = createTestPlayers(2);
+
+      // IDs should be based on player index, so they should match
+      expect(players1[0]?.id).toBe(players2[0]?.id);
+      expect(players1[1]?.id).toBe(players2[1]?.id);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle 0 players by returning empty array", () => {
+      const players = createTestPlayers(0);
+
+      expect(players).toHaveLength(0);
+    });
+
+    it("should handle large number of players", () => {
+      const players = createTestPlayers(10);
+
+      expect(players).toHaveLength(10);
+      expect(players[9]?.name).toBe("Player 10");
+    });
+
+    it("should ignore extra names beyond count", () => {
+      const players = createTestPlayers(2, ["Alice", "Bob", "Charlie"]);
+
+      expect(players).toHaveLength(2);
+      expect(players[0]?.name).toBe("Alice");
+      expect(players[1]?.name).toBe("Bob");
+    });
+  });
+
+  describe("Type Safety", () => {
+    it("should return Player objects with correct structure", () => {
+      const players = createTestPlayers(1);
+
+      expect(players[0]).toHaveProperty("id");
+      expect(players[0]).toHaveProperty("name");
+    });
+
+    it("should have PlayerId branded type", () => {
+      const players = createTestPlayers(1);
+
+      // Runtime check - ID should be a string
+      expect(typeof players[0]?.id).toBe("string");
+
+      // Type-level check happens at compile time
+      // The following would fail TypeScript compilation if Player.id wasn't PlayerId:
+      // const playerId: PlayerId = players[0].id;
+    });
+  });
+});

package/src/testing/test-player-builder.ts

@@ -0,0 +1,46 @@
+import type { Player } from "../game-definition/game-definition";
+import { createPlayerId } from "../types";
+
+/**
+ * Test Player Builder
+ *
+ * Task 2.4: Implement createTestPlayers(count, names?)
+ *
+ * Creates an array of test players with unique IDs and names.
+ * Simplifies test setup by reducing boilerplate player creation.
+ *
+ * Features:
+ * - Generates unique PlayerId for each player
+ * - Uses custom names if provided, otherwise generates default names
+ * - Deterministic IDs based on player index for reproducible tests
+ *
+ * @example
+ * ```typescript
+ * // Create 2 players with default names
+ * const players = createTestPlayers(2);
+ * // [{ id: 'test-p1', name: 'Player 1' }, { id: 'test-p2', name: 'Player 2' }]
+ *
+ * // Create players with custom names
+ * const players = createTestPlayers(3, ['Alice', 'Bob', 'Charlie']);
+ * // [{ id: 'test-p1', name: 'Alice' }, ...]
+ *
+ * // Partial custom names
+ * const players = createTestPlayers(3, ['Alice']);
+ * // [{ id: 'test-p1', name: 'Alice' }, { id: 'test-p2', name: 'Player 2' }, ...]
+ * ```
+ */
+export function createTestPlayers(count: number, names?: string[]): Player[] {
+  const players: Player[] = [];
+
+  for (let i = 0; i < count; i++) {
+    const playerId = createPlayerId(`test-p${i + 1}`);
+    const playerName = names?.[i] ?? `Player ${i + 1}`;
+
+    players.push({
+      id: playerId,
+      name: playerName,
+    });
+  }
+
+  return players;
+}

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

@@ -0,0 +1,356 @@
+import { describe, expect, it } from "bun:test";
+import { RuleEngine } from "../engine/rule-engine";
+import type { GameDefinition } from "../game-definition/game-definition";
+import type { GameMoveDefinitions } from "../game-definition/move-definitions";
+import { createPlayerId, type PlayerId } from "../types";
+import { expectDeterministicReplay } from "./test-replay-assertions";
+
+/**
+ * Test state for replay assertions
+ */
+type ReplayTestState = {
+  players: Array<{
+    id: PlayerId;
+    name: string;
+    score: number;
+  }>;
+  turnNumber: number;
+  randomValues: number[];
+};
+
+type ReplayTestMoves = {
+  addRandom: Record<string, never>;
+  incrementScore: { amount: number };
+};
+
+describe("test-replay-assertions", () => {
+  function createTestEngine(seed?: string) {
+    const moves: GameMoveDefinitions<ReplayTestState, ReplayTestMoves> = {
+      addRandom: {
+        reducer: (draft, context) => {
+          // Use RNG to add random value
+          const value = context.rng?.randomInt(1, 100) ?? 0;
+          draft.randomValues.push(value);
+        },
+      },
+      incrementScore: {
+        reducer: (draft, context) => {
+          const player = draft.players.find((p) => p.id === context.playerId);
+          if (player && context.params?.amount) {
+            player.score += context.params.amount as number;
+          }
+        },
+      },
+    };
+
+    const gameDefinition: GameDefinition<ReplayTestState, ReplayTestMoves> = {
+      name: "Replay Test Game",
+      setup: (players) => ({
+        players: players.map((p) => ({
+          id: p.id as PlayerId,
+          name: p.name || "Player",
+          score: 0,
+        })),
+        turnNumber: 1,
+        randomValues: [],
+      }),
+      moves,
+    };
+
+    const players = [
+      { id: createPlayerId("p1"), name: "Alice" },
+      { id: createPlayerId("p2"), name: "Bob" },
+    ];
+
+    return new RuleEngine(gameDefinition, players, { seed });
+  }
+
+  describe("expectDeterministicReplay", () => {
+    it("should pass when replay produces same state", () => {
+      const engine = createTestEngine("replay-seed");
+
+      // Execute some moves
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 5 },
+      });
+      engine.executeMove("addRandom", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("p2"),
+        params: { amount: 3 },
+      });
+
+      // Should not throw
+      expectDeterministicReplay(engine);
+    });
+
+    it("should verify replay with RNG operations", () => {
+      const engine = createTestEngine("rng-replay-seed");
+
+      // Execute moves that use RNG
+      for (let i = 0; i < 10; i++) {
+        engine.executeMove("addRandom", {
+          playerId: createPlayerId("p1"),
+          params: {},
+        });
+      }
+
+      // Replay should produce exact same random values
+      expectDeterministicReplay(engine);
+    });
+
+    it("should work with complex move sequences", () => {
+      const engine = createTestEngine("complex-replay");
+
+      // Complex sequence
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 1 },
+      });
+      engine.executeMove("addRandom", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("p2"),
+        params: { amount: 2 },
+      });
+      engine.executeMove("addRandom", {
+        playerId: createPlayerId("p2"),
+        params: {},
+      });
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 3 },
+      });
+
+      expectDeterministicReplay(engine);
+    });
+
+    it("should detect non-deterministic behavior", () => {
+      // Create engine with non-deterministic move
+      let callCount = 0;
+      const moves: GameMoveDefinitions<ReplayTestState, ReplayTestMoves> = {
+        addRandom: {
+          reducer: (draft) => {
+            // Add non-deterministic behavior
+            callCount++;
+            draft.randomValues.push(callCount); // Different each time
+          },
+        },
+        incrementScore: {
+          reducer: () => {},
+        },
+      };
+
+      const gameDefinition: GameDefinition<ReplayTestState, ReplayTestMoves> = {
+        name: "Non-deterministic Test",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id as PlayerId,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          turnNumber: 1,
+          randomValues: [],
+        }),
+        moves,
+      };
+
+      const engine = new RuleEngine(
+        gameDefinition,
+        [{ id: createPlayerId("p1"), name: "Alice" }],
+        { seed: "non-deterministic" },
+      );
+
+      engine.executeMove("addRandom", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+
+      // Should throw because replay will have different state
+      expect(() => {
+        expectDeterministicReplay(engine);
+      }).toThrow(/Replay produced different state/);
+    });
+
+    it("should work with empty history", () => {
+      const engine = createTestEngine("empty-seed");
+
+      // No moves executed
+      expectDeterministicReplay(engine);
+    });
+
+    it("should work with single move", () => {
+      const engine = createTestEngine("single-move");
+
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 10 },
+      });
+
+      expectDeterministicReplay(engine);
+    });
+
+    it("should provide helpful error message on mismatch", () => {
+      // Create problematic engine
+      let isReplay = false;
+      const moves: GameMoveDefinitions<ReplayTestState, ReplayTestMoves> = {
+        addRandom: {
+          reducer: (draft, context) => {
+            if (isReplay) {
+              // Different behavior on replay
+              draft.randomValues.push(999);
+            } else {
+              const value = context.rng?.randomInt(1, 100) ?? 0;
+              draft.randomValues.push(value);
+              isReplay = true; // Flag for next call
+            }
+          },
+        },
+        incrementScore: { reducer: () => {} },
+      };
+
+      const gameDefinition: GameDefinition<ReplayTestState, ReplayTestMoves> = {
+        name: "Mismatch Test",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id as PlayerId,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          turnNumber: 1,
+          randomValues: [],
+        }),
+        moves,
+      };
+
+      const engine = new RuleEngine(
+        gameDefinition,
+        [{ id: createPlayerId("p1"), name: "Alice" }],
+        { seed: "mismatch" },
+      );
+
+      engine.executeMove("addRandom", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+
+      expect(() => {
+        expectDeterministicReplay(engine);
+      }).toThrow(/Replay produced different state/);
+    });
+  });
+
+  describe("integration with real game scenarios", () => {
+    it("should verify card shuffling is deterministic", () => {
+      type CardGameState = {
+        players: Array<{ id: PlayerId; name: string }>;
+        deck: string[];
+      };
+
+      type CardMoves = {
+        shuffle: Record<string, never>;
+      };
+
+      const moves: GameMoveDefinitions<CardGameState, CardMoves> = {
+        shuffle: {
+          reducer: (draft, context) => {
+            if (context.rng) {
+              draft.deck = context.rng.shuffle(draft.deck);
+            }
+          },
+        },
+      };
+
+      const gameDefinition: GameDefinition<CardGameState, CardMoves> = {
+        name: "Card Shuffle Test",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id as PlayerId,
+            name: p.name || "Player",
+          })),
+          deck: ["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"],
+        }),
+        moves,
+      };
+
+      const engine = new RuleEngine(
+        gameDefinition,
+        [{ id: createPlayerId("p1"), name: "Alice" }],
+        { seed: "shuffle-test" },
+      );
+
+      // Shuffle multiple times
+      engine.executeMove("shuffle", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+      engine.executeMove("shuffle", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+      engine.executeMove("shuffle", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+
+      // Replay should produce same sequence of shuffles
+      expectDeterministicReplay(engine);
+    });
+
+    it("should verify dice rolls are deterministic", () => {
+      type DiceGameState = {
+        players: Array<{ id: PlayerId; name: string }>;
+        rolls: number[];
+      };
+
+      type DiceMoves = {
+        roll: Record<string, never>;
+      };
+
+      const moves: GameMoveDefinitions<DiceGameState, DiceMoves> = {
+        roll: {
+          reducer: (draft, context) => {
+            if (context.rng) {
+              const roll = context.rng.rollDice(20) as number;
+              draft.rolls.push(roll);
+            }
+          },
+        },
+      };
+
+      const gameDefinition: GameDefinition<DiceGameState, DiceMoves> = {
+        name: "Dice Roll Test",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id as PlayerId,
+            name: p.name || "Player",
+          })),
+          rolls: [],
+        }),
+        moves,
+      };
+
+      const engine = new RuleEngine(
+        gameDefinition,
+        [{ id: createPlayerId("p1"), name: "Alice" }],
+        { seed: "dice-test" },
+      );
+
+      // Roll dice multiple times
+      for (let i = 0; i < 20; i++) {
+        engine.executeMove("roll", {
+          playerId: createPlayerId("p1"),
+          params: {},
+        });
+      }
+
+      // Replay should produce same dice rolls
+      expectDeterministicReplay(engine);
+    });
+  });
+});