chess/docs/testing/test-specifications.md

# Chess Game Test Specifications

## Test Case Catalog

This document provides detailed test case specifications for the HTML chess game.

---

## 1. Chess Rules Testing

### 1.1 Pawn Movement

#### TC-PAWN-001: Initial Two-Square Move
**Priority**: Critical
**Type**: Unit Test

**Preconditions**:
- Board in initial position
- No pieces blocking pawn path

**Test Steps**:
1. Select white pawn on e2
2. Attempt to move to e4
3. Verify move is legal
4. Verify pawn moves to e4
5. Verify turn switches to black

**Expected Result**: Pawn moves two squares forward from initial position

**Test Data**:
```javascript
{
  from: 'e2',
  to: 'e4',
  piece: 'pawn',
  color: 'white',
  expectedValid: true
}
```

---

#### TC-PAWN-002: En Passant Capture
**Priority**: High
**Type**: Integration Test

**Preconditions**:
- White pawn on e5
- Black pawn moves from d7 to d5 (two-square advance)

**Test Steps**:
1. Move white pawn from e5 to d6 (diagonal)
2. Verify move is legal (en passant)
3. Verify black pawn on d5 is captured
4. Verify white pawn is on d6

**Expected Result**: En passant capture executed correctly

**Test Data**:
```javascript
{
  setup: 'rnbqkbnr/ppp1pppp/8/3pP3/8/8/PPPP1PPP/RNBQKBNR w KQkq d6 0 1',
  move: { from: 'e5', to: 'd6' },
  capturedPiece: { square: 'd5', piece: 'pawn', color: 'black' }
}
```

---

#### TC-PAWN-003: Promotion
**Priority**: Critical
**Type**: Unit Test

**Preconditions**:
- White pawn on a7
- Black king on h8
- White's turn

**Test Steps**:
1. Move white pawn from a7 to a8
2. Verify promotion dialog appears
3. Select Queen as promotion piece
4. Verify pawn is replaced with Queen
5. Verify Queen is on a8

**Expected Result**: Pawn promotes to selected piece

**Test Data**:
```javascript
{
  from: 'a7',
  to: 'a8',
  promotionPiece: 'queen',
  expectedPiece: 'queen',
  expectedColor: 'white'
}
```

---

### 1.2 Knight Movement

#### TC-KNIGHT-001: L-Shaped Movement
**Priority**: Critical
**Type**: Unit Test

**Test Steps**:
1. Place knight on d4
2. Test all 8 possible L-shaped moves
3. Verify only valid squares are: c2, e2, f3, f5, e6, c6, b5, b3

**Expected Result**: Knight moves in L-shape pattern

**Test Data**:
```javascript
{
  position: 'd4',
  validMoves: ['c2', 'e2', 'f3', 'f5', 'e6', 'c6', 'b5', 'b3'],
  invalidMoves: ['d5', 'e4', 'c4', 'd3']
}
```

---

#### TC-KNIGHT-002: Jump Over Pieces
**Priority**: High
**Type**: Unit Test

**Preconditions**:
- Knight on b1
- Pawn on c3, d2

**Test Steps**:
1. Move knight from b1 to c3
2. Verify knight can jump over pawn on d2

**Expected Result**: Knight jumps over pieces successfully

---

### 1.3 Bishop Movement

#### TC-BISHOP-001: Diagonal Movement
**Priority**: Critical
**Type**: Unit Test

**Test Steps**:
1. Place bishop on d4
2. Verify can move to any diagonal square (a1, b2, c3, e5, f6, g7, h8, c5, b6, a7, e3, f2, g1)
3. Verify cannot move to non-diagonal squares

**Expected Result**: Bishop moves only diagonally

---

#### TC-BISHOP-002: Blocked Path
**Priority**: High
**Type**: Unit Test

**Preconditions**:
- Bishop on c1
- Pawn on d2

**Test Steps**:
1. Attempt to move bishop from c1 to e3
2. Verify move is illegal (blocked by d2 pawn)

**Expected Result**: Bishop cannot jump over pieces

---

### 1.4 Rook Movement

#### TC-ROOK-001: Straight Line Movement
**Priority**: Critical
**Type**: Unit Test

**Test Steps**:
1. Place rook on d4
2. Verify can move to any square on rank 4 or file d
3. Verify cannot move diagonally

**Expected Result**: Rook moves horizontally or vertically

---

### 1.5 Queen Movement

#### TC-QUEEN-001: Combined Movement
**Priority**: Critical
**Type**: Unit Test

**Test Steps**:
1. Place queen on d4
2. Verify can move like bishop (diagonally)
3. Verify can move like rook (straight lines)

**Expected Result**: Queen combines rook and bishop movement

---

### 1.6 King Movement

#### TC-KING-001: One Square Movement
**Priority**: Critical
**Type**: Unit Test

**Test Steps**:
1. Place king on e4
2. Verify can move one square in any direction
3. Verify cannot move two squares (except castling)

**Expected Result**: King moves one square at a time

---

