chess/docs/typescript-testing-strategy.md

TypeScript Migration Testing Strategy

Executive Summary

This document outlines the comprehensive testing strategy for migrating the chess game from JavaScript to TypeScript while maintaining 100% test coverage and ensuring zero regressions.

Current State:

• 7 test files (unit tests for pieces and game logic)
• 124 passing tests across all components
• Jest with babel-jest transformer
• Custom test matchers for chess-specific validations
• jsdom environment for DOM testing

Migration Goal:

• Maintain all 124 tests in passing state
• Add type safety to test code
• Implement type-level testing
• Achieve 90%+ type coverage
• Zero regression tolerance

---

Phase 1: Jest + TypeScript Configuration

1.1 Dependencies Installation

npm install --save-dev \
  typescript \
  ts-jest \
  @types/jest \
  @types/node \
  @jest/globals \
  jest-mock-extended

Package Purposes:

• typescript: TypeScript compiler
• ts-jest: Jest transformer for TypeScript
• @types/jest: TypeScript definitions for Jest
• @types/node: Node.js type definitions
• @jest/globals: Type-safe Jest globals
• jest-mock-extended: Advanced mocking with type safety

1.2 Jest Configuration Migration

File: jest.config.ts (new)

import type { Config } from 'jest';

const config: Config = {
  // Test environment
  testEnvironment: 'jsdom',

  // TypeScript transformation
  preset: 'ts-jest',

  // Module resolution
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],

  // Test patterns
  testMatch: [
    '**/tests/**/*.test.ts',
    '**/tests/**/*.test.tsx',
    '**/__tests__/**/*.ts',
    '**/__tests__/**/*.tsx'
  ],

  // Transform configuration
  transform: {
    '^.+\\.tsx?$': ['ts-jest', {
      tsconfig: {
        esModuleInterop: true,
        allowSyntheticDefaultImports: true,
        jsx: 'react',
        module: 'ESNext',
        target: 'ES2020',
        moduleResolution: 'node',
        resolveJsonModule: true,
        isolatedModules: true
      }
    }],
    '^.+\\.jsx?$': 'babel-jest' // Keep for transition period
  },

  // Module name mapper for path aliases
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '^@pieces/(.*)$': '<rootDir>/src/pieces/$1',
    '^@game/(.*)$': '<rootDir>/src/game/$1',
    '^@utils/(.*)$': '<rootDir>/src/utils/$1',
    '^@engine/(.*)$': '<rootDir>/src/engine/$1',
    '^@controllers/(.*)$': '<rootDir>/src/controllers/$1',
    '^@views/(.*)$': '<rootDir>/src/views/$1'
  },

  // Coverage configuration
  collectCoverageFrom: [
    'src/**/*.{ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/*.test.{ts,tsx}',
    '!src/main.ts',
    '!**/node_modules/**'
  ],

  coverageDirectory: 'coverage',
  coverageReporters: ['text', 'lcov', 'html', 'json-summary'],

  // Restore coverage thresholds with TypeScript
  coverageThreshold: {
    global: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80
    }
  },

  // Test setup
  setupFilesAfterEnv: ['<rootDir>/tests/setup.ts'],

  // Globals configuration
  globals: {
    'ts-jest': {
      isolatedModules: true,
      diagnostics: {
        warnOnly: true // Don't fail on type errors during transition
      }
    }
  },

  // Verbose output
  verbose: true,

  // Test timeout
  testTimeout: 10000,

  // Clear mocks between tests
  clearMocks: true,
  restoreMocks: true,
  resetMocks: true
};

export default config;

1.3 Test Setup Migration

File: tests/setup.ts (migrated from setup.js)

import '@testing-library/jest-dom';
import { jest } from '@jest/globals';

// Type-safe localStorage mock
interface LocalStorageMock {
  getItem: jest.MockedFunction<(key: string) => string | null>;
  setItem: jest.MockedFunction<(key: string, value: string) => void>;
  removeItem: jest.MockedFunction<(key: string) => void>;
  clear: jest.MockedFunction<() => void>;
  length: number;
  key: jest.MockedFunction<(index: number) => string | null>;
}

const createLocalStorageMock = (): LocalStorageMock => ({
  getItem: jest.fn<(key: string) => string | null>(),
  setItem: jest.fn<(key: string, value: string) => void>(),
  removeItem: jest.fn<(key: string) => void>(),
  clear: jest.fn<() => void>(),
  length: 0,
  key: jest.fn<(index: number) => string | null>()
});

