chess/docs/typescript-testing-quick-ref.md

TypeScript Testing Strategy - Quick Reference

🚀 Quick Start Commands

# Install all testing dependencies
npm install --save-dev typescript ts-jest @types/jest @types/node @jest/globals jest-mock-extended tsd @playwright/test type-coverage

# Run tests
npm test                    # All tests
npm run test:watch          # Watch mode
npm run test:coverage       # With coverage
npm run test:types          # Type-level tests
npm run test:e2e            # End-to-end tests
npm run type-check          # TypeScript compilation check
npm run type-coverage       # Check type coverage percentage

# Full test suite
npm run test:all            # Types + Unit + Coverage

📋 Pre-Flight Checklist

Before starting migration:

• All 124 tests currently passing
• Dependencies installed
• jest.config.ts created
• tests/setup.ts migrated
• Test utilities created (factories.ts, mocks.ts, assertions.ts)
• CI pipeline configured
• Feature branch created

🔄 Per-File Migration Workflow

# 1. Create branch
git checkout -b migrate/[filename]-typescript

# 2. Migrate source file
mv js/[path]/[File].js src/[path]/[File].ts
# Add type annotations

# 3. Migrate test file
mv tests/[path]/[File].test.js tests/[path]/[File].test.ts
# Add type annotations

# 4. Run tests
npm test -- [File].test.ts

# 5. Fix errors and iterate
# Repeat until green

# 6. Full suite
npm test

# 7. Coverage check
npm run test:coverage

# 8. Type check
npm run type-check && npm run type-coverage

# 9. Commit
git add src/[path]/[File].ts tests/[path]/[File].test.ts
git commit -m "feat: migrate [File] to TypeScript"

# 10. Create PR
gh pr create --title "feat: Migrate [File] to TypeScript"

📊 Quality Gates (Must Pass Before Merge)

Check	Command	Target
Tests Pass	npm test	100%
Type Check	npm run type-check	0 errors
Type Coverage	npm run type-coverage	≥ 90%
Code Coverage	npm run test:coverage	≥ 80%
ESLint	npm run lint	0 errors
Format	npm run format	No changes

🎯 Migration Order

Phase 1: Foundation (Days 1-5)

1. Constants.ts + tests
2. Helpers.ts + tests
3. Piece.ts + tests
4. Board.ts + tests (already has tests)

Phase 2: Pieces (Days 6-12) 5. Pawn.ts + tests 6. Knight.ts + tests 7. Bishop.ts + tests 8. Rook.ts + tests 9. Queen.ts + tests 10. King.ts + tests

Phase 3: Game Logic (Days 13-19) 11. GameState.ts + tests 12. MoveValidator.ts + tests 13. SpecialMoves.ts + tests

Phase 4: UI (Days 20-26) 14. EventBus.ts + tests 15. BoardRenderer.ts + tests 16. DragDropHandler.ts + tests 17. GameController.ts + integration tests

Phase 5: E2E (Days 27-30) 18. E2E test suite with Playwright 19. Visual regression tests 20. Performance benchmarks

🧪 Test File Template (TypeScript)

import { describe, test, expect, beforeEach } from '@jest/globals';
import { ClassToTest } from '@/path/to/ClassToTest';
import type { TypeToImport } from '@/types';

describe('ClassToTest', () => {
  let instance: ClassToTest;

  beforeEach(() => {
    instance = new ClassToTest();
  });

  describe('Feature Category', () => {
    test('should do something specific', () => {
      // Arrange
      const input: TypeToImport = { /* test data */ };

      // Act
      const result = instance.method(input);

      // Assert
      expect(result).toBe(expectedValue);
    });
  });
});

🏭 Test Factory Usage

import { TestPieceFactory, TestBoardFactory } from '@tests/utils/factories';

// Create pieces
const king = TestPieceFactory.createKing('white', { row: 7, col: 4 });
const pawn = TestPieceFactory.createPawn('black', { row: 1, col: 0 });

// Create boards
const emptyBoard = TestBoardFactory.createEmptyBoard();
const startingBoard = TestBoardFactory.createStartingPosition();
const customBoard = TestBoardFactory.createCustomPosition([
  { piece: king, position: { row: 7, col: 4 } },
  { piece: pawn, position: { row: 6, col: 4 } }
]);

🎭 Mocking Patterns

import { createMockBoard, createMockGameState } from '@tests/utils/mocks';
import { jest } from '@jest/globals';