#### TC-KING-002: Castling Kingside
**Priority**: Critical
**Type**: Integration Test

**Preconditions**:
- King on e1, Rook on h1
- No pieces between king and rook
- King and rook haven't moved
- King not in check

**Test Steps**:
1. Move king from e1 to g1 (castling move)
2. Verify king moves to g1
3. Verify rook moves from h1 to f1

**Expected Result**: Castling executed correctly

**Test Data**:
```javascript
{
  fen: 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK2R w KQkq - 0 1',
  kingMove: { from: 'e1', to: 'g1' },
  rookMove: { from: 'h1', to: 'f1' }
}
```

---

#### TC-KING-003: Cannot Castle Through Check
**Priority**: High
**Type**: Integration Test

**Preconditions**:
- King on e1, Rook on h1
- Black rook on f8 (attacking f1)

**Test Steps**:
1. Attempt to castle kingside
2. Verify castling is illegal

**Expected Result**: Castling blocked by check

---

#### TC-KING-004: Cannot Move Into Check
**Priority**: Critical
**Type**: Unit Test

**Preconditions**:
- White king on e1
- Black rook on f8

**Test Steps**:
1. Attempt to move king from e1 to f1
2. Verify move is illegal

**Expected Result**: King cannot move into check

---

## 2. Game State Testing

### 2.1 Check Detection

#### TC-CHECK-001: Detect Check
**Priority**: Critical
**Type**: Integration Test

**Preconditions**:
- White king on e1
- Black queen on e8

**Test Steps**:
1. Move black queen from e8 to e1
2. Verify "check" state is detected
3. Verify visual indication of check

**Expected Result**: Check detected and displayed

---

#### TC-CHECK-002: Must Respond to Check
**Priority**: Critical
**Type**: Integration Test

**Test Steps**:
1. Put white in check
2. Attempt to make move that doesn't resolve check
3. Verify move is illegal

**Expected Result**: Only legal moves escape check

---

### 2.2 Checkmate Detection

#### TC-CHECKMATE-001: Fool's Mate
**Priority**: Critical
**Type**: E2E Test

**Test Steps**:
1. f3 (white)
2. e5 (black)
3. g4 (white)
4. Qh4# (black)
5. Verify checkmate detected
6. Verify game ends
7. Verify "Black wins" message

**Expected Result**: Checkmate in 2 moves detected

**Test Data**:
```javascript
{
  moves: ['f3', 'e5', 'g4', 'Qh4'],
  result: 'black_wins',
  reason: 'checkmate'
}
```

---

#### TC-CHECKMATE-002: Back Rank Mate
**Priority**: High
**Type**: Integration Test

**Preconditions**:
- FEN: '6k1/5ppp/8/8/8/8/5PPP/4R1K1 b - - 0 1'

**Test Steps**:
1. Verify white king is trapped
2. Move black rook to e1
3. Verify checkmate

**Expected Result**: Back rank mate detected

---

### 2.3 Stalemate Detection

#### TC-STALEMATE-001: King Cannot Move
**Priority**: High
**Type**: Integration Test

**Preconditions**:
- FEN: 'k7/8/1Q6/8/8/8/8/7K b - - 0 1'

**Test Steps**:
1. Verify black has no legal moves
2. Verify black king is not in check
3. Verify game ends in stalemate

**Expected Result**: Stalemate detected, game drawn

---

### 2.4 Draw Conditions

#### TC-DRAW-001: Insufficient Material
**Priority**: Medium
**Type**: Unit Test

**Test Cases**:
- King vs King
- King+Bishop vs King
- King+Knight vs King
- King+Bishop vs King+Bishop (same color)

**Expected Result**: Draw by insufficient material

---

#### TC-DRAW-002: Fifty-Move Rule
**Priority**: Low
**Type**: Integration Test

**Test Steps**:
1. Make 50 moves without pawn move or capture
2. Verify draw can be claimed

**Expected Result**: Fifty-move rule enforced

---

#### TC-DRAW-003: Threefold Repetition
**Priority**: Medium
**Type**: Integration Test

**Test Steps**:
1. Repeat same position 3 times
2. Verify draw can be claimed

**Expected Result**: Threefold repetition detected

---

## 3. UI Testing

### 3.1 Drag and Drop

#### TC-UI-001: Drag Valid Move
**Priority**: Critical
**Type**: E2E Test

**Test Steps**:
1. Start dragging white pawn from e2
2. Hover over e4
3. Verify e4 is highlighted as valid move
4. Drop piece on e4
5. Verify piece moves to e4

**Expected Result**: Smooth drag-and-drop interaction

---

#### TC-UI-002: Drag Invalid Move
**Priority**: High
**Type**: E2E Test

**Test Steps**:
1. Start dragging white pawn from e2
2. Drag to e5 (invalid)
3. Drop piece
4. Verify piece returns to e2
5. Verify error indication

**Expected Result**: Invalid moves rejected gracefully

---

### 3.2 Click-to-Move

#### TC-UI-003: Click-Select-Click-Move
**Priority**: Critical
**Type**: E2E Test

