mantimon-tcg/TESTING.md

Testing Guide: Prize Zone Fix

Branch: fix/defer-board-creation-until-state

What Was Fixed

Bug: Prize zone rectangles (2x3 grid) were appearing even when use_prize_cards: false (Mantimon TCG points mode).

Root Cause: Board was created during scene initialization before WebSocket state arrived, using default usePrizeCards: true.

Fix: Defer Board creation until StateRenderer receives first game state with correct rules_config.

---

Quick Start

# Terminal 1: Start backend
cd backend && uv run uvicorn app.main:app --reload

# Terminal 2: Start frontend
cd frontend && npm run dev

# Terminal 3: Ensure Docker services running
docker-compose up -d

Open: http://localhost:5173

---

Test 1: Visual Verification (CRITICAL)

Game: /game/f6f158c4-47b0-41b9-b3c2-8edc8275b70c (or any Mantimon mode game)

What to Look For:

BEFORE FIX (Bug):

+-----------------+
|  Opp Active     |
|  Opp Bench      |
|  [P][P]  <---- Prize rectangles (WRONG!)
|  [P][P]
|  [P][P]
+-----------------+
|  My Active      |
|  My Bench       |
|  [P][P]  <---- Prize rectangles (WRONG!)
|  [P][P]
|  [P][P]
+-----------------+

AFTER FIX (Correct):

+-----------------+
|  Opp Active     |
|  Opp Bench      |
|  (no prizes)    |  <---- CORRECT!
+-----------------+
|  My Active      |
|  My Bench       |
|  (no prizes)    |  <---- CORRECT!
+-----------------+

Expected Board Layout (Mantimon Mode):

Top (Opponent):
- Active Zone (1 large rectangle, center-top)
- Bench Slots (5 rectangles, horizontal row)
- Deck (small rectangle, top-right)
- Discard (small rectangle, next to deck)
- Energy Deck (small rectangle, top-left)
- Hand (row of card backs, very top)

Bottom (You):
- Active Zone (1 large rectangle, center-bottom)
- Bench Slots (5 rectangles, horizontal row)
- Deck (small rectangle, bottom-right)
- Discard (small rectangle, next to deck)
- Energy Deck (small rectangle, bottom-left)
- Hand (fanned cards, very bottom)

What should NOT be there:

• ❌ 2x3 grid of small rectangles (prize cards)
• ❌ Any 6-rectangle groups
• ❌ Empty bordered boxes on the left/right sides

---

Test 2: Console Verification

Open DevTools Console (F12), look for these logs:

✅ CORRECT Logs:

[StateRenderer] Creating board with layout options: {
  usePrizeCards: false,     ← Should be FALSE
  prizeCount: 4,
  benchSize: 5,
  energyDeckEnabled: true
}
[StateRenderer] ✓ Board created successfully
[StateRenderer] Creating zones with rules: {
  usePrizeCards: false,     ← Should be FALSE
  energyDeckEnabled: true,
  benchSize: 5
}

❌ WRONG Logs (indicates bug):

[StateRenderer] Creating board with layout options: {
  usePrizeCards: true,      ← WRONG! Should be false
  ...
}

---

Test 3: Loading Overlay

1. Refresh the game page
2. Watch the loading sequence

Expected:

1. "Connecting to game..." overlay appears instantly
2. Overlay stays for 1-3 seconds
3. Overlay disappears, board is fully rendered
4. No visual flash or flicker of wrong state

Bug would be: Brief flash of prize rectangles before they disappear

---

Test 4: Fatal Error Handling

Setup (Temporary):

Edit frontend/src/game/sync/StateRenderer.ts, line 154:

// Add this line temporarily:
throw new Error('Test fatal error')
this.board = createBoard(this.scene, this.layout)

Test Steps:

1. Refresh game page
2. Observe error handling

Expected:

• ✅ Toast appears (bottom-right): "Failed to initialize game board: Test fatal error"
• ✅ Full-screen overlay appears:
  • Red error icon
  • "Failed to initialize game board"
  • "The game cannot continue. Please return to the menu."
  • Blue "Return to Menu" button
• ✅ NO auto-redirect (wait 10+ seconds to verify)
• ✅ Click button → redirects to /play

Console Expected:

[StateRenderer] ✗ Failed to create board: Error: Test fatal error
[GamePage] Fatal error from Phaser: {
  message: 'Failed to initialize game board',
  error: 'Test fatal error',
  context: 'StateRenderer.render()'
}

Cleanup:

IMPORTANT: Remove the throw new Error() line after testing!

---

Test 5: Resign Failure Toast

Setup:

1. Start a game
2. Open DevTools → Network tab → Set to "Offline"

Test Steps:

1. Click exit button (X, top-right)
2. Click "Resign and Leave"

Expected:

• ✅ Toast appears: "Could not confirm resignation with server. Leaving game anyway."
• ✅ Still redirects to /play (doesn't get stuck)
• ✅ Console: [GamePage] Failed to resign: ...

Cleanup:

Turn network back to "Online"

---

Test 6: TypeScript Compilation

cd frontend
npm run typecheck

Expected Output:

> mantimon-tcg-frontend@0.1.0 typecheck
> vue-tsc --noEmit

✓ No errors

Bug would be:

error TS2304: Cannot find name 'gameBridge'
error TS2304: Cannot find name 'Board'

---

Test 7: Classic Mode (Prize Cards Enabled)

Note: This requires a game with use_prize_cards: true in backend rules.

Expected:

• ✅ 6 prize zone rectangles ARE visible (2x3 grid, left side)
• ✅ Same for opponent (top-left)

Console Should Show:

[StateRenderer] Creating board with layout options: {
  usePrizeCards: true,      ← Should be TRUE for classic mode
  prizeCount: 6,
  ...
}

---

Test 8: Multiple Games

1. Play game 1 (Mantimon mode)
2. Exit
3. Start game 2 (any mode)

Expected:

• ✅ Game 1: No prize rectangles
• ✅ Exit works cleanly
• ✅ Game 2: Board matches its rules
• ✅ No leftover visual artifacts

Console Should Show:

[StateRenderer] Board destroyed      ← From game 1
[StateRenderer] Creating board...    ← For game 2
[StateRenderer] ✓ Board created successfully

---

Pass/Fail Criteria

✅ ALL TESTS PASS IF:

1. Visual: No prize rectangles in Mantimon mode games
2. Console: usePrizeCards: false in logs
3. Loading: No visual flash of wrong state
4. Fatal Error: Manual button, no auto-redirect
5. Resign: Toast appears on failure
6. TypeScript: No compilation errors
7. Classic Mode: Prize rectangles appear when enabled
8. Multiple Games: Clean transitions

❌ FIX FAILED IF:

• Prize rectangles visible when use_prize_cards: false
• Console shows usePrizeCards: true for Mantimon games
• Fatal error auto-redirects after 3 seconds
• TypeScript compilation errors

---

Reporting Issues

If any test fails, report:

1. Which test failed
2. What you saw (screenshot preferred)
3. Console logs (copy full output)
4. Game ID you tested with
5. Browser and version

---

Success Criteria Summary

The fix is working if:

✓ No prize zone rectangles appear in your test game
✓ Console shows usePrizeCards: false
✓ Board renders correctly after loading overlay
✓ Fatal error requires manual button click
✓ TypeScript compiles without errors

Ready for merge if all tests pass!