mantimon-tcg/frontend/TEST_COVERAGE_PLAN.md

Test Coverage Improvement Plan

Status: Draft
Created: 2026-02-02
Target Completion: 6 weeks
Current Coverage: 63%
Target Coverage: 85%

See PROJECT_PLAN_TEST_COVERAGE.json for full structured plan.

---

Executive Summary

The Mantimon TCG frontend has excellent test discipline (1000 passing tests) but has critical gaps in the game engine layer:

• ✅ Strong: Composables (84%), Components (90%), Stores (88%)
• ❌ Critical Gap: Game Engine (0% coverage, ~5,500 lines)
• ⚠️ Needs Work: WebSocket (27-45% coverage)

Biggest Risk: Phaser game engine is completely untested - rendering bugs, state sync issues, and visual glitches won't be caught until manual testing or production.

---

Priority Overview

🔴 Critical (Week 1-3)

Task	Component	Impact
TEST-001	Phaser testing infrastructure	Prerequisite for all game engine tests
TEST-002	MatchScene lifecycle	Core game scene rendering
TEST-003	Board layout & zones	Prize zone bug, zone management
TEST-004	Card rendering	Card display and interactions
TEST-005	StateRenderer sync	Backend ↔ Phaser synchronization
TEST-007	Socket connection	WebSocket reliability
TEST-008	Game action handling	Action queueing and responses
TEST-009	Game management	Create/join game workflows

Total: ~80 hours, 8 tasks

🟡 High (Week 4)

Task	Component	Impact
TEST-006	Zone classes	Zone types and card management
TEST-010	PreloadScene	Asset loading
TEST-011	HandManager	Drag/drop edge cases
TEST-012	DamageCounter	Damage display
TEST-013	Asset loader	Asset management
TEST-014	ResizeManager	Responsive layout

Total: ~31 hours, 6 tasks

🟢 Medium/Low (Week 5-6)

• Page tests (HomePage, CampaignPage, MatchPage)
• Edge case tests (user store, drag/drop, deck builder)
• Infrastructure (visual regression, CI coverage, documentation)

Total: ~45 hours, remaining tasks

---

Week-by-Week Roadmap

Week 1: Foundation (28 hours)

Theme: Phaser Testing Infrastructure & Core Objects

Tasks:

• TEST-001: Create Phaser mocks and test utilities (8h)
• TEST-003: Test Board layout and zones (10h)
• TEST-006: Test Zone base class and subclasses (10h)

Deliverables:

• Phaser testing infrastructure ready
• Board and Zone classes tested
• Game engine coverage: 0% → 20%

Blockers: None - can start immediately

---

Week 2: Core Engine (32 hours)

Theme: Scenes & State Synchronization

Tasks:

• TEST-002: Test MatchScene initialization (8h)
• TEST-004: Test Card rendering and interactions (12h)
• TEST-005: Test StateRenderer synchronization (12h)

Deliverables:

• MatchScene lifecycle tested
• Card display and interactions tested
• State sync tested (prize zone fix validated!)
• Game engine coverage: 20% → 50%

Blockers: Requires TEST-001 (Week 1)

---

Week 3: Network Layer (20 hours)

Theme: WebSocket & Multiplayer Reliability

Tasks:

• TEST-007: Test socket connection lifecycle (6h)
• TEST-008: Test game action handling (8h)
• TEST-009: Test game creation/joining (6h)

Deliverables:

• WebSocket reliability tests
• Action queueing tested
• Game management tested
• Socket coverage: 27% → 80%

Blockers: None - independent of game engine

---

Week 4: Engine Completion (21 hours)

Theme: Remaining Game Components

Tasks:

• TEST-010: Test PreloadScene (4h)
• TEST-011: Test HandManager drag/drop (6h)
• TEST-012: Test DamageCounter (3h)
• TEST-013: Test asset loader (4h)
• TEST-014: Test ResizeManager (4h)

Deliverables:

• All major game components tested
• Game engine coverage: 50% → 65%
• Overall coverage: 63% → 73%