global.localStorage = createLocalStorageMock() as Storage;

// Type-safe console mock
global.console = {
  ...console,
  error: jest.fn(),
  warn: jest.fn(),
  log: jest.fn(),
  info: jest.fn(),
  debug: jest.fn()
};

// Custom matchers with TypeScript types
interface ChessPosition {
  row: number;
  col: number;
}

declare global {
  namespace jest {
    interface Matchers<R> {
      toBeValidChessPosition(): R;
      toBeValidFEN(): R;
    }
  }
}

expect.extend({
  toBeValidChessPosition(received: unknown) {
    const pos = received as ChessPosition;
    const isValid =
      typeof pos === 'object' &&
      pos !== null &&
      'row' in pos &&
      'col' in pos &&
      pos.row >= 0 &&
      pos.row < 8 &&
      pos.col >= 0 &&
      pos.col < 8;

    return {
      message: () =>
        isValid
          ? `expected ${JSON.stringify(received)} not to be a valid chess position`
          : `expected ${JSON.stringify(received)} to be a valid chess position (row and col must be 0-7)`,
      pass: isValid
    };
  },

  toBeValidFEN(received: unknown) {
    const fenRegex = /^([rnbqkpRNBQKP1-8]+\/){7}[rnbqkpRNBQKP1-8]+ [wb] [KQkq-]+ ([a-h][1-8]|-) \d+ \d+$/;
    const isValid = typeof received === 'string' && fenRegex.test(received);

    return {
      message: () =>
        isValid
          ? `expected "${received}" not to be valid FEN`
          : `expected "${received}" to be valid FEN notation`,
      pass: isValid
    };
  }
});

// Reset mocks before each test
beforeEach(() => {
  jest.clearAllMocks();
});

// Clean up after each test
afterEach(() => {
  jest.restoreAllMocks();
});

---

Phase 2: Test File Migration Strategy

2.1 Migration Approach

Incremental Migration Pattern:

1. Migrate source file to TypeScript
2. Immediately migrate corresponding test file
3. Ensure all tests pass before moving to next file
4. Run full test suite after each migration
5. Commit after each successful file pair migration

2.2 Test File Migration Order

Priority 1: Core Types & Utilities (No Dependencies)

1. src/utils/Constants.ts → tests/unit/utils/Constants.test.ts
2. src/utils/Helpers.ts → tests/unit/utils/Helpers.test.ts

Priority 2: Base Classes 3. src/pieces/Piece.ts → tests/unit/pieces/Piece.test.ts 4. src/game/Board.ts → tests/unit/game/Board.test.ts (already exists)

Priority 3: Piece Implementations 5. src/pieces/Pawn.ts → tests/unit/pieces/Pawn.test.ts 6. src/pieces/Knight.ts → tests/unit/pieces/Knight.test.ts 7. src/pieces/Bishop.ts → tests/unit/pieces/Bishop.test.ts 8. src/pieces/Rook.ts → tests/unit/pieces/Rook.test.ts 9. src/pieces/Queen.ts → tests/unit/pieces/Queen.test.ts 10. src/pieces/King.ts → tests/unit/pieces/King.test.ts

Priority 4: Game Logic 11. src/game/GameState.ts → tests/unit/game/GameState.test.ts 12. src/engine/MoveValidator.ts → tests/unit/engine/MoveValidator.test.ts 13. src/engine/SpecialMoves.ts → tests/unit/engine/SpecialMoves.test.ts

Priority 5: Controllers & Views 14. src/utils/EventBus.ts → tests/unit/utils/EventBus.test.ts 15. src/views/BoardRenderer.ts → tests/unit/views/BoardRenderer.test.ts 16. src/controllers/DragDropHandler.ts → tests/unit/controllers/DragDropHandler.test.ts 17. src/controllers/GameController.ts → tests/integration/GameController.test.ts

2.3 Test File Template

Example: King.test.ts Migration

import { describe, test, expect, beforeEach } from '@jest/globals';
import { King } from '@pieces/King';
import { Board } from '@game/Board';
import type { Piece, PieceColor, Position } from '@/types';