// Mock entire objects
const mockBoard = createMockBoard();
mockBoard.getPiece.mockReturnValue(somePiece);

// Mock functions
const mockGetValidMoves = jest.fn<(board: Board) => Position[]>();
mockGetValidMoves.mockReturnValue([{ row: 4, col: 4 }]);

// Spy on methods
const spy = jest.spyOn(instance, 'method');
expect(spy).toHaveBeenCalledWith(expectedArg);

🔍 Common Type Errors & Fixes

Error: "Cannot find module '@/types'"

Fix: Check tsconfig.json paths configuration

Error: "Type 'X' is not assignable to type 'Y'"

Fix: Add proper type annotations or type guards

Error: "Object is possibly 'null'"

Fix: Add null check or use optional chaining

// Before
const piece = board.getPiece(row, col);
piece.move(); // Error

// After
const piece = board.getPiece(row, col);
if (piece) {
  piece.move(); // OK
}
// Or
piece?.move(); // OK

Error: "Argument of type 'unknown' is not assignable"

Fix: Add type assertion or type guard

expect(value).toBe(42); // If value is unknown

// Use type assertion
expect(value as number).toBe(42);

// Or type guard
if (typeof value === 'number') {
  expect(value).toBe(42);
}

📈 Success Metrics Dashboard

Metric	Current	Target	Status
Total Tests	124	150+	🟡 In Progress
Pass Rate	100%	100%	🟢 Passing
Code Coverage	~80%	85%	🟡 In Progress
Type Coverage	0%	90%	🔴 Not Started
Files Migrated	0/17	17/17	🔴 Not Started
Test Files Migrated	0/7	7/7	🔴 Not Started

🚨 Emergency Rollback

If migration breaks something:

# Quick rollback
git checkout main
git branch -D migrate/problematic-file

# Or revert specific commit
git revert [commit-hash]

# Re-run tests
npm test

# Restore JS version temporarily
git checkout origin/main -- js/path/to/File.js
npm test

🔗 Important Files

File	Purpose
/docs/typescript-testing-strategy.md	Full strategy document
/tests/setup.ts	Jest configuration and global test setup
/tests/utils/factories.ts	Test data factories
/tests/utils/mocks.ts	Mock creation helpers
/tests/utils/assertions.ts	Custom assertion helpers
/tests/types/type-tests.ts	Type-level tests
jest.config.ts	Jest configuration for TypeScript
tsconfig.json	TypeScript compiler configuration
playwright.config.ts	E2E test configuration

💡 Pro Tips

1. Always run tests before committing:

   npm test && git commit
   

2. Use watch mode during development:

   npm run test:watch
   

3. Check types frequently:

   npm run type-check
   

4. Keep PRs small:

   • 1-2 files per PR maximum
   • Easier to review
   • Faster to merge
   • Safer to rollback

5. Use type inference when possible:

   // Don't over-annotate
   const pieces: Piece[] = board.getAllPieces(); // Redundant
   const pieces = board.getAllPieces(); // Better (type inferred)
   

6. Add tests for type guards:

   function isPawn(piece: Piece): piece is Pawn {
     return piece.type === 'pawn';
   }
   
   test('isPawn type guard', () => {
     const pawn = TestPieceFactory.createPawn('white', { row: 6, col: 0 });
     expect(isPawn(pawn)).toBe(true);
   
     const king = TestPieceFactory.createKing('white', { row: 7, col: 4 });
     expect(isPawn(king)).toBe(false);
   });
   

7. Snapshot changes carefully:

   # Review snapshots before updating
   npm test -- -u
   git diff tests/**/__snapshots__
   

🎓 Learning Resources

• Jest + TypeScript Guide
• ts-jest Documentation
• TypeScript Testing Best Practices
• Playwright TypeScript

❓ FAQ

Q: Do I need to test types? A: Yes! Use tsd or type-level tests to ensure type safety.

Q: Should I migrate tests before or after source code? A: Migrate source file and test file together in the same PR.

Q: What if a test fails after migration? A: Don't commit! Fix the issue or rollback. Never merge failing tests.

Q: Can I use any type? A: Avoid it. Use unknown + type guards instead. Document if absolutely necessary.

Q: How do I handle DOM types? A: Install @types/testing-library__jest-dom and use proper DOM types from TypeScript.

Q: What about third-party libraries without types? A: Install @types/[library] if available, or create .d.ts declaration files.

---

Remember: Green tests = happy team. Never compromise test quality for speed.