@drmxrcy/tcg-core 0.0.0-202602060542

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

@@ -0,0 +1,389 @@
+import { describe, expect, it } from "bun:test";
+import type { GameDefinition } from "../game-definition/game-definition";
+import type { GameMoveDefinitions } from "../game-definition/move-definitions";
+import { createPlayerId } from "../types";
+import { createTestEngine } from "./test-engine-builder";
+import { createTestPlayers } from "./test-player-builder";
+
+/**
+ * Tests for createTestEngine - Engine builder for tests
+ *
+ * Task 2.1: Write tests for test builders (createTestEngine)
+ *
+ * Tests verify:
+ * - Creating engine with minimal game definition
+ * - Creating engine with custom players
+ * - Creating engine with options (seed)
+ * - Default player generation
+ * - Engine is properly initialized and functional
+ */
+
+type SimpleGameState = {
+  players: Array<{ id: string; name: string; score: number }>;
+  currentPlayer: number;
+};
+
+type SimpleMoves = {
+  incrementScore: Record<string, never>;
+  pass: Record<string, never>;
+};
+
+describe("createTestEngine", () => {
+  describe("Basic Functionality", () => {
+    it("should create engine with minimal game definition and default players", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: {
+          reducer: (draft: SimpleGameState) => {
+            const player = draft.players[draft.currentPlayer];
+            if (player) {
+              player.score += 1;
+            }
+          },
+        },
+        pass: {
+          reducer: (draft: SimpleGameState) => {
+            draft.currentPlayer =
+              (draft.currentPlayer + 1) % draft.players.length;
+          },
+        },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition);
+
+      // Engine should be initialized
+      expect(engine).toBeDefined();
+
+      // Should have default 2 players
+      const state = engine.getState();
+      expect(state.players).toHaveLength(2);
+      expect(state.players[0]?.name).toBe("Player 1");
+      expect(state.players[1]?.name).toBe("Player 2");
+    });
+
+    it("should create engine with custom players", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: { reducer: () => {} },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const customPlayers = createTestPlayers(3, ["Alice", "Bob", "Charlie"]);
+      const engine = createTestEngine(definition, customPlayers);
+
+      const state = engine.getState();
+      expect(state.players).toHaveLength(3);
+      expect(state.players[0]?.name).toBe("Alice");
+      expect(state.players[1]?.name).toBe("Bob");
+      expect(state.players[2]?.name).toBe("Charlie");
+    });
+
+    it("should create engine with seed option for deterministic RNG", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: { reducer: () => {} },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition, undefined, {
+        seed: "test-seed",
+      });
+
+      // Engine should have seeded RNG
+      expect(engine.getRNG()).toBeDefined();
+      expect(engine.getRNG().getSeed()).toBe("test-seed");
+    });
+  });
+
+  describe("Engine Functionality", () => {
+    it("should create functional engine that can execute moves", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: {
+          reducer: (draft: SimpleGameState) => {
+            const player = draft.players[draft.currentPlayer];
+            if (player) {
+              player.score += 1;
+            }
+          },
+        },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition);
+
+      const result = engine.executeMove("incrementScore", {
+        playerId: createPlayerId("test-p1"),
+        params: {},
+      });
+
+      expect(result.success).toBe(true);
+
+      const state = engine.getState();
+      expect(state.players[0]?.score).toBe(1);
+    });
+
+    it("should create engine with history tracking", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: {
+          reducer: (draft: SimpleGameState) => {
+            const player = draft.players[draft.currentPlayer];
+            if (player) {
+              player.score += 1;
+            }
+          },
+        },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition);
+
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("test-p1"),
+        params: {},
+      });
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("test-p1"),
+        params: {},
+      });
+
+      const history = engine.getHistory();
+      expect(history.length).toBe(2);
+    });
+
+    it("should create engine that supports undo/redo", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: {
+          reducer: (draft: SimpleGameState) => {
+            const player = draft.players[draft.currentPlayer];
+            if (player) {
+              player.score += 1;
+            }
+          },
+        },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition);
+
+      engine.executeMove("incrementScore", {
+        playerId: createPlayerId("test-p1"),
+        params: {},
+      });
+      expect(engine.getState().players[0]?.score).toBe(1);
+
+      engine.undo();
+      expect(engine.getState().players[0]?.score).toBe(0);
+
+      engine.redo();
+      expect(engine.getState().players[0]?.score).toBe(1);
+    });
+  });
+
+  describe("Options", () => {
+    it("should accept undefined players and use defaults", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: { reducer: () => {} },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition, undefined);
+
+      const state = engine.getState();
+      expect(state.players).toHaveLength(2);
+    });
+
+    it("should accept undefined options", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: { reducer: () => {} },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition, undefined, undefined);
+
+      expect(engine).toBeDefined();
+      expect(engine.getRNG()).toBeDefined();
+    });
+
+    it("should merge custom options with defaults", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: { reducer: () => {} },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const engine = createTestEngine(definition, undefined, {
+        seed: "custom-seed",
+      });
+
+      expect(engine.getRNG().getSeed()).toBe("custom-seed");
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should create engine with single player", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: { reducer: () => {} },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const singlePlayer = createTestPlayers(1, ["Solo"]);
+      const engine = createTestEngine(definition, singlePlayer);
+
+      const state = engine.getState();
+      expect(state.players).toHaveLength(1);
+      expect(state.players[0]?.name).toBe("Solo");
+    });
+
+    it("should create engine with many players", () => {
+      const moves: GameMoveDefinitions<SimpleGameState, SimpleMoves> = {
+        incrementScore: { reducer: () => {} },
+        pass: { reducer: () => {} },
+      };
+
+      const definition: GameDefinition<SimpleGameState, SimpleMoves> = {
+        name: "Test Game",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id,
+            name: p.name || "Player",
+            score: 0,
+          })),
+          currentPlayer: 0,
+        }),
+        moves,
+      };
+
+      const manyPlayers = createTestPlayers(6);
+      const engine = createTestEngine(definition, manyPlayers);
+
+      const state = engine.getState();
+      expect(state.players).toHaveLength(6);
+    });
+  });
+});

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