describe('King', () => {
  let board: Board;

  beforeEach(() => {
    board = new Board();
    board.clear();
  });

  describe('One Square Movement', () => {
    test('king can move one square in any direction', () => {
      const king = new King('white', { row: 4, col: 4 });
      board.setPiece(4, 4, king);

      const moves = king.getValidMoves(board);

      const expectedMoves: Position[] = [
        { row: 3, col: 3 }, { row: 3, col: 4 }, { row: 3, col: 5 },
        { row: 4, col: 3 }, /* king here */ { row: 4, col: 5 },
        { row: 5, col: 3 }, { row: 5, col: 4 }, { row: 5, col: 5 }
      ];

      expect(moves).toHaveLength(8);
      expectedMoves.forEach((expected: Position) => {
        expect(moves).toContainEqual(expected);
      });
    });

    test('king in corner has 3 moves', () => {
      const king = new King('white', { row: 0, col: 0 });
      board.setPiece(0, 0, king);

      const moves: Position[] = king.getValidMoves(board);

      expect(moves).toHaveLength(3);
      expect(moves).toContainEqual({ row: 0, col: 1 });
      expect(moves).toContainEqual({ row: 1, col: 0 });
      expect(moves).toContainEqual({ row: 1, col: 1 });
    });
  });

  describe('Cannot Move Into Check', () => {
    test('king cannot move into attacked square', () => {
      const whiteKing = new King('white', { row: 7, col: 4 });
      const blackRook: Piece = {
        type: 'rook',
        color: 'black',
        position: { row: 0, col: 5 },
        hasMoved: false,
        getValidMoves: jest.fn()
      };

      board.setPiece(7, 4, whiteKing);
      board.setPiece(0, 5, blackRook);

      const moves = whiteKing.getValidMoves(board, board);

      // Type-safe assertions
      expect(moves).not.toContainEqual({ row: 7, col: 5 });
      expect(moves).not.toContainEqual({ row: 6, col: 5 });
    });
  });

  describe('Castling - Kingside', () => {
    test('king can castle kingside when conditions met', () => {
      const king = new King('white', { row: 7, col: 4 });
      const rook: Piece = {
        type: 'rook',
        color: 'white',
        position: { row: 7, col: 7 },
        hasMoved: false,
        getValidMoves: jest.fn()
      };

      board.setPiece(7, 4, king);
      board.setPiece(7, 7, rook);

      const gameState = { castlingRights: { whiteKingside: true } };
      const moves = king.getValidMoves(board, board, gameState);

      expect(moves).toContainEqual({ row: 7, col: 6, castling: 'kingside' });
    });
  });
});

---

Phase 3: Type-Safe Test Utilities

3.1 Test Factory Pattern

File: tests/utils/factories.ts

import { jest } from '@jest/globals';
import type { Piece, PieceType, PieceColor, Position } from '@/types';

export class TestPieceFactory {
  static createPiece(
    type: PieceType,
    color: PieceColor,
    position: Position,
    hasMoved: boolean = false
  ): Piece {
    return {
      type,
      color,
      position: { ...position },
      hasMoved,
      getValidMoves: jest.fn(() => [])
    };
  }

  static createPawn(color: PieceColor, position: Position): Piece {
    return this.createPiece('pawn', color, position);
  }

  static createKing(color: PieceColor, position: Position, hasMoved: boolean = false): Piece {
    return this.createPiece('king', color, position, hasMoved);
  }

  static createRook(color: PieceColor, position: Position, hasMoved: boolean = false): Piece {
    return this.createPiece('rook', color, position, hasMoved);
  }

  static createKnight(color: PieceColor, position: Position): Piece {
    return this.createPiece('knight', color, position);
  }

  static createBishop(color: PieceColor, position: Position): Piece {
    return this.createPiece('bishop', color, position);
  }

  static createQueen(color: PieceColor, position: Position): Piece {
    return this.createPiece('queen', color, position);
  }
}

export class TestBoardFactory {
  static createEmptyBoard(): Board {
    const board = new Board();
    board.clear();
    return board;
  }

  static createStartingPosition(): Board {
    const board = new Board();
    board.setupInitialPosition();
    return board;
  }

  static createCustomPosition(pieces: Array<{ piece: Piece; position: Position }>): Board {
    const board = this.createEmptyBoard();
    pieces.forEach(({ piece, position }) => {
      board.setPiece(position.row, position.col, piece);
    });
    return board;
  }
}

3.2 Type-Safe Mock Helpers

File: tests/utils/mocks.ts

