turn-based-game-mcp testing.instructions.md

Testing Guidelines

Purpose

Testing patterns and requirements for all packages. Covers test structure, mocking, shared utilities, and coverage requirements.

Test Structure and Organization

• Use descriptive test names following the pattern: "should [expected behavior] when [condition]"
• Group related tests using describe blocks
• Use beforeEach for common setup and afterEach for cleanup
• Keep tests focused on single behaviors

Mock Patterns

• Mock external dependencies (APIs, timers, storage) but not the component being tested
• Use factory functions for creating mock data:

  const createMockGameState = (overrides = {}) => ({
    id: 'test-game',
    players: [
      { id: 'player1', name: 'Player 1', isAI: false },
      { id: 'ai', name: 'AI Player', isAI: true }
    ],
    currentPlayerId: 'player1',
    status: 'playing',
    ...overrides
  })
  

Shared Testing Utilities

Use centralized mock data and test utilities from the shared package:

// ✅ Import shared testing utilities
import { 
  mockTicTacToeGameState, 
  mockRPSGameState,
  createMockGameSession,
  setupTestDatabase,
  clearTestDatabase 
} from '@turn-based-mcp/shared/testing'

// ✅ Use shared constants in tests
import { DIFFICULTIES, GAME_TYPES } from '@turn-based-mcp/shared'

// ❌ Don't recreate mock data locally
const localMockGameState = { /* duplicated data */ }  // Use shared mocks instead!

Available shared testing utilities:

• Mock game states: mockTicTacToeGameState, mockRPSGameState
• Factory functions: createMockGameSession, createMockPlayer
• Database utilities: setupTestDatabase, clearTestDatabase, teardownTestDatabase
• Type assertions and validation helpers

Component Testing

• Always render components with realistic props
• Test user-facing behavior, not implementation details
• Use specific assertions (toHaveClass, toHaveAttribute) over snapshots
• Test both positive and negative cases
• Always test accessibility attributes (ARIA labels, roles, keyboard navigation)