@@ -0,0 +1,46 @@
+import { RuleEngine, type RuleEngineOptions } from "../engine/rule-engine";
+import type {
+  GameDefinition,
+  Player,
+} from "../game-definition/game-definition";
+import { createTestPlayers } from "./test-player-builder";
+
+/**
+ * Test Engine Builder
+ *
+ * Task 2.3: Implement createTestEngine(definition, players?, options?)
+ *
+ * Creates a fully initialized RuleEngine for testing.
+ * Simplifies test setup by providing sensible defaults for players and options.
+ *
+ * Features:
+ * - Default 2 players if not provided
+ * - Optional seed for deterministic testing
+ * - Returns ready-to-use engine with initialized state
+ *
+ * @example
+ * ```typescript
+ * // Create engine with defaults (2 players)
+ * const engine = createTestEngine(gameDefinition);
+ *
+ * // Create engine with custom players
+ * const players = createTestPlayers(4, ['Alice', 'Bob', 'Charlie', 'Dave']);
+ * const engine = createTestEngine(gameDefinition, players);
+ *
+ * // Create engine with seed for deterministic tests
+ * const engine = createTestEngine(gameDefinition, undefined, {
+ *   seed: 'test-seed-123'
+ * });
+ * ```
+ */
+export function createTestEngine<TState, TMoves extends Record<string, any>>(
+  definition: GameDefinition<TState, TMoves>,
+  players?: Player[],
+  options?: RuleEngineOptions,
+): RuleEngine<TState, TMoves> {
+  // Use provided players or create default 2 players
+  const enginePlayers = players ?? createTestPlayers(2);
+
+  // Create and return engine with options
+  return new RuleEngine(definition, enginePlayers, options);
+}

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