import { jest } from '@jest/globals';
import { mockDeep, mockReset, DeepMockProxy } from 'jest-mock-extended';
import type { Board, GameState, MoveValidator } from '@/types';

export function createMockBoard(): DeepMockProxy<Board> {
  return mockDeep<Board>();
}

export function createMockGameState(): DeepMockProxy<GameState> {
  return mockDeep<GameState>();
}

export function createMockMoveValidator(): DeepMockProxy<MoveValidator> {
  return mockDeep<MoveValidator>();
}

// DOM mocks
export function createMockElement(tagName: string = 'div'): HTMLElement {
  const element = document.createElement(tagName);
  jest.spyOn(element, 'addEventListener');
  jest.spyOn(element, 'removeEventListener');
  return element;
}

export function resetAllMocks(...mocks: DeepMockProxy<any>[]): void {
  mocks.forEach(mock => mockReset(mock));
}

3.3 Custom Assertion Helpers

File: tests/utils/assertions.ts

import type { Position, Move, Piece } from '@/types';

export function expectPositionsEqual(actual: Position, expected: Position): void {
  expect(actual.row).toBe(expected.row);
  expect(actual.col).toBe(expected.col);
}

export function expectMoveInArray(moves: Move[], expected: Move): void {
  const found = moves.some(
    move =>
      move.from.row === expected.from.row &&
      move.from.col === expected.from.col &&
      move.to.row === expected.to.row &&
      move.to.col === expected.to.col
  );
  expect(found).toBe(true);
}

export function expectValidPiece(piece: Piece | null): asserts piece is Piece {
  expect(piece).not.toBeNull();
  expect(piece).toBeDefined();
  expect(piece).toHaveProperty('type');
  expect(piece).toHaveProperty('color');
  expect(piece).toHaveProperty('position');
}

export function expectPieceType(piece: Piece, expectedType: PieceType): void {
  expectValidPiece(piece);
  expect(piece.type).toBe(expectedType);
}

---

Phase 4: Testing Type Definitions

4.1 Type-Level Testing Strategy

File: tests/types/type-tests.ts

import { expectType, expectError, expectAssignable } from 'tsd';
import type {
  Piece,
  PieceType,
  PieceColor,
  Position,
  Move,
  GameState,
  CastlingRights
} from '@/types';

// Test: Position type is correct
expectType<Position>({ row: 0, col: 0 });
expectError<Position>({ row: -1, col: 0 }); // Should not allow negative
expectError<Position>({ x: 0, y: 0 }); // Wrong property names

// Test: PieceColor is a union of literals
expectType<PieceColor>('white');
expectType<PieceColor>('black');
expectError<PieceColor>('red'); // Invalid color

// Test: PieceType exhaustiveness
expectType<PieceType>('pawn');
expectType<PieceType>('knight');
expectType<PieceType>('bishop');
expectType<PieceType>('rook');
expectType<PieceType>('queen');
expectType<PieceType>('king');
expectError<PieceType>('wizard'); // Invalid type

// Test: Piece interface structure
expectAssignable<Piece>({
  type: 'pawn',
  color: 'white',
  position: { row: 6, col: 4 },
  hasMoved: false,
  getValidMoves: (board) => []
});

// Test: Move type structure
expectType<Move>({
  from: { row: 6, col: 4 },
  to: { row: 4, col: 4 },
  piece: 'pawn',
  captured: null,
  promotion: null,
  castling: null,
  enPassant: false
});

// Test: CastlingRights structure
expectType<CastlingRights>({
  whiteKingside: true,
  whiteQueenside: true,
  blackKingside: false,
  blackQueenside: false
});

// Test: GameState interface
expectAssignable<GameState>({
  currentTurn: 'white',
  board: {} as Board,
  moveHistory: [],
  capturedPieces: { white: [], black: [] },
  castlingRights: {
    whiteKingside: true,
    whiteQueenside: true,
    blackKingside: true,
    blackQueenside: true
  },
  enPassantTarget: null,
  halfMoveClock: 0,
  fullMoveNumber: 1,
  inCheck: false,
  isCheckmate: false,
  isStalemate: false
});

4.2 Install Type Testing Dependencies

npm install --save-dev tsd @types/testing-library__jest-dom

4.3 Type Test Script

Add to package.json:

{
  "scripts": {
    "test:types": "tsd",
    "test:all": "npm run test:types && npm test"
  }
}

