SerpentRace/TESTING_CHECKLIST.md

# 🧪 Game Testing Checklist

## Current Status
All major backend and frontend issues have been resolved:
- ✅ Redis key consistency (gameCode everywhere)
- ✅ Turn system working for authenticated and guest players
- ✅ Gamemaster status preserved through approval workflow
- ✅ All WebSocket event handlers implemented
- ✅ TypeScript compilation successful (0 errors)
- ✅ Auto-navigation from Lobby to GameScreen wired up

## 🎯 Priority 1: Core Gameplay Flow

### Test 1: Game Creation & Joining
1. **Create a game** (as authenticated user)
   - Verify gameCode is generated
   - Check that creator becomes gamemaster
   - Check console logs for WebSocket connection

2. **Join as second player** (guest or authenticated)
   - Use the gameCode to join
   - For **private games**: Verify pending approval appears
   - For **public games**: Should join immediately
   - Check that both players appear in Lobby

3. **Gamemaster approval** (private games only)
   - Gamemaster should see pending players list
   - Click "Approve" on pending player
   - Verify approved player appears in main players list
   - **CRITICAL**: Check gamemaster still has start button visible
   - Check console for `game:player-approved` and `game:state` events

### Test 2: Game Start & Navigation
1. **Gamemaster starts game**
   - Click "Start Game" button in Lobby
   - **Watch console logs** for:
     - Backend: `game:start` emission
     - Frontend context: "Setting gameStarted to true"
     - Lobby: "gameStarted changed to: true"
     - Lobby: "navigating to /game"
   - **Verify**: All players automatically navigate to GameScreen
   - **Verify**: Board renders with all fields

2. **Check initial state**
   - First player in turn order should see "Your turn" indicator
   - Other players should see waiting message
   - Dice roll button enabled only for current player

### Test 3: Turn System
1. **First player rolls dice**
   - Click "Roll Dice" button
   - Verify dice animation shows
   - Verify player position updates on board
   - **Check console**: `game:dice-rolled` event received

2. **Draw card** (if enabled after dice roll)
   - Card modal should appear with question
   - Submit answer
   - **Check console**: `game:card-answer` emitted
   - Verify feedback (correct/incorrect)

3. **Position guessing** (after correct answer)
   - Position guess modal should appear
   - Submit position guess
   - **Check console**: `game:position-guess` emitted
   - Verify position update if correct

4. **Turn advancement**
   - After turn completes, verify:
     - `game:turn-changed` event received
     - Next player gets `game:your-turn` event
     - Turn indicator updates to show new current player
     - Previous player's dice button disabled

### Test 4: Joker Cards (Gamemaster)
1. **Player uses joker card**
   - When player answers with joker, check gamemaster sees approval request
   - Gamemaster should see modal with joker details

2. **Gamemaster approves joker**
   - Click "Approve" button
   - **Check console**: `game:gamemaster-decision` with decision:'approve'
   - Verify player receives `game:joker-complete` event
   - Verify player position updates
   - Verify requesting player sees success message

3. **Gamemaster rejects joker**
   - Use joker again, click "Reject" with reason
   - **Check console**: `game:gamemaster-decision` with decision:'reject'
   - Verify player receives rejection with reason
   - Verify no position update

### Test 5: Special Cards
1. **Luck card** (if drawn)
   - Verify `game:luck-consequence` event
   - Check position changes (forward/backward)
   - Verify extra turn if applicable

2. **Game end**
   - Play until a player reaches final position
   - Verify `game:ended` event received
   - Verify winner modal displays
   - Check final scores are correct

## 🎯 Priority 2: Edge Cases

### Test 6: Guest vs Authenticated Players
1. **Create game as authenticated user**
2. **Join as guest** (no login, just gameCode + playerName)
3. **Join as another authenticated user**
4. Start game and **verify all 3 player types can**:
   - Roll dice
   - Draw cards
   - Submit answers
   - Take turns correctly
   - See position updates

