# TypeScript Testing Strategy - Quick Reference

## 🚀 Quick Start Commands

```bash
# 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

```bash
# 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)

```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

```typescript
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

```typescript
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
```typescript
// 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
```typescript
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:

```bash
# 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:**
   ```bash
   npm test && git commit
   ```

2. **Use watch mode during development:**
   ```bash
   npm run test:watch
   ```

3. **Check types frequently:**
   ```bash
   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:**
   ```typescript
   // Don't over-annotate
   const pieces: Piece[] = board.getAllPieces(); // Redundant
   const pieces = board.getAllPieces(); // Better (type inferred)
   ```

6. **Add tests for type guards:**
   ```typescript
   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:**
   ```bash
   # Review snapshots before updating
   npm test -- -u
   git diff tests/**/__snapshots__
   ```

## 🎓 Learning Resources

- [Jest + TypeScript Guide](https://jestjs.io/docs/getting-started#using-typescript)
- [ts-jest Documentation](https://kulshekhar.github.io/ts-jest/)
- [TypeScript Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
- [Playwright TypeScript](https://playwright.dev/docs/test-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.