@drmxrcy/tcg-core 0.0.0-202602060542

package/src/testing/__tests__/testing-utilities-integration.test.ts

@@ -0,0 +1,161 @@
+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 {
+  createTestCards,
+  createTestDeck,
+  createTestHand,
+  expectDeterministicReplay,
+  expectGameEnd,
+  expectGameNotEnded,
+  expectMoveFailure,
+  expectMoveSuccess,
+  expectPhaseTransition,
+  expectStateProperty,
+  withSeed,
+} from "../index";
+
+/**
+ * Integration test demonstrating @drmxrcy/tcg-core/testing utilities
+ */
+
+type TestGameState = {
+  players: Array<{
+    id: PlayerId;
+    name: string;
+    health: number;
+    hand: string[];
+  }>;
+  phase: "draw" | "main";
+  winner?: PlayerId;
+};
+
+type TestGameMoves = {
+  drawCard: Record<string, never>;
+  attack: Record<string, never>;
+  endPhase: Record<string, never>;
+};
+
+describe("Testing Utilities Integration", () => {
+  it("demonstrates testing utilities workflow", () => {
+    // 1. Test factories
+    const cards = createTestCards(5);
+    expect(cards.length).toBe(5);
+
+    const deck = createTestDeck([], createPlayerId("p1"));
+    expect(deck.config.visibility).toBe("secret");
+
+    const hand = createTestHand([], createPlayerId("p1"));
+    expect(hand.config.visibility).toBe("private");
+
+    // 2. Test RNG
+    const shuffled1 = withSeed("test", (rng) => rng.shuffle([1, 2, 3]));
+    const shuffled2 = withSeed("test", (rng) => rng.shuffle([1, 2, 3]));
+    expect(shuffled1).toEqual(shuffled2);
+
+    // 3. Test game
+    const moves: GameMoveDefinitions<TestGameState, TestGameMoves> = {
+      drawCard: {
+        condition: (state) => state.phase === "draw",
+        reducer: (draft) => {
+          const player = draft.players[0];
+          if (player) {
+            player.hand.push("card");
+          }
+        },
+      },
+      attack: {
+        condition: (state) => state.phase === "main",
+        reducer: (draft) => {
+          const target = draft.players[1];
+          if (target) {
+            target.health -= 1;
+            if (target.health <= 0) {
+              draft.winner = draft.players[0]?.id;
+            }
+          }
+        },
+      },
+      endPhase: {
+        reducer: (draft) => {
+          draft.phase = draft.phase === "draw" ? "main" : "draw";
+        },
+      },
+    };
+
+    const gameDefinition: GameDefinition<TestGameState, TestGameMoves> = {
+      name: "Test Game",
+      setup: (players) => ({
+        players: players.map((p) => ({
+          id: p.id as PlayerId,
+          name: p.name || "Player",
+          health: 3,
+          hand: [],
+        })),
+        phase: "draw" as const,
+      }),
+      moves,
+      endIf: (state) => {
+        if (state.winner) {
+          return { winner: state.winner, reason: "Victory" };
+        }
+        return undefined;
+      },
+    };
+
+    const engine = new RuleEngine(
+      gameDefinition,
+      [
+        { id: createPlayerId("p1"), name: "Alice" },
+        { id: createPlayerId("p2"), name: "Bob" },
+      ],
+      { seed: "test-seed" },
+    );
+
+    // 4. Test assertions
+    expectStateProperty(engine, "phase", "draw");
+    expectStateProperty(engine, "players[0].health", 3);
+
+    expectMoveSuccess(engine, "drawCard", {
+      playerId: createPlayerId("p1"),
+      params: {},
+    });
+    expectStateProperty(engine, "players[0].hand.length", 1);
+
+    expectPhaseTransition(
+      engine,
+      "endPhase",
+      { playerId: createPlayerId("p1"), params: {} },
+      "draw",
+      "main",
+    );
+
+    expectMoveFailure(
+      engine,
+      "drawCard",
+      { playerId: createPlayerId("p1"), params: {} },
+      "CONDITION_FAILED",
+    );
+
+    expectGameNotEnded(engine);
+
+    // Attack to end game
+    expectMoveSuccess(engine, "attack", {
+      playerId: createPlayerId("p1"),
+      params: {},
+    });
+    expectMoveSuccess(engine, "attack", {
+      playerId: createPlayerId("p1"),
+      params: {},
+    });
+    expectMoveSuccess(engine, "attack", {
+      playerId: createPlayerId("p1"),
+      params: {},
+    });
+
+    expectGameEnd(engine, createPlayerId("p1"));
+    expectDeterministicReplay(engine);
+  });
+});