### Test 7: Reconnection
1. **Start game with 2+ players**
2. **Refresh browser** for one player
3. Verify reconnection works:
   - GameToken from localStorage is used
   - Player rejoins same game room
   - Game state syncs correctly
   - Player can continue playing

### Test 8: Error Handling
1. **Invalid gameCode**
   - Try to join with non-existent code
   - Verify error message displays

2. **Game already started**
   - Try to join game that's already in progress
   - Verify rejection message

3. **Out of turn action**
   - Player tries to roll dice when it's not their turn
   - Verify "It is not your turn" error

## 🎯 Priority 3: UI/UX Enhancements (Future)

### Polish Items
- [ ] Add countdown timer for card answers (60s)
- [ ] Add countdown timer for joker decisions (120s)
- [ ] Smooth animations for player movement
- [ ] Sound effects for dice roll, card draw, etc.
- [ ] Better winner screen with confetti animation
- [ ] Leaderboard/scores display
- [ ] Chat messages between players
- [ ] Spectator mode for finished games

## 📊 Console Log Checklist

When testing, watch for these logs to confirm everything works:

### Backend Logs (if accessible)
- `[GameWebSocketService] Broadcasting game:start to game_${gameCode}`
- `[StartGamePlayCommandHandler] Game ${gameCode} started successfully`
- `[GameWebSocketService] Player ${playerId} rolled dice: ${roll}`
- `[GameWebSocketService] Turn changed to player ${nextPlayerId}`

### Frontend Context Logs
- `🎮 [GameWebSocketContext] Socket connected to /game namespace`
- `🎮 [GameWebSocketContext] Setting gameStarted to true`
- `🎮 Game started:` (with full data object)
- `🎲 Dice rolled:` (when dice roll event received)
- `🎯 Your turn!` (when game:your-turn received)
- `🏁 Game ended:` (when game:ended received)

### Frontend Component Logs
- `🎮 Lobby: gameStarted changed to: true`
- `🎮 Game started, navigating to /game`
- `[GameScreen] Mounted and initializing`

## 🐛 Known Issues to Watch For

1. **Navigation not happening**
   - If Lobby doesn't navigate to GameScreen after start
   - Check: Is `gameStarted` in context actually changing?
   - Check: Is `goGame()` function being called?
   - Check: React Router navigation working?

2. **Gamemaster loses privileges**
   - After approving/rejecting players
   - Check: Is `isGamemaster` flag still true in context?
   - Check: Does gamemaster still see "Start Game" button?

3. **Turn validation fails**
   - "It is not your turn" for everyone
   - Check: Is `currentPlayer` set in backend game state?
   - Check: Is `playerIdentifier` correctly matching turn sequence?

4. **Guest players can't play**
   - Guest player actions ignored
   - Check: Is `playerIdentifier = socket.userId || socket.playerName` working?
   - Check: Is turn sequence using player names for guests?

## 🚀 How to Run Tests

1. **Start backend**:
   ```bash
   cd SerpentRace_Backend
   npm run dev
   ```

2. **Start frontend**:
   ```bash
   cd SerpentRace_Frontend
   npm run dev
   ```

3. **Open multiple browser windows/tabs**:
   - Window 1: Authenticated user (login first)
   - Window 2: Guest player (join directly with gameCode)
   - Window 3: Another authenticated user or guest

4. **Open browser console in all windows** (F12)
   - Filter for: 🎮, 🎲, 🎯, 🏁 emojis to see game logs

5. **Follow test scenarios above** and verify each step

## ✅ Success Criteria

The game is **fully functional** when:
- ✅ All players can create and join games
- ✅ Gamemaster can approve/reject players (private games)
- ✅ Game start triggers automatic navigation for all players
- ✅ Turn system works correctly (right player can act)
- ✅ All player types (auth + guest) can play
- ✅ Cards system works (draw, answer, validate)
- ✅ Position updates happen smoothly
- ✅ Joker approval workflow works
- ✅ Game ends with correct winner
- ✅ No console errors during gameplay

---

**Last Updated**: After fixing all compilation errors and implementing auto-navigation
**Next Step**: Run end-to-end test with 2-3 players to validate everything works