@drmxrcy/tcg-core 0.0.0-202602060542

package/src/testing/test-context-factory.ts

@@ -0,0 +1,187 @@
+/**
+ * Test Context Factory
+ *
+ * Utilities for creating MoveContext objects in tests.
+ * Provides mock implementations of engine services for unit testing.
+ */
+
+import type { HistoryOperations } from "../history/history-operations";
+import type { MoveContext, MoveContextInput } from "../moves/move-system";
+import type { CardOperations } from "../operations/card-operations";
+import type { CounterOperations } from "../operations/counter-operations";
+import type { GameOperations } from "../operations/game-operations";
+import type { ZoneOperations } from "../operations/zone-operations";
+import { SeededRNG } from "../rng/seeded-rng";
+import type { CardId, PlayerId, ZoneId } from "../types";
+
+/**
+ * Create a mock MoveContext for testing
+ *
+ * Builds a full MoveContext with mock implementations of engine services.
+ * Useful for unit testing reducers and conditions without a full engine.
+ *
+ * @param input - Partial context input
+ * @param options - Optional mock implementations
+ * @returns Full MoveContext with mocks
+ *
+ * @example
+ * ```typescript
+ * const context = createMockContext({
+ *   playerId: 'p1',
+ *   params: { cardId: 'card-123' }
+ * });
+ *
+ * // Use in reducer test
+ * const reducer: MoveReducer<GameState> = (draft, ctx) => {
+ *   // ctx has full MoveContext type
+ * };
+ * reducer(draft, context);
+ * ```
+ */
+export function createMockContext<TParams = any>(
+  input: MoveContextInput<TParams>,
+  options?: {
+    rng?: SeededRNG;
+    zones?: Partial<ZoneOperations>;
+    cards?: Partial<CardOperations<any>>;
+    game?: Partial<GameOperations>;
+    counters?: Partial<CounterOperations>;
+    registry?: any;
+    flow?: {
+      currentPhase?: string;
+      currentSegment?: string;
+      turn: number;
+      currentPlayer: PlayerId;
+      isFirstTurn: boolean;
+      endPhase?: () => void;
+      endSegment?: () => void;
+      endTurn?: () => void;
+    };
+    endGame?: (result: {
+      winner?: PlayerId;
+      reason: string;
+      metadata?: Record<string, unknown>;
+    }) => void;
+    trackers?: {
+      check(name: string, playerId?: PlayerId): boolean;
+      mark(name: string, playerId?: PlayerId): void;
+      unmark(name: string, playerId?: PlayerId): void;
+    };
+    history?: Partial<HistoryOperations>;
+  },
+): MoveContext<TParams> {
+  const mockZones: ZoneOperations = {
+    moveCard: () => {},
+    getCardsInZone: () => [],
+    shuffleZone: () => {},
+    getCardZone: () => undefined,
+    drawCards: () => [],
+    mulligan: () => {},
+    bulkMove: () => [],
+    createDeck: () => [],
+    ...options?.zones,
+  };
+
+  const mockCards: CardOperations<any> = {
+    getCardMeta: () => ({}),
+    updateCardMeta: () => {},
+    setCardMeta: () => {},
+    getCardOwner: () => undefined as any,
+    queryCards: () => [],
+    ...options?.cards,
+  };
+
+  const mockGame: GameOperations = {
+    setOTP: () => {},
+    getOTP: () => undefined,
+    setChoosingFirstPlayer: () => {},
+    getChoosingFirstPlayer: () => undefined,
+    setPendingMulligan: () => {},
+    getPendingMulligan: () => [],
+    addPendingMulligan: () => {},
+    removePendingMulligan: () => {},
+    ...options?.game,
+  };
+
+  const mockCounters: CounterOperations = {
+    setFlag: () => {},
+    getFlag: () => false,
+    addCounter: () => {},
+    removeCounter: () => {},
+    getCounter: () => 0,
+    clearCounter: () => {},
+    clearAllCounters: () => {},
+    getCardsWithFlag: () => [],
+    getCardsWithCounter: () => [],
+    ...options?.counters,
+  };
+
+  return {
+    ...input,
+    rng: options?.rng || new SeededRNG("test-seed"),
+    zones: mockZones,
+    cards: mockCards,
+    game: mockGame,
+    counters: mockCounters,
+    registry: options?.registry,
+    flow: options?.flow
+      ? {
+          ...options.flow,
+          endPhase: options.flow.endPhase || (() => {}),
+          endSegment: options.flow.endSegment || (() => {}),
+          endTurn: options.flow.endTurn || (() => {}),
+        }
+      : undefined,
+    endGame: options?.endGame || (() => {}),
+    trackers: options?.trackers || {
+      check: () => false,
+      mark: () => {},
+      unmark: () => {},
+    },
+    history: {
+      log: () => {},
+      ...options?.history,
+    },
+  };
+}
+
+/**
+ * Create a mock CardOperations for testing
+ *
+ * @param overrides - Optional method overrides
+ * @returns Mock CardOperations
+ */
+export function createMockCardOperations<TCardMeta = any>(
+  overrides?: Partial<CardOperations<TCardMeta>>,
+): CardOperations<TCardMeta> {
+  return {
+    getCardMeta: () => ({}) as TCardMeta,
+    updateCardMeta: () => {},
+    setCardMeta: () => {},
+    getCardOwner: () => undefined as any,
+    queryCards: () => [],
+    ...overrides,
+  };
+}
+
+/**
+ * Create a mock ZoneOperations for testing
+ *
+ * @param overrides - Optional method overrides
+ * @returns Mock ZoneOperations
+ */
+export function createMockZoneOperations(
+  overrides?: Partial<ZoneOperations>,
+): ZoneOperations {
+  return {
+    moveCard: () => {},
+    getCardsInZone: () => [],
+    shuffleZone: () => {},
+    getCardZone: () => undefined,
+    drawCards: () => [],
+    mulligan: () => {},
+    bulkMove: () => [],
+    createDeck: () => [],
+    ...overrides,
+  };
+}

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