---

Phase 5: Regression Prevention Strategy

5.1 Snapshot Testing

File: tests/unit/pieces/__snapshots__/King.test.ts.snap

// tests/unit/pieces/King.test.ts
describe('King Moves Snapshot', () => {
  test('king starting position moves should match snapshot', () => {
    const board = TestBoardFactory.createStartingPosition();
    const king = board.getPiece(7, 4) as King;

    const moves = king.getValidMoves(board);

    // Ensure consistent ordering for snapshot
    const sortedMoves = moves.sort((a, b) =>
      a.row === b.row ? a.col - b.col : a.row - b.row
    );

    expect(sortedMoves).toMatchSnapshot();
  });
});

5.2 Visual Regression Testing

File: tests/visual/board-rendering.test.ts

import { BoardRenderer } from '@views/BoardRenderer';
import { Board } from '@game/Board';

describe('Board Visual Regression', () => {
  let container: HTMLElement;

  beforeEach(() => {
    container = document.createElement('div');
    container.id = 'board';
    document.body.appendChild(container);
  });

  afterEach(() => {
    document.body.removeChild(container);
  });

  test('starting position renders correctly', () => {
    const board = new Board();
    board.setupInitialPosition();

    const renderer = new BoardRenderer(board);
    renderer.render();

    // Snapshot of rendered HTML
    expect(container.innerHTML).toMatchSnapshot();
  });

  test('board after e4 move renders correctly', () => {
    const board = new Board();
    board.setupInitialPosition();
    board.movePiece(6, 4, 4, 4); // e2 to e4

    const renderer = new BoardRenderer(board);
    renderer.render();

    expect(container.innerHTML).toMatchSnapshot();
  });
});

5.3 Integration Test Suite

File: tests/integration/full-game.test.ts

import { GameController } from '@controllers/GameController';
import { Board } from '@game/Board';
import { GameState } from '@game/GameState';

describe('Full Game Integration', () => {
  let gameController: GameController;

  beforeEach(() => {
    document.body.innerHTML = `
      <div id="board"></div>
      <div id="turn-indicator"></div>
      <div id="captured-white"></div>
      <div id="captured-black"></div>
      <div id="move-history"></div>
    `;

    gameController = new GameController();
  });

  test('Scholar\'s Mate sequence', () => {
    const moves = [
      { from: { row: 6, col: 4 }, to: { row: 4, col: 4 } }, // e4
      { from: { row: 1, col: 4 }, to: { row: 3, col: 4 } }, // e5
      { from: { row: 7, col: 5 }, to: { row: 4, col: 2 } }, // Bc4
      { from: { row: 0, col: 1 }, to: { row: 2, col: 2 } }, // Nc6
      { from: { row: 7, col: 3 }, to: { row: 3, col: 7 } }, // Qh5
      { from: { row: 0, col: 6 }, to: { row: 2, col: 5 } }, // Nf6
      { from: { row: 3, col: 7 }, to: { row: 1, col: 5 } }  // Qxf7# (checkmate)
    ];

    moves.forEach((move, index) => {
      const result = gameController.makeMove(move.from, move.to);
      expect(result.success).toBe(true);

      if (index === moves.length - 1) {
        expect(gameController.isCheckmate()).toBe(true);
      }
    });
  });

  test('castling both sides', () => {
    // Setup position for castling
    const board = gameController.getBoard();
    board.clear();

    // White pieces for castling
    const whiteKing = TestPieceFactory.createKing('white', { row: 7, col: 4 });
    const whiteRookKingside = TestPieceFactory.createRook('white', { row: 7, col: 7 });
    const whiteRookQueenside = TestPieceFactory.createRook('white', { row: 7, col: 0 });

    board.setPiece(7, 4, whiteKing);
    board.setPiece(7, 7, whiteRookKingside);
    board.setPiece(7, 0, whiteRookQueenside);

    // Test kingside castling
    const kingsideCastle = gameController.makeMove(
      { row: 7, col: 4 },
      { row: 7, col: 6 }
    );
    expect(kingsideCastle.success).toBe(true);
    expect(board.getPiece(7, 6)?.type).toBe('king');
    expect(board.getPiece(7, 5)?.type).toBe('rook');
  });
});

5.4 Regression Test Checklist

File: tests/regression/CHECKLIST.md

# Regression Test Checklist