@@ -0,0 +1,284 @@
+import { describe, expect, it } from "bun:test";
+import { RuleEngine } from "../engine/rule-engine";
+import type { FlowDefinition } from "../flow/flow-definition";
+import type { GameDefinition } from "../game-definition/game-definition";
+import type { GameMoveDefinitions } from "../game-definition/move-definitions";
+import { createPlayerId, type PlayerId } from "../types";
+import { expectPhaseTransition } from "./test-flow-assertions";
+
+/**
+ * Test state for flow assertions
+ */
+type FlowTestState = {
+  players: Array<{
+    id: PlayerId;
+    name: string;
+  }>;
+  phase: "draw" | "main" | "end";
+  turnNumber: number;
+};
+
+type FlowTestMoves = {
+  nextPhase: Record<string, never>;
+};
+
+describe("test-flow-assertions", () => {
+  function createTestEngine() {
+    const moves: GameMoveDefinitions<FlowTestState, FlowTestMoves> = {
+      nextPhase: {
+        reducer: (draft) => {
+          // Transition through phases
+          if (draft.phase === "draw") {
+            draft.phase = "main";
+          } else if (draft.phase === "main") {
+            draft.phase = "end";
+          } else if (draft.phase === "end") {
+            draft.phase = "draw";
+            draft.turnNumber += 1;
+          }
+        },
+      },
+    };
+
+    const flow: FlowDefinition<FlowTestState> = {
+      turn: {
+        onBegin: (context) => {
+          context.state.phase = "draw";
+        },
+        phases: {
+          draw: {
+            order: 0,
+            next: "main",
+          },
+          main: {
+            order: 1,
+            next: "end",
+          },
+          end: {
+            order: 2,
+            next: undefined,
+          },
+        },
+      },
+    };
+
+    const gameDefinition: GameDefinition<FlowTestState, FlowTestMoves> = {
+      name: "Flow Test Game",
+      setup: (players) => ({
+        players: players.map((p) => ({
+          id: p.id as PlayerId,
+          name: p.name || "Player",
+        })),
+        phase: "draw" as const,
+        turnNumber: 1,
+      }),
+      moves,
+      flow,
+    };
+
+    const players = [
+      { id: createPlayerId("p1"), name: "Alice" },
+      { id: createPlayerId("p2"), name: "Bob" },
+    ];
+
+    return new RuleEngine(gameDefinition, players);
+  }
+
+  describe("expectPhaseTransition", () => {
+    it("should pass when phase transitions correctly", () => {
+      const engine = createTestEngine();
+
+      // Should not throw
+      expectPhaseTransition(
+        engine,
+        "nextPhase",
+        { playerId: createPlayerId("p1"), params: {} },
+        "draw",
+        "main",
+      );
+    });
+
+    it("should throw when initial phase does not match", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectPhaseTransition(
+          engine,
+          "nextPhase",
+          { playerId: createPlayerId("p1"), params: {} },
+          "main", // Wrong initial phase
+          "end",
+        );
+      }).toThrow(/Expected initial phase to be 'main'/);
+    });
+
+    it("should throw when final phase does not match", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectPhaseTransition(
+          engine,
+          "nextPhase",
+          { playerId: createPlayerId("p1"), params: {} },
+          "draw",
+          "end", // Wrong final phase (should be 'main')
+        );
+      }).toThrow(/Expected final phase to be 'end'/);
+    });
+
+    it("should work with multiple transitions", () => {
+      const engine = createTestEngine();
+
+      expectPhaseTransition(
+        engine,
+        "nextPhase",
+        { playerId: createPlayerId("p1"), params: {} },
+        "draw",
+        "main",
+      );
+
+      expectPhaseTransition(
+        engine,
+        "nextPhase",
+        { playerId: createPlayerId("p1"), params: {} },
+        "main",
+        "end",
+      );
+
+      expectPhaseTransition(
+        engine,
+        "nextPhase",
+        { playerId: createPlayerId("p1"), params: {} },
+        "end",
+        "draw",
+      );
+    });
+
+    it("should handle move failures", () => {
+      const _engine = createTestEngine();
+
+      // Create a move that will fail
+      const moves: GameMoveDefinitions<FlowTestState, FlowTestMoves> = {
+        nextPhase: {
+          condition: () => false, // Always fails
+          reducer: () => {},
+        },
+      };
+
+      const flow: FlowDefinition<FlowTestState> = {
+        turn: {
+          phases: {
+            draw: { order: 0, next: "main" },
+            main: { order: 1, next: undefined },
+          },
+        },
+      };
+
+      const gameDefinition: GameDefinition<FlowTestState, FlowTestMoves> = {
+        name: "Failing Flow Test",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id as PlayerId,
+            name: p.name || "Player",
+          })),
+          phase: "draw" as const,
+          turnNumber: 1,
+        }),
+        moves,
+        flow,
+      };
+
+      const failEngine = new RuleEngine(gameDefinition, [
+        { id: createPlayerId("p1"), name: "Alice" },
+      ]);
+
+      expect(() => {
+        expectPhaseTransition(
+          failEngine,
+          "nextPhase",
+          { playerId: createPlayerId("p1"), params: {} },
+          "draw",
+          "main",
+        );
+      }).toThrow(/Move failed/);
+    });
+
+    it("should work with FlowManager integration", () => {
+      const engine = createTestEngine();
+      const flowManager = engine.getFlowManager();
+
+      expect(flowManager).toBeDefined();
+      expect(flowManager?.getCurrentPhase()).toBe("draw");
+
+      // Transition phase
+      expectPhaseTransition(
+        engine,
+        "nextPhase",
+        { playerId: createPlayerId("p1"), params: {} },
+        "draw",
+        "main",
+      );
+
+      // Note: FlowManager tracks its own phase state separate from game state
+      // This test verifies that expectPhaseTransition works with engines that have FlowManager
+      const state = engine.getState();
+      expect(state.phase).toBe("main");
+    });
+
+    it("should accept phase path for nested state", () => {
+      // Create engine with nested phase in state
+      type NestedFlowState = {
+        players: Array<{ id: PlayerId; name: string }>;
+        gameState: {
+          currentPhase: "start" | "middle" | "end";
+        };
+        turnNumber: number;
+      };
+
+      type NestedMoves = {
+        advance: Record<string, never>;
+      };
+
+      const moves: GameMoveDefinitions<NestedFlowState, NestedMoves> = {
+        advance: {
+          reducer: (draft) => {
+            if (draft.gameState.currentPhase === "start") {
+              draft.gameState.currentPhase = "middle";
+            } else if (draft.gameState.currentPhase === "middle") {
+              draft.gameState.currentPhase = "end";
+            }
+          },
+        },
+      };
+
+      const gameDefinition: GameDefinition<NestedFlowState, NestedMoves> = {
+        name: "Nested Flow Test",
+        setup: (players) => ({
+          players: players.map((p) => ({
+            id: p.id as PlayerId,
+            name: p.name || "Player",
+          })),
+          gameState: {
+            currentPhase: "start" as const,
+          },
+          turnNumber: 1,
+        }),
+        moves,
+      };
+
+      const nestedEngine = new RuleEngine(gameDefinition, [
+        { id: createPlayerId("p1"), name: "Alice" },
+      ]);
+
+      // Should work with custom phase path
+      expectPhaseTransition(
+        nestedEngine,
+        "advance",
+        { playerId: createPlayerId("p1"), params: {} },
+        "start",
+        "middle",
+        "gameState.currentPhase",
+      );
+    });
+  });
+});