---

Week 5: Integration & UI (22 hours)

Theme: Pages and Integration Testing

Tasks:

• TEST-016: User store edge cases (3h)
• TEST-017: Drag/drop edge cases (3h)
• TEST-018: Deck builder edge cases (4h)
• TEST-019: Page tests (Home, Campaign, Match) (6h)
• TEST-021: Animation sequences (6h)

Deliverables:

• All pages tested
• Integration scenarios covered
• Overall coverage: 73% → 78%

---

Week 6: Infrastructure (21 hours)

Theme: Testing Tooling & Documentation

Tasks:

• TEST-022: Visual regression with Playwright (8h)
• TEST-023: CI coverage reporting (3h)
• TEST-024: Testing documentation (4h)
• TEST-020: Socket type guards (2h)
• TEST-015: CardBack tests (2h) (Quick win!)
• TEST-025: Mutation testing (optional) (6h)

Deliverables:

• Visual regression testing enabled
• CI coverage tracking
• Testing guide for team
• Overall coverage: 78% → 82%+

---

Quick Wins (Do First!)

These tasks are simple and provide immediate value:

1. TEST-015: CardBack (2h) - Simple component, easy test, gets game/ coverage started
2. TEST-020: Type guards (2h) - Straightforward logic tests, improves socket reliability
3. TEST-016: User store (3h) - Boosts coverage from 52% to 90%+

Total: 7 hours for measurable coverage improvement

---

Production Blockers

These must be tested before production release:

1. TEST-005: StateRenderer - State desync bugs cause multiplayer issues
2. TEST-007: Socket client - Connection problems make game unplayable
3. TEST-008: useGameSocket - Lost/duplicate actions break game flow

---

Testing Challenges & Solutions

Challenge 1: Phaser Requires WebGL/Canvas

Problem: Phaser games need WebGL/Canvas, jsdom doesn't support it

Solutions:

1. Mock Phaser classes - Create minimal mocks (TEST-001)
2. Extract logic - Pull game logic out of Phaser into pure functions
3. Visual regression - Use Playwright for rendering tests (TEST-022)
4. Integration tests - Test via PhaserGame.vue wrapper

Example:

// ❌ Hard to test - logic inside Phaser class
class Card extends Phaser.GameObjects.Sprite {
  update() {
    if (this.health <= 0) {
      this.destroy()
      this.scene.addScore(10)
    }
  }
}

// ✅ Easy to test - logic extracted
function shouldDestroyCard(health: number): boolean {
  return health <= 0
}

class Card extends Phaser.GameObjects.Sprite {
  update() {
    if (shouldDestroyCard(this.health)) {
      this.destroy()
      this.scene.addScore(10)
    }
  }
}

Challenge 2: WebSocket State Management

Problem: Real-time behavior, connection state, race conditions

Solutions:

1. Mock socket.io-client - Already doing this well
2. Test state machines - Focus on state transitions
3. Fake timers - Control async timing
4. Error injection - Simulate disconnect/reconnect

Challenge 3: Animation Testing

Problem: Animations are async and timing-dependent

Solutions:

1. Fake timers - Advance time manually with vi.useFakeTimers()
2. Test completion - Verify animation completes, not individual frames
3. Integration tests - Test animation sequences end-to-end (TEST-021)

---

Coverage Targets

Area	Current	Week 2	Week 4	Week 6	3 Months
Overall	63%	68%	73%	78%	85%
Game Engine	0%	40%	60%	65%	80%
Composables	84%	84%	86%	90%	95%
Components	90%	90%	90%	92%	95%
Stores	88%	88%	90%	92%	95%
Socket	27%	27%	80%	85%	90%

---

Getting Started

Option 1: Quick Wins First (Recommended)

Build momentum with easy tasks:

# Week 1 - Quick Wins (7 hours)
npm run test -- src/game/objects/CardBack.spec.ts  # Create this
npm run test -- src/socket/types.spec.ts           # Expand this
npm run test -- src/stores/user.spec.ts            # Expand this

