mtgonline/BACKEND_TEST_PLAN.md

# Backend Test Plan (Updated)

## Overview
This test plan is designed for iterative execution using sub-agents, with each sub-agent handling a specific phase to avoid exceeding the 300,000 token context limit. Each phase focuses on a distinct subsystem and includes specific test cases and verification steps.

**Last Updated:** 2026-06-08  
**Status:** Phase 1 Complete - Database & Migration Tests Verified

---

## Test Phases

### Phase 1: Database & Migration Tests ✅ COMPLETE
**Scope:** Alembic migrations, database schema, model relationships  
**Sub-agent Task:** Verify all migrations run correctly and database schema is consistent  
**Status:** ✅ Verified - All migrations functionally correct

#### Actual Migration Structure:

**Migration 000 (`000_base_tables.py`)** - Creates 8 base tables:
- `mtgonline_users` (base table)
- `mtgonline_decklist_folders` (FK to mtgonline_users.id, self-ref)
- `mtgonline_decklist_files` (FK to mtgonline_decklist_folders.id, mtgonline_users.id)
- `mtgonline_rooms` (base table)
- `mtgonline_rooms_gametypes` (FK to mtgonline_rooms.id)
- `mtgonline_bans` (FK to mtgonline_users.id)
- `mtgonline_log` (FK to mtgonline_rooms.id, mtgonline_users.id)
- `mtgonline_audit` (FK to mtgonline_users.id)

**Migration 001 (`001_initial_user_schema.py`)** - Creates 15 user-related tables:
- `user_sessions` (FK to mtgonline_users.id)
- `deck_versions` (FK to mtgonline_decklist_files.id)
- `game_replays` (FK to mtgonline_rooms.id)
- `replay_players` (FK to game_replays.id, mtgonline_users.id, mtgonline_decklist_files.id)
- `game_outcomes` (FK to mtgonline_users.id, game_replays.game_uuid)
- `user_statistics` (PK: user_id, FK to mtgonline_users.id)
- `user_card_collection` (FK to mtgonline_users.id)
- `card_wishlist` (FK to mtgonline_users.id)
- `user_groups` (FK to mtgonline_users.id)
- `group_members` (FK to user_groups.id, mtgonline_users.id)
- `group_chat_messages` (FK to user_groups.id, mtgonline_users.id)
- `user_networks` (FK to mtgonline_users.id)
- `network_members` (FK to user_networks.id, mtgonline_users.id)
- `user_preferences` (PK: user_id, FK to mtgonline_users.id)
- `user_activity_log` (FK to mtgonline_users.id)

**Migration 002 (`002_user_deck_building_tables.py`)** - Creates:
- `user_decks` (FK to mtgonline_users.id, mtgonline_decklist_folders.id)

**Migration 003 (`003_mtgonline_cards_table.py`)** - Creates:
- `mtgonline_cards` (base table)
- `user_deck_cards` (FK to user_decks.id, mtgonline_cards.id)
- `deck_precedents` (FK to mtgonline_users.id)
- `deck_precedent_cards` (FK to deck_precedents.id, mtgonline_cards.id)
- `card_suggestions` (FK to user_decks.id, mtgonline_cards.id, self-ref)

**Migration 004 (`004_card_import_table.py`)** - Creates:
- `user_card_imports` (FK to mtgonline_users.id)

**Migration 005 (`005_missing_tables.py`)** - Creates:
- `mtg_sets` (base table)
- `mtg_cards` (FK to mtg_sets.id)
- `mtg_cards_mirror` (base table)
- `card_import_batches` (FK to mtgonline_users.id)
- `user_card_imports_confirmed` (FK to mtgonline_users.id, card_import_batches.id)
- `deck_card_links` (FK to mtgonline_decklist_files.id, mtg_cards_mirror.id)

#### Verification Results:
- ✅ All 6 migrations properly linked (000 → 001 → 002 → 003 → 004 → 005)
- ✅ All foreign keys reference tables created in same or earlier migrations
- ✅ No circular dependencies
- ✅ All indexes created on FK columns
- ✅ All unique constraints valid
- ✅ Downgrade functions properly drop tables in reverse dependency order
- ✅ All model imports in `env.py` and `__init__.py` consistent