package/src/testing/index.ts

@@ -0,0 +1,88 @@
+/**
+ * @drmxrcy/tcg-core/testing
+ *
+ * Testing utilities for game engine development
+ *
+ * Provides assertions, factories, and helpers for:
+ * - Move execution testing
+ * - State verification
+ * - Flow and phase transitions
+ * - Game end conditions
+ * - Card and zone creation
+ * - Deterministic RNG testing
+ * - Replay verification
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   expectMoveSuccess,
+ *   expectStateProperty,
+ *   createTestCard,
+ *   createTestDeck,
+ *   withSeed,
+ *   expectDeterministicReplay
+ * } from '@drmxrcy/tcg-core/testing';
+ *
+ * // Test move execution
+ * expectMoveSuccess(engine, 'playCard', {
+ *   playerId: 'p1',
+ *   data: { cardId: 'card-123' }
+ * });
+ *
+ * // Verify state
+ * expectStateProperty(engine, 'players[0].score', 10);
+ *
+ * // Create test data
+ * const card = createTestCard({ type: 'creature', basePower: 3 });
+ * const deck = createTestDeck(['card1', 'card2', 'card3'], 'player1');
+ *
+ * // Test with deterministic RNG
+ * const result = withSeed('test-seed', (rng) => {
+ *   return rng.shuffle([1, 2, 3, 4, 5]);
+ * });
+ *
+ * // Verify deterministic replay
+ * expectDeterministicReplay(engine);
+ * ```
+ *
+ * @module @drmxrcy/tcg-core/testing
+ */
+
+// Move assertions
+export {
+  expectMoveFailure,
+  expectMoveSuccess,
+  expectStateProperty,
+} from "./test-assertions";
+// Card factory
+export {
+  createTestCard,
+  createTestCards,
+  resetCardCounter,
+} from "./test-card-factory";
+
+// End assertions
+export { expectGameEnd, expectGameNotEnded } from "./test-end-assertions";
+// Flow assertions
+export { expectPhaseTransition } from "./test-flow-assertions";
+// Replay assertions
+export { expectDeterministicReplay } from "./test-replay-assertions";
+
+// RNG helpers
+export {
+  createDeterministicRNG,
+  createMultipleRNGs,
+  createPredictableSequence,
+  expectDeterministicBehavior,
+  testWithMultipleSeeds,
+  withSeed,
+} from "./test-rng-helpers";
+// Zone factory
+export {
+  createTestDeck,
+  createTestGraveyard,
+  createTestHand,
+  createTestPlayArea,
+  createTestZone,
+  resetZoneCounter,
+} from "./test-zone-factory";

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