Run this checklist after each migration step:

## Basic Functionality
- [ ] All 124 original tests pass
- [ ] No TypeScript compilation errors
- [ ] No type errors in test files
- [ ] Test coverage remains >= 80%

## Piece Movement
- [ ] All pieces can move correctly
- [ ] Capture logic works for all pieces
- [ ] Special moves (castling, en passant, promotion) work
- [ ] Move validation prevents illegal moves

## Game State
- [ ] Turn switching works correctly
- [ ] Check detection works
- [ ] Checkmate detection works
- [ ] Stalemate detection works
- [ ] Move history is recorded

## UI Integration
- [ ] Board renders correctly
- [ ] Drag and drop works
- [ ] Piece highlighting works
- [ ] Move indicators appear correctly

## Performance
- [ ] Tests run in < 10 seconds total
- [ ] No memory leaks detected
- [ ] No infinite loops in move generation

## Type Safety
- [ ] All types are properly exported
- [ ] No `any` types in production code
- [ ] All function signatures are typed
- [ ] Interfaces are properly defined

---

Phase 6: Migration Execution Plan

6.1 Pre-Migration Setup

Step 1: Install Dependencies

npm install --save-dev typescript ts-jest @types/jest @types/node @jest/globals jest-mock-extended tsd

Step 2: Create TypeScript Config

# Create tsconfig.json (use Issue #6 spec)
# Create jest.config.ts
# Migrate tests/setup.js to tests/setup.ts

Step 3: Create Test Utilities

mkdir -p tests/utils tests/types tests/integration tests/visual
# Create factories.ts, mocks.ts, assertions.ts
# Create type-tests.ts

Step 4: Verify Jest Configuration

npm test -- --listTests  # Should show existing .test.js files

6.2 Migration Workflow (Per File)

# For each source file (e.g., King.js):

# 1. Create feature branch
git checkout -b migrate/king-typescript

# 2. Migrate source file
mv js/pieces/King.js src/pieces/King.ts
# Add type annotations to King.ts

# 3. Migrate test file
mv tests/unit/pieces/King.test.js tests/unit/pieces/King.test.ts
# Add type annotations to test file

# 4. Run specific test
npm test -- King.test.ts

# 5. Fix any TypeScript errors
# Iterate until all tests pass

# 6. Run full test suite
npm test

# 7. Check coverage
npm run test:coverage

# 8. Run type tests
npm run test:types

# 9. Commit if successful
git add src/pieces/King.ts tests/unit/pieces/King.test.ts
git commit -m "feat: migrate King piece to TypeScript

- Add type annotations to King class
- Migrate tests to TypeScript
- All tests passing (124/124)
- Coverage maintained at 80%+"

# 10. Push and create PR
git push origin migrate/king-typescript
gh pr create --title "feat: Migrate King piece to TypeScript" \
  --body "Part of Issue #6 TypeScript migration"

# 11. After PR approval and merge
git checkout main
git pull origin main

6.3 Maintaining Green Tests

Strategy: Never Break Main Branch

1. Feature Branches: Each file migration is a separate branch
2. Test-First Verification: Tests must pass before committing
3. Incremental Merges: Merge one file pair at a time
4. Automated CI Checks: All tests run on every PR
5. Rollback Plan: Keep JS files in separate branch until migration complete

Parallel File Support (Transition Period):

// jest.config.ts - Support both .js and .ts
testMatch: [
  '**/tests/**/*.test.ts',
  '**/tests/**/*.test.js'  // Remove after full migration
],

transform: {
  '^.+\\.tsx?$': 'ts-jest',
  '^.+\\.jsx?$': 'babel-jest'
}

---

Phase 7: Type Coverage Metrics

7.1 Install Type Coverage Tool

npm install --save-dev type-coverage

7.2 Configure Type Coverage

Add to package.json:

{
  "scripts": {
    "type-check": "tsc --noEmit",
    "type-coverage": "type-coverage --at-least 90 --strict",
    "test:types:all": "npm run type-check && npm run type-coverage && npm run test:types"
  },
  "typeCoverage": {
    "atLeast": 90,
    "strict": true,
    "ignoreCatch": false,
    "ignoreFiles": [
      "**/*.test.ts",
      "**/*.spec.ts",
      "**/node_modules/**"
    ]
  }
}

7.3 Type Coverage Goals