**Note:** Migration 000 is NOT empty (creates 8 base tables). This is intentional and correct.

---

### Phase 2: Model Layer Tests
**Scope:** SQLAlchemy models, relationships, validation  
**Sub-agent Task:** Verify all model definitions are correct and consistent

#### Actual Model Structure:

**1. Core Models (`app/models/models.py`)**
- `User` (`mtgonline_users`) - username, email, password_hash, salt, country, real_name, avatar_bmp, privlevel, is_active, is_banned, ban_reason, ban_ends, vip_status, vip_expiry, creation_date, last_login
- `MtonlineCard` (`mtgonline_cards`) - source_id, name, mana_cost, type_line, oracle_text, power, toughness, rarity, layout, artist, flavor_text, numbers, identifiers, images, image, set_code, set_name, card_parts, keywords, legalities, synced_at, created_at
- `DecklistFolder` (`mtgonline_decklist_folders`) - owner_id, name, parent_id, creation_date
- `DecklistFile` (`mtgonline_decklist_files`) - folder_id, owner_id, name, content, format, status, creation_date
- `Room` (`mtgonline_rooms`) - name, description, is_password_protected, password_hash, creation_date
- `RoomGameType` (`mtgonline_rooms_gametypes`) - room_id, name, description
- `Ban` (`mtgonline_bans`) - user_id, server_id, reason, moderators, ip_address, expiration_time, active, creation_date
- `GameLog` (`mtgonline_log`) - room_id, player_id, message, timestamp
- `AuditLog` (`mtgonline_audit`) - admin_id, action_type, target_user_id, details, ip_address, timestamp

**2. MTG Models (`app/models/mtg_models.py`)**
- `MtgSet` (`mtg_sets`) - code, name, type, release_date, base_set_size, total_size, is_foil_only, is_non_foil_only, digital, icon_svg_url, parent_code, mtgo_code, image, updated_at
- `MtgCard` (`mtg_cards`) - set_id, name, mana_cost, type_line, oracle_text, power, toughness, rarity, layout, artist, flavor_text, numbers, identifiers, images, image, updated_at

**3. Mirror Models (`app/models/mirror_models.py`)**
- `MtgCardMirror` (`mtg_cards_mirror`) - source_id, name, mana_cost, type_line, oracle_text, power, toughness, rarity, layout, artist, flavor_text, numbers, identifiers, images, image, card_parts, keywords, legalities, set_code, set_name, synced_at, created_at
- `DeckCardLink` (`deck_card_links`) - deck_id, card_id, quantity, zone

**4. User Data Models (`app/models/user_data.py`)**
- `UserSession` (`user_sessions`) - user_id, session_token_hash, ip_address, user_agent, created_at, expires_at, is_active
- `DeckVersion` (`deck_versions`) - deck_id, version_number, content, status, comment, created_at
- `GameReplay` (`game_replays`) - game_uuid, room_id, game_type, format, duration_seconds, start_time, end_time, status, replay_data, created_at, updated_at
- `ReplayPlayer` (`replay_players`) - replay_id, user_id, position, deck_id, won, lost, concession, turn_one, created_at
- `GameOutcome` (`game_outcomes`) - user_id, game_uuid, outcome, opponent_id, format, rating_before, rating_after, rating_change, created_at
- `UserStatistics` (`user_statistics`) - user_id (PK), total_games, total_wins, total_losses, total_concessions, win_rate, current_streak, best_streak, average_rating, last_game_date, updated_at
- `UserCardCollection` (`user_card_collection`) - user_id, card_id, quantity, condition, language, is_foil, is_alt_art, acquired_date, acquisition_method, notes, created_at, updated_at
- `CardWishlist` (`card_wishlist`) - user_id, card_id, max_price, notes, created_at
- `UserGroup` (`user_groups`) - name, description, owner_id, is_public, max_members, created_at, updated_at
- `GroupMember` (`group_members`) - group_id, user_id, role, joined_at
- `GroupChatMessage` (`group_chat_messages`) - group_id, sender_id, message, created_at
- `UserNetwork` (`user_networks`) - name, description, creator_id, is_public, created_at
- `NetworkMember` (`network_members`) - network_id, user_id, role, joined_at
- `UserPreference` (`user_preferences`) - user_id (PK), theme, notifications_enabled, email_notifications, auto_save_decks, default_format, language, updated_at
- `UserActivityLog` (`user_activity_log`) - user_id, activity_type, activity_data, ip_address, created_at

