chess/planning/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:

{
  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:

{
  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:

{
  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:

{
  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:

{
  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:

{
  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/
• PGN Games: test-data/games/
• Test Scenarios: test-data/scenarios/