@drmxrcy/tcg-core 0.0.0-202602060542

package/src/testing/test-assertions.ts

@@ -0,0 +1,256 @@
+import type { MoveExecutionResult, RuleEngine } from "../engine/rule-engine";
+import type { MoveContext, MoveContextInput } from "../moves/move-system";
+
+/**
+ * Test Assertions
+ *
+ * Assertion helpers for testing game moves and state
+ */
+
+/**
+ * Assert that a move executes successfully
+ *
+ * Executes the move and throws an error if it fails.
+ * Returns the success result for further assertions on patches.
+ *
+ * @param engine - Rule engine instance
+ * @param moveId - Move to execute
+ * @param context - Move context
+ * @returns Move execution result (success)
+ * @throws Error if move fails
+ *
+ * @example
+ * ```typescript
+ * const result = expectMoveSuccess(engine, 'playCard', {
+ *   playerId: 'p1',
+ *   data: { cardId: 'card-123' }
+ * });
+ * expect(result.patches.length).toBeGreaterThan(0);
+ * ```
+ */
+export function expectMoveSuccess<TState, TMoves extends Record<string, any>>(
+  engine: RuleEngine<TState, TMoves>,
+  moveId: string,
+  context: MoveContextInput,
+): Extract<MoveExecutionResult, { success: true }> {
+  const result = engine.executeMove(moveId, context);
+
+  if (!result.success) {
+    throw new Error(
+      `Expected move '${moveId}' to succeed, but it failed with: ${result.error}` +
+        (result.errorCode ? ` (code: ${result.errorCode})` : ""),
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Assert that a move fails
+ *
+ * Executes the move and throws an error if it succeeds.
+ * Returns the failure result for assertions on error details.
+ *
+ * @param engine - Rule engine instance
+ * @param moveId - Move to execute
+ * @param context - Move context
+ * @param expectedErrorCode - Optional expected error code
+ * @returns Move execution result (failure)
+ * @throws Error if move succeeds or error code doesn't match
+ *
+ * @example
+ * ```typescript
+ * const result = expectMoveFailure(engine, 'invalidMove', {
+ *   playerId: 'p1'
+ * }, 'CONDITION_FAILED');
+ * expect(result.error).toContain('not met');
+ * ```
+ */
+export function expectMoveFailure<TState, TMoves extends Record<string, any>>(
+  engine: RuleEngine<TState, TMoves>,
+  moveId: string,
+  context: MoveContextInput,
+  expectedErrorCode?: string,
+): Extract<MoveExecutionResult, { success: false }> {
+  const result = engine.executeMove(moveId, context);
+
+  if (result.success) {
+    throw new Error(
+      `Expected move '${moveId}' to fail, but it succeeded with ${result.patches.length} patches`,
+    );
+  }
+
+  if (expectedErrorCode && result.errorCode !== expectedErrorCode) {
+    throw new Error(
+      `Expected error code '${expectedErrorCode}', but got '${result.errorCode}': ${result.error}`,
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Assert that a state property has a specific value
+ *
+ * Supports dot notation and array indexing for nested properties.
+ * Throws an error if the property doesn't match the expected value.
+ *
+ * @param engine - Rule engine instance
+ * @param path - Property path (e.g., 'players[0].score' or 'nested.deep.value')
+ * @param expectedValue - Expected value
+ * @throws Error if property doesn't match or path is invalid
+ *
+ * @example
+ * ```typescript
+ * expectStateProperty(engine, 'turnNumber', 1);
+ * expectStateProperty(engine, 'players[0].score', 10);
+ * expectStateProperty(engine, 'nested.deep.value', 42);
+ * ```
+ */
+export function expectStateProperty<TState, TMoves extends Record<string, any>>(
+  engine: RuleEngine<TState, TMoves>,
+  path: string,
+  expectedValue: any,
+): void {
+  const state = engine.getState();
+  const actualValue = getPropertyByPath(state, path);
+
+  if (actualValue === undefined && !hasProperty(state, path)) {
+    throw new Error(
+      `Property path '${path}' not found in state. Available paths: ${getAvailablePaths(state).join(", ")}`,
+    );
+  }
+
+  if (actualValue !== expectedValue) {
+    throw new Error(
+      `Expected state.${path} to be ${JSON.stringify(expectedValue)}, but got ${JSON.stringify(actualValue)}`,
+    );
+  }
+}
+
+/**
+ * Get property value by path with dot notation and array indexing
+ *
+ * Supports paths like:
+ * - 'players[0].name'
+ * - 'nested.deep.value'
+ * - 'array.length'
+ *
+ * @param obj - Object to traverse
+ * @param path - Property path
+ * @returns Property value or undefined
+ */
+function getPropertyByPath(obj: any, path: string): any {
+  // Split by dots but preserve array brackets
+  const parts = path.split(/\.(?![^[]*\])/);
+
+  let current = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+
+    // Handle array indexing: players[0]
+    const arrayMatch = part.match(/^(.+?)\[(\d+)\]$/);
+    if (arrayMatch) {
+      const [, arrayName, index] = arrayMatch;
+      current = current[arrayName as string];
+      if (current === null || current === undefined) {
+        return undefined;
+      }
+      current = current[Number.parseInt(index as string, 10)];
+    } else {
+      current = current[part];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Check if a property path exists in an object
+ *
+ * @param obj - Object to check
+ * @param path - Property path
+ * @returns True if path exists
+ */
+function hasProperty(obj: any, path: string): boolean {
+  const parts = path.split(/\.(?![^[]*\])/);
+  let current = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return false;
+    }
+
+    // Handle array indexing
+    const arrayMatch = part.match(/^(.+?)\[(\d+)\]$/);
+    if (arrayMatch) {
+      const [, arrayName, index] = arrayMatch;
+      if (!(arrayName in current)) {
+        return false;
+      }
+      current = current[arrayName as string];
+      if (current === null || current === undefined) {
+        return false;
+      }
+      const idx = Number.parseInt(index as string, 10);
+      if (!Array.isArray(current) || idx >= current.length) {
+        return false;
+      }
+      current = current[idx];
+    } else {
+      if (!(part in current)) {
+        return false;
+      }
+      current = current[part];
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Get available property paths in an object (for error messages)
+ *
+ * @param obj - Object to inspect
+ * @param prefix - Path prefix for recursion
+ * @param maxDepth - Maximum depth to traverse
+ * @returns Array of property paths
+ */
+function getAvailablePaths(obj: any, prefix = "", maxDepth = 2): string[] {
+  if (maxDepth <= 0 || obj === null || typeof obj !== "object") {
+    return [];
+  }
+
+  const paths: string[] = [];
+
+  for (const key of Object.keys(obj)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    paths.push(path);
+
+    // Recursively get nested paths
+    if (typeof obj[key] === "object" && obj[key] !== null) {
+      if (Array.isArray(obj[key])) {
+        // Show array length
+        paths.push(`${path}.length`);
+        // Show first few elements
+        for (let i = 0; i < Math.min(3, obj[key].length); i++) {
+          paths.push(`${path}[${i}]`);
+          const nestedPaths = getAvailablePaths(
+            obj[key][i],
+            `${path}[${i}]`,
+            maxDepth - 1,
+          );
+          paths.push(...nestedPaths);
+        }
+      } else {
+        const nestedPaths = getAvailablePaths(obj[key], path, maxDepth - 1);
+        paths.push(...nestedPaths);
+      }
+    }
+  }
+
+  return paths.slice(0, 50); // Limit for readability
+}

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

@@ -0,0 +1,228 @@
+import { describe, expect, it } from "bun:test";
+import type { CardDefinition } from "../cards/card-definition";
+import { createTestCard, createTestCards } from "./test-card-factory";
+
+describe("test-card-factory", () => {
+  describe("createTestCard", () => {
+    it("should create card with default values", () => {
+      const card = createTestCard();
+
+      expect(card.id).toBeDefined();
+      expect(card.name).toBeDefined();
+      expect(card.type).toBeDefined();
+    });
+
+    it("should generate unique IDs for each card", () => {
+      const card1 = createTestCard();
+      const card2 = createTestCard();
+      const card3 = createTestCard();
+
+      expect(card1.id).not.toBe(card2.id);
+      expect(card2.id).not.toBe(card3.id);
+      expect(card1.id).not.toBe(card3.id);
+    });
+
+    it("should override provided properties", () => {
+      const card = createTestCard({
+        name: "Custom Card",
+        type: "spell",
+        basePower: 10,
+      });
+
+      expect(card.name).toBe("Custom Card");
+      expect(card.type).toBe("spell");
+      expect(card.basePower).toBe(10);
+    });
+
+    it("should keep default values for non-overridden properties", () => {
+      const card = createTestCard({
+        name: "Custom Card",
+      });
+
+      expect(card.name).toBe("Custom Card");
+      expect(card.type).toBeDefined(); // Should still have default type
+      expect(card.id).toBeDefined(); // Should still have generated ID
+    });
+
+    it("should create creature card with power and toughness", () => {
+      const creature = createTestCard({
+        type: "creature",
+        basePower: 3,
+        baseToughness: 4,
+      });
+
+      expect(creature.type).toBe("creature");
+      expect(creature.basePower).toBe(3);
+      expect(creature.baseToughness).toBe(4);
+    });
+
+    it("should create spell card with cost", () => {
+      const spell = createTestCard({
+        type: "spell",
+        baseCost: 5,
+      });
+
+      expect(spell.type).toBe("spell");
+      expect(spell.baseCost).toBe(5);
+    });
+
+    it("should support abilities", () => {
+      const card = createTestCard({
+        abilities: ["flying", "haste"],
+      });
+
+      expect(card.abilities).toEqual(["flying", "haste"]);
+    });
+
+    it("should handle empty overrides", () => {
+      const card = createTestCard({});
+
+      expect(card.id).toBeDefined();
+      expect(card.name).toBeDefined();
+      expect(card.type).toBeDefined();
+    });
+
+    it("should create valid card definition", () => {
+      const card = createTestCard();
+
+      // Verify it's a valid CardDefinition
+      const validate = (def: CardDefinition) => def;
+      expect(() => validate(card)).not.toThrow();
+    });
+  });
+
+  describe("createTestCards", () => {
+    it("should create multiple cards with default count", () => {
+      const cards = createTestCards();
+
+      expect(cards.length).toBe(3); // Default count
+      expect(cards[0]).toBeDefined();
+      expect(cards[1]).toBeDefined();
+      expect(cards[2]).toBeDefined();
+    });
+
+    it("should create specified number of cards", () => {
+      const cards = createTestCards(5);
+
+      expect(cards.length).toBe(5);
+    });
+
+    it("should create cards with unique IDs", () => {
+      const cards = createTestCards(10);
+
+      const ids = cards.map((c) => c.id);
+      const uniqueIds = new Set(ids);
+
+      expect(uniqueIds.size).toBe(10); // All IDs should be unique
+    });
+
+    it("should apply overrides to all cards", () => {
+      const cards = createTestCards(3, {
+        type: "creature",
+        basePower: 2,
+      });
+
+      for (const card of cards) {
+        expect(card.type).toBe("creature");
+        expect(card.basePower).toBe(2);
+      }
+    });
+
+    it("should still generate unique IDs even with overrides", () => {
+      const cards = createTestCards(3, {
+        name: "Same Name",
+        type: "creature",
+      });
+
+      const ids = cards.map((c) => c.id);
+      const uniqueIds = new Set(ids);
+
+      expect(uniqueIds.size).toBe(3);
+      expect(cards[0]?.name).toBe("Same Name");
+      expect(cards[1]?.name).toBe("Same Name");
+      expect(cards[2]?.name).toBe("Same Name");
+    });
+
+    it("should handle count of 0", () => {
+      const cards = createTestCards(0);
+
+      expect(cards.length).toBe(0);
+      expect(cards).toEqual([]);
+    });
+
+    it("should handle count of 1", () => {
+      const cards = createTestCards(1);
+
+      expect(cards.length).toBe(1);
+      expect(cards[0]).toBeDefined();
+    });
+
+    it("should create cards with different base stats", () => {
+      const cards = createTestCards(3, {
+        type: "creature",
+        basePower: 5,
+        baseToughness: 5,
+        baseCost: 3,
+      });
+
+      for (const card of cards) {
+        expect(card.type).toBe("creature");
+        expect(card.basePower).toBe(5);
+        expect(card.baseToughness).toBe(5);
+        expect(card.baseCost).toBe(3);
+      }
+    });
+  });
+
+  describe("integration", () => {
+    it("should create cards useful for testing", () => {
+      // Create a test deck
+      const creatures = createTestCards(20, {
+        type: "creature",
+        basePower: 2,
+        baseToughness: 2,
+      });
+
+      const spells = createTestCards(10, {
+        type: "spell",
+        baseCost: 3,
+      });
+
+      const deck = [...creatures, ...spells];
+
+      expect(deck.length).toBe(30);
+
+      // Verify creatures
+      const creatureCards = deck.filter((c) => c.type === "creature");
+      expect(creatureCards.length).toBe(20);
+
+      // Verify spells
+      const spellCards = deck.filter((c) => c.type === "spell");
+      expect(spellCards.length).toBe(10);
+
+      // Verify all unique
+      const ids = deck.map((c) => c.id);
+      const uniqueIds = new Set(ids);
+      expect(uniqueIds.size).toBe(30);
+    });
+
+    it("should work with card registry", () => {
+      const cards = createTestCards(5);
+
+      // Simulate registry usage
+      const registry = new Map<string, CardDefinition>();
+      for (const card of cards) {
+        registry.set(card.id, card);
+      }
+
+      expect(registry.size).toBe(5);
+
+      // Can retrieve cards by ID
+      const firstCard = cards[0];
+      if (firstCard) {
+        const retrieved = registry.get(firstCard.id);
+        expect(retrieved).toEqual(firstCard);
+      }
+    });
+  });
+});

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

@@ -0,0 +1,111 @@
+import type { CardDefinition } from "../cards/card-definition";
+
+/**
+ * Test Card Factory
+ *
+ * Factory functions for creating test card definitions
+ */
+
+let cardCounter = 0;
+
+/**
+ * Create a test card definition with optional overrides
+ *
+ * Generates a card with sensible defaults that can be customized.
+ * Each card gets a unique ID automatically.
+ *
+ * @param overrides - Optional properties to override defaults
+ * @returns Card definition for testing
+ *
+ * @example
+ * ```typescript
+ * // Create default test card
+ * const card = createTestCard();
+ *
+ * // Create custom creature
+ * const creature = createTestCard({
+ *   name: 'Dragon',
+ *   type: 'creature',
+ *   basePower: 5,
+ *   baseToughness: 5,
+ *   baseCost: 7
+ * });
+ *
+ * // Create spell
+ * const spell = createTestCard({
+ *   type: 'spell',
+ *   baseCost: 3
+ * });
+ * ```
+ */
+export function createTestCard(
+  overrides?: Partial<CardDefinition>,
+): CardDefinition {
+  const id = `test-card-${cardCounter++}`;
+
+  return {
+    id,
+    name: `Test Card ${cardCounter}`,
+    type: "creature",
+    basePower: 1,
+    baseToughness: 1,
+    baseCost: 1,
+    ...overrides,
+  };
+}
+
+/**
+ * Create multiple test cards with optional overrides
+ *
+ * Generates an array of test cards, each with a unique ID.
+ * All cards share the same overridden properties but have unique IDs.
+ *
+ * @param count - Number of cards to create (default: 3)
+ * @param overrides - Optional properties to override defaults for all cards
+ * @returns Array of card definitions
+ *
+ * @example
+ * ```typescript
+ * // Create 5 default cards
+ * const cards = createTestCards(5);
+ *
+ * // Create 10 creatures with same stats
+ * const creatures = createTestCards(10, {
+ *   type: 'creature',
+ *   basePower: 2,
+ *   baseToughness: 2
+ * });
+ *
+ * // Create deck of mixed cards
+ * const deck = [
+ *   ...createTestCards(20, { type: 'creature' }),
+ *   ...createTestCards(10, { type: 'spell' })
+ * ];
+ * ```
+ */
+export function createTestCards(
+  count = 3,
+  overrides?: Partial<CardDefinition>,
+): CardDefinition[] {
+  const cards: CardDefinition[] = [];
+
+  for (let i = 0; i < count; i++) {
+    cards.push(createTestCard(overrides));
+  }
+
+  return cards;
+}
+
+/**
+ * Reset the card counter (useful for deterministic test IDs)
+ *
+ * @example
+ * ```typescript
+ * resetCardCounter();
+ * const card1 = createTestCard(); // test-card-0
+ * const card2 = createTestCard(); // test-card-1
+ * ```
+ */
+export function resetCardCounter(): void {
+  cardCounter = 0;
+}