**5. User Deck Models (`app/models/user_deck.py`)**
- `UserDeck` (`user_decks`) - user_id, name, status, folder_id, format, notes, is_precedent, precedent_name, created_at, updated_at
- `UserDeckCard` (`user_deck_cards`) - deck_id, card_id, quantity, zone, position
- `DeckPrecedent` (`deck_precedents`) - name, description, format, is_public, created_by, created_at, updated_at
- `DeckPrecedentCard` (`deck_precedent_cards`) - precedent_id, card_id, quantity, zone
- `CardSuggestion` (`card_suggestions`) - deck_id, card_id, source_card_id, suggestion_type, confidence, notes, created_at

**6. Card Import Models (`app/models/card_import.py`)**
- `CardImportBatch` (`card_import_batches`) - user_id, filename, file_type, file_size, status, total_cards, matched_cards, unmatched_cards, match_results, error_message, created_at, updated_at
- `UserCardImportRecord` (`user_card_imports_confirmed`) - user_id, batch_id, is_confirmed, confirmed_at

#### Test Cases:
1. **Verify all models have proper `__tablename__`**
2. **Verify all foreign keys reference correct tables**
3. **Verify all relationships are bidirectional where needed**
4. **Verify cascade delete behavior**
5. **Verify indexes on FK columns**
6. **Verify unique constraints**
7. **Verify model imports in `app/models/__init__.py`**
8. **Check for missing fields compared to migration definitions**

**Verification:** All models compile without errors, relationships are correct, no missing fields.

---

### Phase 3: Schema Layer Tests
**Scope:** Pydantic schemas, request/response validation  
**Sub-agent Task:** Verify all schema definitions are correct

#### Actual Schema Structure:

**1. Core Schemas (`app/schemas/schemas.py`)**
- **Authentication:** `LoginRequest`, `LoginResponse`, `RefreshTokenRequest`, `TokenResponse`
- **User:** `UserBase`, `UserCreate`, `UserUpdate`, `UserResponse`
- **Deck:** `DeckCreate`, `DeckUpdate`, `DeckResponse`, `FolderCreate`, `FolderResponse`
- **Game:** `GameCreate`, `GameResponse`
- **Room:** `RoomResponse`
- **Ban:** `BanCreate`, `BanResponse`
- **Error:** `ErrorResponse`, `ValidationErrorResponse`
- **Pagination:** `PaginationParams`, `PaginatedResponse`
- **Card Mirror:** `CardMirrorResponse`, `DeckCardLinkResponse`, `DeckWithCardsResponse`

**2. User Data Schemas (`app/schemas/user_data_schemas.py`)**
- **Enums:** `DeckVersionStatus`, `GameReplayStatus`, `GameOutcomeType`, `GroupMemberRole`, `NetworkMemberRole`, `UserPreferenceTheme`, `ActivityType`
- **Session:** `SessionResponse`, `SessionCleanupResponse`
- **Deck Version:** `DeckVersionCreate`, `DeckVersionUpdate`, `DeckVersionResponse`, `DeckVersionListResponse`
- **Game Replay:** `GameReplayCreate`, `GameReplayUpdate`, `GameReplayResponse`, `GameReplayListResponse`
- **Game Outcome:** `GameOutcomeCreate`, `GameOutcomeResponse`, `GameOutcomeListResponse`
- **User Statistics:** `UserStatisticsResponse`, `StatisticsUpdateResponse`
- **Card Collection:** `CardCollectionCreate`, `CardCollectionUpdate`, `CardCollectionResponse`, `CardCollectionListResponse`
- **Wishlist:** `WishlistCreate`, `WishlistUpdate`, `WishlistResponse`, `WishlistListResponse`
- **Group:** `GroupCreate`, `GroupUpdate`, `GroupMemberCreate`, `GroupMemberUpdate`, `GroupMemberRemove`, `GroupResponse`, `GroupListResponse`, `GroupChatMessageCreate`, `GroupChatMessageResponse`, `GroupChatMessageListResponse`
- **Network:** `NetworkCreate`, `NetworkUpdate`, `NetworkMemberCreate`, `NetworkResponse`, `NetworkListResponse`
- **Preference:** `UserPreferenceUpdate`, `UserPreferenceResponse`
- **Activity Log:** `ActivityLogEntry`, `ActivityLogListResponse`
- **Generic:** `MessageResponse`, `CountResponse`, `ErrorDetail`