**Test Steps**:
1. Click white pawn on e2
2. Verify piece is selected (highlighted)
3. Verify valid moves are highlighted
4. Click on e4
5. Verify piece moves to e4

**Expected Result**: Click interface works correctly

---

### 3.3 Visual Feedback

#### TC-UI-004: Highlight Last Move
**Priority**: Medium
**Type**: E2E Test

**Test Steps**:
1. Make any move
2. Verify "from" square is highlighted
3. Verify "to" square is highlighted

**Expected Result**: Last move visually indicated

---

#### TC-UI-005: Show Valid Moves
**Priority**: High
**Type**: E2E Test

**Test Steps**:
1. Select any piece
2. Verify all valid destination squares are highlighted
3. Verify invalid squares are not highlighted

**Expected Result**: Valid moves clearly shown

---

## 4. Edge Cases

### 4.1 Invalid Operations

#### TC-EDGE-001: Move Opponent's Piece
**Priority**: Critical
**Type**: Unit Test

**Test Steps**:
1. White's turn
2. Attempt to move black piece
3. Verify move is rejected

**Expected Result**: Cannot move opponent's pieces

---

#### TC-EDGE-002: Move to Same Square
**Priority**: Medium
**Type**: Unit Test

**Test Steps**:
1. Attempt to move piece to its current square
2. Verify move is rejected or piece deselects

**Expected Result**: No-op move handled gracefully

---

#### TC-EDGE-003: Multiple Rapid Clicks
**Priority**: High
**Type**: E2E Test

**Test Steps**:
1. Rapidly click on multiple squares
2. Verify only valid moves are processed
3. Verify no duplicate moves

**Expected Result**: Rapid input handled correctly

---

### 4.2 Game State Edge Cases

#### TC-EDGE-004: Undo at Game Start
**Priority**: Low
**Type**: Unit Test

**Test Steps**:
1. Start new game
2. Click undo
3. Verify no error occurs
4. Verify board unchanged

**Expected Result**: Undo disabled at start

---

#### TC-EDGE-005: Save Empty Game
**Priority**: Low
**Type**: Integration Test

**Test Steps**:
1. Start new game (no moves)
2. Save game
3. Verify game saved with initial position

**Expected Result**: Empty game saves correctly

---

## 5. Performance Testing

### 5.1 Move Calculation Performance

#### TC-PERF-001: Complex Position
**Priority**: High
**Type**: Performance Test

**Preconditions**:
- Mid-game position with 20+ pieces

**Test Steps**:
1. Calculate all legal moves
2. Measure calculation time

**Expected Result**: <100ms for move generation

---

#### TC-PERF-002: Endgame Tablebase
**Priority**: Low
**Type**: Performance Test

**Test Steps**:
1. Load 3-piece endgame position
2. Calculate optimal move
3. Measure calculation time

**Expected Result**: <50ms for simple endgame

---

### 5.2 Rendering Performance

#### TC-PERF-003: Animation Frame Rate
**Priority**: Medium
**Type**: Performance Test

**Test Steps**:
1. Execute piece move with animation
2. Measure frame rate during animation

**Expected Result**: Maintain 60 FPS

---

## 6. Accessibility Testing

### 6.1 Keyboard Navigation

#### TC-A11Y-001: Keyboard Move
**Priority**: High
**Type**: E2E Test

**Test Steps**:
1. Use Tab to focus on board
2. Use arrow keys to select square
3. Use Enter to select piece
4. Use arrow keys to select destination
5. Use Enter to move

**Expected Result**: Full keyboard control

---

#### TC-A11Y-002: Screen Reader Announcements
**Priority**: High
**Type**: Accessibility Test

**Test Steps**:
1. Enable screen reader
2. Make a move
3. Verify move is announced (e.g., "White pawn e2 to e4")

**Expected Result**: Moves announced clearly

---

### 6.2 Visual Accessibility

#### TC-A11Y-003: High Contrast Mode
**Priority**: Medium
**Type**: Visual Test

**Test Steps**:
1. Enable high contrast mode
2. Verify all pieces are distinguishable
3. Verify board squares have sufficient contrast

**Expected Result**: WCAG AA contrast ratios met

---

## 7. Cross-Browser Testing

### 7.1 Browser Compatibility

#### TC-BROWSER-001: Chrome Compatibility
**Priority**: Critical
**Type**: E2E Test

**Test Steps**:
1. Run all E2E tests in Chrome
2. Verify all tests pass

**Expected Result**: Full compatibility with Chrome

---

#### TC-BROWSER-002: Safari Compatibility
**Priority**: High
**Type**: E2E Test

**Test Steps**:
1. Run all E2E tests in Safari
2. Verify drag-and-drop works
3. Verify no visual glitches

**Expected Result**: Full compatibility with Safari

---

## Test Data References

- **FEN Strings**: [test-data/positions/](./test-data/positions/)
- **PGN Games**: [test-data/games/](./test-data/games/)
- **Test Scenarios**: [test-data/scenarios/](./test-data/scenarios/)