# Result: +5% coverage, confidence boost

Option 2: Critical Path (Production-Focused)

Tackle blockers immediately:

# Week 1-3 - Critical Path (80 hours)
# TEST-001: Phaser infrastructure (8h)
# TEST-002: MatchScene (8h)
# TEST-003: Board (10h)
# TEST-004: Card (12h)
# TEST-005: StateRenderer (12h)
# TEST-007: Socket client (6h)
# TEST-008: useGameSocket (8h)
# TEST-009: useGames (6h)

# Result: Core game and network tested, ready for production

Option 3: Parallel Development (Team of 2-3)

Split work across developers:

# Developer 1: Game Engine
- Week 1: TEST-001, TEST-003, TEST-006
- Week 2: TEST-002, TEST-004, TEST-005

# Developer 2: Network Layer
- Week 1: TEST-007, TEST-008
- Week 2: TEST-009, TEST-010, TEST-011

# Developer 3: UI & Infrastructure
- Week 1: Quick wins (TEST-015, TEST-016, TEST-020)
- Week 2: TEST-019, TEST-021
- Week 3: TEST-022, TEST-023, TEST-024

# Result: Complete in 3 weeks instead of 6

---

Success Metrics

Week 2 Checkpoint

• Phaser infrastructure works well
• Board tests validate prize zone fix
• StateRenderer tests catch desync bugs
• Coverage: 63% → 68%

Week 4 Checkpoint

• All major game components tested
• WebSocket layer reliable
• Coverage: 68% → 73%
• Team confident in test suite

Week 6 Completion

• Visual regression enabled
• CI coverage tracking
• Testing documentation complete
• Coverage: 73% → 78%
• Ready for production

3 Month Goal

• Coverage: 85%+
• All critical code paths tested
• Mutation testing shows strong tests
• New features include tests by default

---

Team Resources

Documentation

• TEST-024: Create src/test/README.md with testing patterns
• Add Phaser testing examples
• Document common pitfalls and solutions

Infrastructure

• TEST-022: Playwright visual regression
• TEST-023: CI coverage reporting
• TEST-025: Stryker mutation testing (optional)

Training

• Share knowledge as infrastructure is built
• Code review testing PRs thoroughly
• Pair program on first few Phaser tests

---

Questions & Discussion

Should we aim for 100% coverage?

No. 85% is realistic and valuable. Some code is hard to test:

• Animation frames and tweens
• WebGL rendering details
• Entry points (main.ts, router config)

Focus on logic and state management, not rendering details.

Should we stop feature work to fix coverage?

Depends on priorities. Options:

1. Aggressive: Pause features for 2-3 weeks, hit 80% coverage
2. Balanced: Dedicate 1-2 days/week to testing, reach 80% in 8-10 weeks
3. Maintenance: Add tests alongside features, reach 80% in 3-6 months

Recommendation: Balanced approach - TEST-001 through TEST-009 are critical for production confidence, do those first.

What if tests are too slow?

Strategies:

• Use vi.mock() liberally - mock Phaser, socket, API
• Use vi.useFakeTimers() - control async timing
• Run tests in parallel: vitest --threads
• Use it.skip() for expensive tests during development
• Run full suite in CI only

---

Next Steps

1. Review this plan - Discuss with team, adjust priorities
2. Start with TEST-001 - Build Phaser testing infrastructure
3. Quick win: TEST-015 - Test CardBack to validate infrastructure
4. Tackle critical path - TEST-002 through TEST-009
5. Track progress - Update PROJECT_PLAN_TEST_COVERAGE.json as tasks complete

---

Related Documents

• PROJECT_PLAN_TEST_COVERAGE.json - Full structured plan
• TESTING.md - Current testing guide (recently added!)
• CONTRIBUTING.md - Never use --no-verify policy
• VISUAL-TEST-GUIDE.md - Visual testing reference

---

Let's build confidence in our game engine! 🎮✅