**3. User Deck Schemas (`app/schemas/user_deck_schemas.py`)**
- **Enums:** `DeckStatus`, `DeckZone`, `SuggestionType`
- **Deck:** `UserDeckCreate`, `UserDeckUpdate`, `UserDeckResponse`, `UserDeckListResponse`
- **Deck Card:** `DeckCardCreate`, `DeckCardUpdate`, `DeckCardResponse`, `DeckCardWithDetailsResponse`, `DeckCardListResponse`
- **Deck Precedent:** `PrecedentCreate`, `PrecedentUpdate`, `PrecedentResponse`, `PrecedentListResponse`
- **Card Suggestion:** `SuggestionCreate`, `SuggestionResponse`, `SuggestionListResponse`
- **Deck Action:** `DeckFinalizeRequest`, `DeckFinalizeResponse`, `DeckDeleteResponse`
- **Search:** `CardSearchRequest`, `CardSearchResponse`
- **Generic:** `MessageResponse`, `CountResponse`

**4. Card Import Schemas (`app/schemas/card_import_schemas.py`)**
- `CardImportRequest`, `CardImportResponse`, `CardImportStatusResponse`
- `CardMatchResult`, `CardImportSummary`
- `MessageResponse`, `CountResponse`, `ErrorResponse`

**5. Card Search Schemas (`app/schemas/card_search_schemas.py`)**
- `CardResponse`, `SetResponse`, `CardTypeResponse`, `CardSearchResponse`
- `CardImportResponse`, `CardImportStatusResponse`
- `CardMatchResult`, `CardImportSummary`
- `MessageResponse`, `CountResponse`, `ErrorResponse`

**6. Protocol Schemas (`app/schemas/proto_messages.py`)**
- **Base:** `ProtoMessageBase`
- **Commands:** `SessionCommand`, `GameCommand`, `GameEvent`, `Response`
- **Server Info:** `ServerInfoUser`, `ServerInfoDeckStorageFile`, `ServerInfoDeckStorageFolder`, `ServerInfoDeckStorageTreeItem`, `ServerInfoCard`, `ServerInfoZone`, `ServerInfoGame`

**7. Protocol Constants (`app/schemas/protocol_constants.py`)**
- `SessionCommandType` (IntEnum)
- `GameCommandType` (IntEnum)
- `GameEventType` (IntEnum)
- `ResponseCode` (IntEnum)
- `ZoneType` (IntEnum)
- `UserLevelFlag` (IntFlag)

**8. User Card Collection Schemas (`app/schemas/user_card_collection.py`)**
- **Enums:** `CardCondition`, `AcquisitionMethod`
- **Card Collection:** `CardCollectionCreate`, `CardCollectionUpdate`, `CardCollectionResponse`, `CardCollectionListResponse`
- **Wishlist:** `WishlistCreate`, `WishlistUpdate`, `WishlistResponse`, `WishlistListResponse`
- **Collection Statistics:** `CollectionStatistics`, `CollectionSummaryResponse`
- **Generic:** `MessageResponse`, `CountResponse`, `ErrorDetail`

#### Test Cases:
1. **Verify all schemas have proper `model_config`**
2. **Verify required vs optional fields**
3. **Verify validation rules (min/max length, patterns, etc.)**
4. **Verify schema imports in `app/schemas/__init__.py`**
5. **Check for missing fields compared to model definitions**
6. **Verify enum values match expected constants**

**Verification:** All schemas compile without errors, validation rules are correct, no missing fields.

---

### Phase 4: Router Layer Tests
**Scope:** FastAPI routers, endpoint definitions, dependencies  
**Sub-agent Task:** Verify all router definitions are correct