@@ -0,0 +1,341 @@
+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 {
+  expectMoveFailure,
+  expectMoveSuccess,
+  expectStateProperty,
+} from "./test-assertions";
+import { createMockContext } from "./test-context-factory";
+
+/**
+ * Test state for assertions
+ */
+type TestGameState = {
+  players: Array<{
+    id: PlayerId;
+    name: string;
+    score: number;
+    hand: string[];
+  }>;
+  currentPlayerIndex: number;
+  turnNumber: number;
+  phase: "main" | "end";
+  nested: {
+    deep: {
+      value: number;
+    };
+  };
+};
+
+type TestMoves = {
+  addScore: { amount: number };
+  drawCard: Record<string, never>;
+  invalidMove: Record<string, never>;
+};
+
+describe("test-assertions", () => {
+  function createTestEngine() {
+    const moves: GameMoveDefinitions<TestGameState, TestMoves> = {
+      addScore: {
+        reducer: (draft, context) => {
+          const player = draft.players[draft.currentPlayerIndex];
+          if (player && context.params?.amount) {
+            player.score += context.params.amount as number;
+          }
+        },
+      },
+      drawCard: {
+        reducer: (draft) => {
+          const player = draft.players[draft.currentPlayerIndex];
+          if (player) {
+            player.hand.push("card");
+          }
+        },
+      },
+      invalidMove: {
+        condition: () => false, // Always fails
+        reducer: () => {},
+      },
+    };
+
+    const gameDefinition: GameDefinition<TestGameState, TestMoves> = {
+      name: "Test Game",
+      setup: (players) => ({
+        players: players.map((p) => ({
+          id: p.id as PlayerId,
+          name: p.name || "Player",
+          score: 0,
+          hand: [] as string[],
+        })),
+        currentPlayerIndex: 0,
+        turnNumber: 1,
+        phase: "main" as const,
+        nested: {
+          deep: {
+            value: 42,
+          },
+        },
+      }),
+      moves,
+    };
+
+    const players = [
+      { id: createPlayerId("p1"), name: "Alice" },
+      { id: createPlayerId("p2"), name: "Bob" },
+    ];
+
+    return new RuleEngine(gameDefinition, players);
+  }
+
+  describe("expectMoveSuccess", () => {
+    it("should pass when move succeeds", () => {
+      const engine = createTestEngine();
+
+      // Should not throw
+      expectMoveSuccess(engine, "addScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 5 },
+      });
+    });
+
+    it("should fail when move does not succeed", () => {
+      const engine = createTestEngine();
+
+      // Should throw because condition fails
+      expect(() => {
+        expectMoveSuccess(engine, "invalidMove", {
+          playerId: createPlayerId("p1"),
+          params: {},
+        });
+      }).toThrow();
+    });
+
+    it("should return move result for further assertions", () => {
+      const engine = createTestEngine();
+
+      const result = expectMoveSuccess(engine, "addScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 5 },
+      });
+
+      expect(result.success).toBe(true);
+      if (result.success) {
+        expect(result.patches.length).toBeGreaterThan(0);
+      }
+    });
+
+    it("should throw with descriptive error message on failure", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectMoveSuccess(engine, "invalidMove", {
+          playerId: createPlayerId("p1"),
+          params: {},
+        });
+      }).toThrow(/Expected move 'invalidMove' to succeed/);
+    });
+  });
+
+  describe("expectMoveFailure", () => {
+    it("should pass when move fails", () => {
+      const engine = createTestEngine();
+
+      // Should not throw
+      expectMoveFailure(engine, "invalidMove", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+    });
+
+    it("should fail when move succeeds", () => {
+      const engine = createTestEngine();
+
+      // Should throw because move succeeds
+      expect(() => {
+        expectMoveFailure(engine, "addScore", {
+          playerId: createPlayerId("p1"),
+          params: { amount: 5 },
+        });
+      }).toThrow();
+    });
+
+    it("should return failure result with error", () => {
+      const engine = createTestEngine();
+
+      const result = expectMoveFailure(engine, "invalidMove", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.error).toBeDefined();
+        expect(result.errorCode).toBeDefined();
+      }
+    });
+
+    it("should optionally check error code", () => {
+      const engine = createTestEngine();
+
+      // Should not throw because error code matches
+      expectMoveFailure(
+        engine,
+        "invalidMove",
+        { playerId: createPlayerId("p1"), params: {} },
+        "CONDITION_FAILED",
+      );
+    });
+
+    it("should throw when error code does not match", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectMoveFailure(
+          engine,
+          "invalidMove",
+          { playerId: createPlayerId("p1"), params: {} },
+          "WRONG_CODE",
+        );
+      }).toThrow(/Expected error code 'WRONG_CODE'/);
+    });
+
+    it("should throw with descriptive error message when move succeeds", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectMoveFailure(engine, "addScore", {
+          playerId: createPlayerId("p1"),
+          params: { amount: 5 },
+        });
+      }).toThrow(/Expected move 'addScore' to fail/);
+    });
+  });
+
+  describe("expectStateProperty", () => {
+    it("should verify top-level property", () => {
+      const engine = createTestEngine();
+
+      // Should not throw
+      expectStateProperty(engine, "turnNumber", 1);
+      expectStateProperty(engine, "phase", "main");
+    });
+
+    it("should verify nested property with dot notation", () => {
+      const engine = createTestEngine();
+
+      // Should not throw
+      expectStateProperty(engine, "nested.deep.value", 42);
+    });
+
+    it("should verify array element", () => {
+      const engine = createTestEngine();
+
+      expectStateProperty(engine, "players[0].name", "Alice");
+      expectStateProperty(engine, "players[1].name", "Bob");
+    });
+
+    it("should verify array length", () => {
+      const engine = createTestEngine();
+
+      expectStateProperty(engine, "players.length", 2);
+    });
+
+    it("should throw when property value does not match", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectStateProperty(engine, "turnNumber", 99);
+      }).toThrow(/Expected state.turnNumber to be 99/);
+    });
+
+    it("should throw when property path does not exist", () => {
+      const engine = createTestEngine();
+
+      expect(() => {
+        expectStateProperty(
+          engine,
+          "nonexistent.path" as any,
+          "anything" as any,
+        );
+      }).toThrow(/Property path 'nonexistent.path' not found/);
+    });
+
+    it("should work with undefined values", () => {
+      const engine = createTestEngine();
+      engine.executeMove("addScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 5 },
+      });
+
+      // Non-existent property should be undefined
+      expect(() => {
+        expectStateProperty(
+          engine,
+          "players[0].nonexistent" as any,
+          undefined as any,
+        );
+      }).toThrow();
+    });
+
+    it("should verify state changes after moves", () => {
+      const engine = createTestEngine();
+
+      expectStateProperty(engine, "players[0].score", 0);
+
+      engine.executeMove("addScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 10 },
+      });
+
+      expectStateProperty(engine, "players[0].score", 10);
+    });
+
+    it("should handle complex nested paths", () => {
+      const engine = createTestEngine();
+
+      // Draw some cards
+      engine.executeMove("drawCard", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+      engine.executeMove("drawCard", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+
+      expectStateProperty(engine, "players[0].hand.length", 2);
+      expectStateProperty(engine, "players[0].hand[0]", "card");
+    });
+  });
+
+  describe("integration with RuleEngine", () => {
+    it("should work together in a typical test scenario", () => {
+      const engine = createTestEngine();
+
+      // Initial state assertions
+      expectStateProperty(engine, "turnNumber", 1);
+      expectStateProperty(engine, "players[0].score", 0);
+
+      // Execute and verify success
+      expectMoveSuccess(engine, "addScore", {
+        playerId: createPlayerId("p1"),
+        params: { amount: 5 },
+      });
+
+      // Verify state changed
+      expectStateProperty(engine, "players[0].score", 5);
+
+      // Verify invalid move fails
+      expectMoveFailure(engine, "invalidMove", {
+        playerId: createPlayerId("p1"),
+        params: {},
+      });
+
+      // State should be unchanged after failed move
+      expectStateProperty(engine, "players[0].score", 5);
+    });
+  });
+});