Metric	Target	Critical
Overall Type Coverage	90%	Yes
Strict Type Coverage	85%	Yes
Any Types	< 5%	Yes
Implicit Any	0%	Yes
Untyped Functions	< 10%	No

7.4 CI Integration

File: .github/workflows/typescript-tests.yml

name: TypeScript Tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run type-check
      - run: npm run type-coverage

  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm test
      - run: npm run test:coverage
      - uses: codecov/codecov-action@v3
        with:
          file: ./coverage/coverage-final.json

  type-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run test:types

---

Phase 8: E2E Test Compatibility

8.1 E2E Testing Strategy

Current State: No E2E tests exist

Recommendation: Add Playwright for E2E tests

npm install --save-dev @playwright/test

8.2 Playwright Configuration

File: playwright.config.ts

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',

  use: {
    baseURL: 'http://localhost:8080',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure'
  },

  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] }
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] }
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] }
    }
  ],

  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:8080',
    reuseExistingServer: !process.env.CI
  }
});

8.3 Sample E2E Tests

File: tests/e2e/gameplay.spec.ts

import { test, expect } from '@playwright/test';

test.describe('Chess Game E2E', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/');
  });

  test('should load game with initial position', async ({ page }) => {
    // Check board is rendered
    const board = page.locator('#board');
    await expect(board).toBeVisible();

    // Check all pieces are present
    const pieces = page.locator('.piece');
    await expect(pieces).toHaveCount(32);

    // Check turn indicator
    const turnIndicator = page.locator('#turn-indicator');
    await expect(turnIndicator).toContainText("White's turn");
  });

  test('should allow valid pawn move', async ({ page }) => {
    // Drag white pawn from e2 to e4
    const e2Pawn = page.locator('[data-position="6-4"]');
    const e4Square = page.locator('[data-square="4-4"]');

    await e2Pawn.dragTo(e4Square);

    // Verify move was made
    await expect(e4Square.locator('.piece')).toBeVisible();
    await expect(e4Square.locator('.piece')).toHaveAttribute('data-piece', 'pawn');

    // Verify turn switched
    const turnIndicator = page.locator('#turn-indicator');
    await expect(turnIndicator).toContainText("Black's turn");
  });

  test('should prevent invalid move', async ({ page }) => {
    // Try to move white pawn from e2 to e5 (invalid)
    const e2Pawn = page.locator('[data-position="6-4"]');
    const e5Square = page.locator('[data-square="3-4"]');

    await e2Pawn.dragTo(e5Square);

    // Verify move was rejected
    await expect(e5Square.locator('.piece')).not.toBeVisible();

    // Verify pawn is still at e2
    const e2Square = page.locator('[data-square="6-4"]');
    await expect(e2Square.locator('.piece')).toBeVisible();

    // Turn should still be white
    const turnIndicator = page.locator('#turn-indicator');
    await expect(turnIndicator).toContainText("White's turn");
  });

  test('should detect checkmate', async ({ page }) => {
    // Play Scholar's Mate using page.evaluate to directly manipulate game state
    await page.evaluate(() => {
      const moves = [
        { from: { row: 6, col: 4 }, to: { row: 4, col: 4 } }, // e4
        { from: { row: 1, col: 4 }, to: { row: 3, col: 4 } }, // e5
        { from: { row: 7, col: 5 }, to: { row: 4, col: 2 } }, // Bc4
        { from: { row: 0, col: 1 }, to: { row: 2, col: 2 } }, // Nc6
        { from: { row: 7, col: 3 }, to: { row: 3, col: 7 } }, // Qh5
        { from: { row: 0, col: 6 }, to: { row: 2, col: 5 } }, // Nf6
        { from: { row: 3, col: 7 }, to: { row: 1, col: 5 } }  // Qxf7# checkmate
      ];

      moves.forEach(move => {
        (window as any).gameController.makeMove(move.from, move.to);
      });
    });

    // Check for checkmate message
    const gameMessage = page.locator('#game-message');
    await expect(gameMessage).toContainText('Checkmate');
    await expect(gameMessage).toContainText('White wins');
  });
});

Add to package.json:

{
  "scripts": {
    "test:e2e": "playwright test",
    "test:e2e:ui": "playwright test --ui",
    "test:e2e:debug": "playwright test --debug"
  }
}

---

Success Metrics & Goals

Test Coverage Goals