#### Actual Router Structure:

**1. Auth Router (`app/routers/auth.py`)**
- `POST /login` - Authenticate user, return JWT tokens
- `POST /refresh` - Refresh access token
- `POST /register` - Register new user
- `GET /me` - Get current authenticated user

**2. Users Router (`app/routers/users.py`)**
- `GET /{user_id}` - Get user by ID
- `PATCH /{user_id}` - Update user profile
- `POST /{user_id}/ban` - Ban user (admin only)
- `POST /{user_id}/unban` - Unban user (admin only)

**3. Decks Router (`app/routers/decks.py`)**
- **Deck CRUD:**
  - `GET /` - List user's decks with filtering
  - `POST /` - Create new user deck (DRAFT)
  - `GET /{deck_id}` - Get specific deck
  - `PATCH /{deck_id}` - Update deck
  - `DELETE /{deck_id}` - Delete deck
- **Deck Finalize:**
  - `POST /{deck_id}/finalize` - Transition DRAFT to FINAL
- **Deck Card Management:**
  - `POST /{deck_id}/cards` - Add card to deck
  - `GET /{deck_id}/cards` - Get all cards in deck
  - `PATCH /{deck_id}/cards/{card_id}` - Update card in deck
  - `DELETE /{deck_id}/cards/{card_id}` - Remove card from deck
- **Deck Precedents:**
  - `GET /precedents` - List available precedents
  - `POST /precedents` - Create precedent (template)
  - `GET /precedents/{precedent_id}` - Get specific precedent
  - `POST /precedents/{precedent_id}/use` - Clone precedent to new deck
- **Card Search:**
  - `POST /search/cards` - Search MTG cards
- **Card Suggestions:**
  - `GET /{deck_id}/suggestions` - Get card suggestions
  - `POST /{deck_id}/suggestions` - Add suggestion

**4. Additional Routers (exist but not fully documented)**
- `app/routers/rooms.py` - Rooms router
- `app/routers/games/` - Games router (directory)
- `app/routers/admin.py` - Admin router
- `app/routers/card_router.py` - Card router
- `app/routers/interactions.py` - Interactions router
- `app/routers/refresh.py` - Refresh router
- `app/routers/card_import.py` - Card import router
- `app/routers/ws.py` - WebSocket router

#### Test Cases:
1. **Verify all endpoints defined with correct HTTP methods**
2. **Verify request/response schemas match**
3. **Verify dependencies (auth, db session, etc.)**
4. **Verify prefix paths are correct**
5. **Verify tag assignments**
6. **Verify all routers imported in `app/main.py`**
7. **Check for missing endpoints**

**Verification:** All routers compile without errors, endpoints are properly defined, no missing imports.

---

### Phase 5: Service Layer Tests
**Scope:** Business logic, service functions  
**Sub-agent Task:** Verify all service implementations are correct

#### Actual Service Structure:

**1. Card Services**
- `app/services/card_database.py` - Card database management
- `app/services/card_mirror_service.py` - Card mirroring
- `app/services/card_search_service.py` - Card search
- `app/services/fuzzy_card_matcher.py` - Fuzzy card matching

**2. Deck Services**
- `app/services/deck_manager.py` - Deck management
- `app/services/deck_parser.py` - Deck parsing
- `app/services/deck_suggestion_service.py` - Deck suggestions

**3. File Services**
- `app/services/file_parser.py` - File parsing

**4. Game Services**
- `app/services/game_server.py` - Game server logic

**5. Import Services**
- `app/services/import_batch_processor.py` - Import batch processing

**6. MTGJSON Services**
- `app/services/mtgjson_downloader.py` - MTGJSON data download
- `app/services/mtgjson_loader.py` - MTGJSON data loading
- `app/services/mtgjson_manager.py` - MTGJSON data management
- `app/services/mtgjson_uploader.py` - MTGJSON data upload

#### Test Cases:
1. **Verify all functions defined with proper signatures**
2. **Verify function implementations match expected behavior**
3. **Verify service imports (models, schemas, utilities)**
4. **Check for missing implementations**
5. **Verify error handling**

**Verification:** All services compile without errors, functions are properly implemented, no missing imports.

---