@@ -0,0 +1,262 @@
+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 { expectGameEnd, expectGameNotEnded } from "./test-end-assertions";
+
+/**
+ * Test state for end assertions
+ */
+type EndTestState = {
+  players: Array<{
+    id: PlayerId;
+    name: string;
+    health: number;
+  }>;
+  turnNumber: number;
+  winner?: PlayerId;
+};
+
+type EndTestMoves = {
+  damagePlayer: { targetId: PlayerId; amount: number };
+  setWinner: { winnerId: PlayerId };
+};
+
+describe("test-end-assertions", () => {
+  function createTestEngine() {
+    const moves: GameMoveDefinitions<EndTestState, EndTestMoves> = {
+      damagePlayer: {
+        reducer: (draft, context) => {
+          if (context.params?.targetId && context.params?.amount) {
+            const target = draft.players.find(
+              (p) => p.id === context.params?.targetId,
+            );
+            if (target) {
+              target.health -= context.params.amount as number;
+              if (target.health <= 0) {
+                // Set winner to the other player
+                const winner = draft.players.find(
+                  (p) => p.id !== context.params?.targetId,
+                );
+                if (winner) {
+                  draft.winner = winner.id;
+                }
+              }
+            }
+          }
+        },
+      },
+      setWinner: {
+        reducer: (draft, context) => {
+          if (context.params?.winnerId) {
+            draft.winner = context.params.winnerId as PlayerId;
+          }
+        },
+      },
+    };
+
+    const gameDefinition: GameDefinition<EndTestState, EndTestMoves> = {
+      name: "End Test Game",
+      setup: (players) => ({
+        players: players.map((p) => ({
+          id: p.id as PlayerId,
+          name: p.name || "Player",
+          health: 10,
+        })),
+        turnNumber: 1,
+      }),
+      moves,
+      endIf: (state) => {
+        if (state.winner) {
+          return {
+            winner: state.winner,
+            reason: "Player eliminated",
+          };
+        }
+        return undefined;
+      },
+    };
+
+    const players = [
+      { id: createPlayerId("p1"), name: "Alice" },
+      { id: createPlayerId("p2"), name: "Bob" },
+    ];
+
+    return new RuleEngine(gameDefinition, players);
+  }
+
+  describe("expectGameEnd", () => {
+    it("should pass when game ends with expected winner", () => {
+      const engine = createTestEngine();
+
+      // Set winner
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      // Should not throw
+      expectGameEnd(engine, createPlayerId("p1"));
+    });
+
+    it("should throw when game has not ended", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectGameEnd(engine, createPlayerId("p1"));
+      }).toThrow(/Expected game to have ended/);
+    });
+
+    it("should throw when winner does not match", () => {
+      const engine = createTestEngine();
+
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      expect(() => {
+        expectGameEnd(engine, createPlayerId("p2"));
+      }).toThrow(/Expected winner to be 'p2'/);
+    });
+
+    it("should work without specifying winner", () => {
+      const engine = createTestEngine();
+
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      // Should not throw - just checks that game ended
+      expectGameEnd(engine);
+    });
+
+    it("should optionally check reason", () => {
+      const engine = createTestEngine();
+
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      // Should not throw
+      expectGameEnd(engine, createPlayerId("p1"), "Player eliminated");
+    });
+
+    it("should throw when reason does not match", () => {
+      const engine = createTestEngine();
+
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      expect(() => {
+        expectGameEnd(engine, createPlayerId("p1"), "Wrong reason");
+      }).toThrow(/Expected reason to be 'Wrong reason'/);
+    });
+
+    it("should return game end result", () => {
+      const engine = createTestEngine();
+
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      const result = expectGameEnd(engine);
+      expect(result.winner).toBe(createPlayerId("p1"));
+      expect(result.reason).toBe("Player eliminated");
+    });
+
+    it("should work in realistic game scenario", () => {
+      const engine = createTestEngine();
+
+      // Damage player 2 until they lose
+      engine.executeMove("damagePlayer", {
+        playerId: createPlayerId("p1"),
+        params: { targetId: createPlayerId("p2"), amount: 5 },
+      });
+
+      expectGameNotEnded(engine); // Game should still be ongoing
+
+      engine.executeMove("damagePlayer", {
+        playerId: createPlayerId("p1"),
+        params: { targetId: createPlayerId("p2"), amount: 5 },
+      });
+
+      // Game should have ended
+      expectGameEnd(engine, createPlayerId("p1"), "Player eliminated");
+    });
+  });
+
+  describe("expectGameNotEnded", () => {
+    it("should pass when game has not ended", () => {
+      const engine = createTestEngine();
+
+      // Should not throw
+      expectGameNotEnded(engine);
+    });
+
+    it("should throw when game has ended", () => {
+      const engine = createTestEngine();
+
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      expect(() => {
+        expectGameNotEnded(engine);
+      }).toThrow(/Expected game to still be ongoing/);
+    });
+
+    it("should provide helpful error message with end details", () => {
+      const engine = createTestEngine();
+
+      engine.executeMove("setWinner", {
+        playerId: createPlayerId("p1"),
+        params: { winnerId: createPlayerId("p1") },
+      });
+
+      expect(() => {
+        expectGameNotEnded(engine);
+      }).toThrow(/"winner":"p1"/);
+    });
+  });
+
+  describe("integration", () => {
+    it("should work together to test game flow", () => {
+      const engine = createTestEngine();
+
+      // Initially game is not ended
+      expectGameNotEnded(engine);
+
+      // Do some damage but not enough to end game
+      engine.executeMove("damagePlayer", {
+        playerId: createPlayerId("p1"),
+        params: { targetId: createPlayerId("p2"), amount: 3 },
+      });
+
+      expectGameNotEnded(engine);
+
+      // More damage
+      engine.executeMove("damagePlayer", {
+        playerId: createPlayerId("p1"),
+        params: { targetId: createPlayerId("p2"), amount: 3 },
+      });
+
+      expectGameNotEnded(engine);
+
+      // Final damage should end game
+      engine.executeMove("damagePlayer", {
+        playerId: createPlayerId("p1"),
+        params: { targetId: createPlayerId("p2"), amount: 4 },
+      });
+
+      expectGameEnd(engine, createPlayerId("p1"));
+    });
+  });
+});

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

