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:

   cd SerpentRace_Backend
   npm run dev
   

2. Start frontend:

   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