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

```bash
# 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:

```typescript
// 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

```bash
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!**