### Phase 6: Utility & Helper Tests
**Scope:** Utility functions, helpers, constants  
**Sub-agent Task:** Verify all utility implementations are correct

#### Actual Utility Structure:

**1. Core Configuration (`app/core/`)**
- `app/core/database.py` - Database configuration, session management
- `app/core/redis_client.py` - Redis client setup
- `app/core/security.py` - JWT tokens, password hashing, auth dependencies
- `app/core/settings.py` - Application settings, environment variables

**2. Utilities (`app/utils/`)**
- `app/utils/auth.py` - Authentication utilities
- `app/utils/database.py` - Database utilities
- `app/utils/errors.py` - Custom exceptions and error handlers
- `app/utils/constants.py` - Application constants

#### Test Cases:
1. **Verify all functions defined with proper signatures**
2. **Verify function implementations**
3. **Verify exception classes defined with proper error codes**
4. **Verify constants defined with correct values**
5. **Verify utility imports where needed**

**Verification:** All utilities compile without errors, functions are properly implemented, no missing imports.

---

### Phase 7: Configuration & Environment Tests
**Scope:** Settings, environment variables, configuration  
**Sub-agent Task:** Verify all configuration is correct

#### Test Cases:
1. **Verify all settings defined in `app/core/settings.py`**
2. **Verify default values are sensible**
3. **Verify database URL configuration**
4. **Verify async/sync engine setup in `app/core/database.py`**
5. **Verify FastAPI app initialization in `app/main.py`**
6. **Verify middleware setup**
7. **Verify CORS configuration**
8. **Verify all settings used in code match defined settings**
9. **Verify environment variables match settings**

**Verification:** All configuration compiles without errors, settings are properly defined, no missing configuration.

---

### Phase 8: Integration Tests
**Scope:** Cross-component integration, API consistency  
**Sub-agent Task:** Verify all components work together correctly

#### Test Cases:
1. **Router-Service Integration**
   - Verify routers call correct service functions
   - Verify service functions return correct types
   - Check for integration issues

2. **Service-Model Integration**
   - Verify services use correct models
   - Verify model operations are correct
   - Check for integration issues

3. **Schema-Router Integration**
   - Verify routers use correct schemas
   - Verify schemas match request/response
   - Check for integration issues

4. **Database-Model Integration**
   - Verify models match database schema (from migrations)
   - Verify migrations create correct tables
   - Check for integration issues

5. **Overall Consistency**
   - Verify all imports are correct
   - Verify all function calls are valid
   - Check for circular dependencies
   - Verify no orphaned code

**Verification:** All components integrate correctly, no circular dependencies, all imports valid.

---

## Execution Strategy

### Sub-Agent Execution Order:
1. **Phase 1:** ✅ Database & Migration Tests (COMPLETE)
2. **Phase 2:** Model Layer Tests
3. **Phase 3:** Schema Layer Tests
4. **Phase 4:** Router Layer Tests
5. **Phase 5:** Service Layer Tests
6. **Phase 6:** Utility & Helper Tests
7. **Phase 7:** Configuration & Environment Tests
8. **Phase 8:** Integration Tests

### Context Management:
- Each sub-agent handles one phase at a time
- Sub-agents return only findings and issues
- Main agent aggregates results and coordinates fixes
- Maximum context usage per sub-agent: ~50,000 tokens

### Verification Criteria:
- All files compile without syntax errors
- All imports resolve correctly
- All function signatures match across components
- All foreign keys reference existing tables
- All schemas have proper validation
- All routers have proper dependencies
- No circular dependencies
- No orphaned code

### Issue Reporting:
Each sub-agent should report:
1. **Critical Issues:** Missing files, broken imports, syntax errors
2. **Consistency Issues:** Mismatched types, missing fields, incorrect references
3. **Recommendations:** Improvements, missing features, best practices

---

## Summary

This test plan provides a systematic approach to verifying the entire backend system by breaking it down into 8 manageable phases. Each phase can be executed by a sub-agent independently, ensuring comprehensive coverage while staying within context limits. The plan focuses on consistency, correctness, and completeness of the codebase.

**Current Status:** Phase 1 Complete  
**Next Phase:** Phase 2 - Model Layer Tests