@@ -0,0 +1,95 @@
+import type { RuleEngine } from "../engine/rule-engine";
+import type { GameEndResult } from "../game-definition/game-definition";
+
+/**
+ * Test End Assertions
+ *
+ * Assertion helpers for testing game end conditions
+ */
+
+/**
+ * Assert that the game has ended
+ *
+ * Verifies that checkGameEnd returns a truthy value.
+ * Optionally checks the winner and/or reason.
+ *
+ * @param engine - Rule engine instance
+ * @param expectedWinner - Optional expected winner
+ * @param expectedReason - Optional expected reason
+ * @returns Game end result
+ * @throws Error if game hasn't ended or end result doesn't match expectations
+ *
+ * @example
+ * ```typescript
+ * // Check that game ended
+ * expectGameEnd(engine);
+ *
+ * // Check specific winner
+ * expectGameEnd(engine, 'player1');
+ *
+ * // Check winner and reason
+ * expectGameEnd(engine, 'player1', 'Opponent eliminated');
+ * ```
+ */
+export function expectGameEnd<TState, TMoves extends Record<string, any>>(
+  engine: RuleEngine<TState, TMoves>,
+  expectedWinner?: string,
+  expectedReason?: string,
+): GameEndResult {
+  const endResult = engine.checkGameEnd();
+
+  if (!endResult) {
+    throw new Error(
+      "Expected game to have ended, but checkGameEnd() returned undefined",
+    );
+  }
+
+  // Check winner if specified
+  if (expectedWinner !== undefined && endResult.winner !== expectedWinner) {
+    throw new Error(
+      `Expected winner to be '${expectedWinner}', but got '${endResult.winner}'`,
+    );
+  }
+
+  // Check reason if specified
+  if (expectedReason !== undefined && endResult.reason !== expectedReason) {
+    throw new Error(
+      `Expected reason to be '${expectedReason}', but got '${endResult.reason}'`,
+    );
+  }
+
+  return endResult;
+}
+
+/**
+ * Assert that the game has not ended
+ *
+ * Verifies that checkGameEnd returns undefined/falsy.
+ * Useful for testing that intermediate game states don't trigger end conditions.
+ *
+ * @param engine - Rule engine instance
+ * @throws Error if game has ended
+ *
+ * @example
+ * ```typescript
+ * // Verify game is still ongoing
+ * expectGameNotEnded(engine);
+ *
+ * // Do some moves
+ * engine.executeMove('attack', { ... });
+ *
+ * // Verify game still hasn't ended
+ * expectGameNotEnded(engine);
+ * ```
+ */
+export function expectGameNotEnded<TState, TMoves extends Record<string, any>>(
+  engine: RuleEngine<TState, TMoves>,
+): void {
+  const endResult = engine.checkGameEnd();
+
+  if (endResult) {
+    throw new Error(
+      `Expected game to still be ongoing, but it ended with: ${JSON.stringify(endResult)}`,
+    );
+  }
+}