Metric	Current	Target	Critical
Total Tests	124	150+	Yes
Test Pass Rate	100%	100%	Yes
Code Coverage	~80%	85%	Yes
Type Coverage	0%	90%	Yes
Branch Coverage	~75%	80%	No

Quality Gates

Before Any PR Merge:

1. ✅ All tests pass (124/124 minimum)
2. ✅ No TypeScript compilation errors
3. ✅ No type errors (strict mode)
4. ✅ Code coverage >= 80%
5. ✅ Type coverage >= 90%
6. ✅ No any types without explicit justification
7. ✅ All ESLint rules pass
8. ✅ Prettier formatting applied

Before Final Migration Complete:

1. ✅ All 17 source files migrated
2. ✅ All 7+ test files migrated
3. ✅ E2E tests implemented and passing
4. ✅ Type tests passing
5. ✅ Visual regression tests passing
6. ✅ Integration tests passing
7. ✅ CI/CD pipeline green
8. ✅ Documentation updated

Performance Goals

Metric	Target
Unit Test Suite	< 10 seconds
Integration Tests	< 5 seconds
E2E Tests	< 30 seconds
Type Check	< 5 seconds
Total CI Time	< 2 minutes

---

Risk Mitigation

Risk 1: Test Failures During Migration

Mitigation:

• One file at a time approach
• Keep JS files until full migration
• Automated rollback via Git
• Comprehensive regression tests

Risk 2: Type Errors Breaking Tests

Mitigation:

• Use diagnostics.warnOnly during transition
• Incremental strict mode adoption
• Type-safe test utilities from day 1
• Extensive type testing

Risk 3: Performance Degradation

Mitigation:

• Benchmark tests before/after
• Use isolated modules for faster compilation
• Cache type checking results
• Monitor CI execution time

Risk 4: Coverage Drop

Mitigation:

• Enforce coverage thresholds in CI
• Track coverage per-file
• Add tests for edge cases revealed by types
• Visual coverage reports

---

Timeline & Milestones

Week 1: Setup & Foundation

• Day 1-2: Install dependencies, configure Jest + TypeScript
• Day 3: Migrate test utilities and setup files
• Day 4-5: Create factories, mocks, and assertions
• Milestone: Green test suite with TypeScript configuration

Week 2: Core Types & Base Classes

• Day 1: Migrate Constants and Helpers + tests
• Day 2-3: Migrate Piece base class + tests
• Day 4-5: Migrate Board class + tests
• Milestone: Core infrastructure in TypeScript

Week 3: Piece Implementations

• Day 1: Pawn + tests
• Day 2: Knight & Bishop + tests
• Day 3: Rook & Queen + tests
• Day 4-5: King + tests (complex, castling logic)
• Milestone: All pieces in TypeScript

Week 4: Game Logic & Engine

• Day 1-2: GameState + MoveValidator + tests
• Day 3: SpecialMoves + tests
• Day 4-5: Integration tests
• Milestone: Complete game logic in TypeScript

Week 5: Controllers, Views & E2E

• Day 1: EventBus + tests
• Day 2-3: BoardRenderer + DragDropHandler + tests
• Day 4: GameController + integration tests
• Day 5: E2E tests with Playwright
• Milestone: Full application in TypeScript

Week 6: Polish & Verification

• Day 1-2: Type coverage optimization (reach 90%)
• Day 3: Visual regression tests
• Day 4: Performance benchmarking
• Day 5: Final verification, documentation
• Milestone: Migration complete, all quality gates passed

---

Conclusion

This comprehensive testing strategy ensures:

1. Zero Regression: All 124 tests remain passing throughout migration
2. Type Safety: 90%+ type coverage with strict mode enabled
3. Maintainability: Type-safe test utilities and factories
4. Confidence: Multi-layer testing (unit, integration, E2E, type-level)
5. Quality: Automated CI checks enforce quality gates
6. Speed: Incremental migration allows continuous deployment

Next Steps:

1. Review and approve this strategy
2. Set up initial TypeScript + Jest configuration
3. Begin migration with Constants/Helpers (lowest risk)
4. Establish CI pipeline
5. Execute migration plan file-by-file

Success Criteria:

• ✅ 100% test pass rate maintained
• ✅ 90%+ type coverage achieved
• ✅ Zero production bugs introduced
• ✅ CI pipeline running in < 2 minutes
• ✅ All quality gates passing on every PR