Code_of_Conquest/public_web/docs/TESTING.md

Manual Testing Guide - Public Web Frontend

Last Updated: November 18, 2025

---

Overview

This document outlines the manual testing procedures for the Code of Conquest web frontend. Since we prefer manual testing over automated UI tests, this guide provides comprehensive checklists for testing all features.

Testing Philosophy:

• Test in multiple browsers (Chrome, Firefox, Safari, Edge)
• Test on multiple devices (Desktop, Tablet, Mobile)
• Test with and without JavaScript enabled (progressive enhancement)
• Test realtime features with multiple concurrent users
• Test all HTMX interactions

---

Testing Environment Setup

Local Testing

# Start API backend
cd api
source venv/bin/activate
python wsgi.py  # → http://localhost:5000

# Start web frontend
cd public_web
source venv/bin/activate
python wsgi.py  # → http://localhost:8000

# Start Redis (for sessions)
docker-compose up redis

# Start Appwrite (for database/auth)
docker-compose up appwrite

Test Browsers

• Desktop:

  • Chrome (latest)
  • Firefox (latest)
  • Safari (latest, macOS only)
  • Edge (latest)

• Mobile:

  • Chrome (Android)
  • Safari (iOS)

Test Accounts

Create test accounts for each tier:

• Free Tier: test_free@example.com / password123
• Basic Tier: test_basic@example.com / password123
• Premium Tier: test_premium@example.com / password123
• Elite Tier: test_elite@example.com / password123

---

Authentication Testing

Registration

Test Steps:

1. Navigate to /register
2. Fill in registration form:
   • Username: testuser
   • Email: testuser@example.com
   • Password: SecurePassword123!
   • Confirm Password: SecurePassword123!
3. Click "Register"

Expected Results:

• Form validates (required fields, email format, password strength)
• User account created in Appwrite
• Redirected to /dashboard
• Session cookie set
• Welcome message displayed

Error Cases to Test:

• Empty fields show validation errors
• Invalid email format rejected
• Password mismatch shows error
• Weak password rejected
• Duplicate email shows error

Login

Test Steps:

1. Navigate to /login
2. Enter credentials
3. Click "Login"

Expected Results:

• User authenticated
• Redirected to /dashboard
• Session cookie set
• Navigation shows user menu

Error Cases:

• Invalid credentials show error
• Empty fields show validation
• Account lockout after 5 failed attempts (if implemented)

Logout

Test Steps:

1. Click "Logout" in navigation
2. Confirm logout

Expected Results:

• Session destroyed
• Redirected to /
• Navigation shows "Login" link
• Cannot access protected pages

---

Character Management Testing

Character Creation

Test Steps:

1. Navigate to /characters/create
2. Fill in character form:
   • Name: Thorin Ironshield
   • Class: Vanguard
   • Background: Soldier
3. Click "Create Character"

Expected Results:

• Character created via API
• Redirected to /characters/{character_id}
• Character details displayed
• Character appears in character list

HTMX Behavior:

• Form submits without page reload (if using HTMX)
• Success message appears
• Form resets or replaced with character card

Error Cases:

• Name validation (3-50 characters)
• Required fields enforced
• Duplicate name handling

Character List

Test Steps:

1. Navigate to /characters
2. View character list

Expected Results:

• All user's characters displayed
• Character cards show: name, class, level, HP
• "Create Character" button visible
• Empty state if no characters

Interactions:

• Click character card → /characters/{id}
• Click "Play" → creates session
• Click "Delete" → confirmation modal
• Search/filter works (if implemented)

Character View

Test Steps:

1. Navigate to /characters/{character_id}
2. View character details

Expected Results:

• Full character sheet displayed
• Stats, abilities, inventory shown
• Equipment slots visible
• Edit/Delete buttons visible (if owner)

Character Edit

Test Steps:

1. Navigate to /characters/{character_id}/edit
2. Modify character details
3. Click "Save"

Expected Results:

• Changes saved via API
• Redirected to character view
• Updates visible immediately

Inline Edit (HTMX):

• Click name to edit inline
• Save without page reload
• Cancel reverts changes

Character Delete

Test Steps:

1. Click "Delete" on character card
2. Confirm deletion

Expected Results:

• Confirmation modal appears
• Character deleted via API
• Character removed from list (HTMX removes element)
• Success message displayed

---

Session Testing

Session Creation

Test Steps:

1. Navigate to /sessions/create
2. Select character
3. Click "Start Session"

Expected Results:

• Session created via API
• Redirected to /sessions/{session_id}
• Session UI loaded
• Timer started (if applicable)

Active Session

Test Steps:

1. Navigate to /sessions/{session_id}
2. Interact with session UI

Expected Results:

• Character info displayed
• Location/narrative shown
• Action buttons visible
• Conversation history loaded

Interactions:

• Click action button → sends to API
• Response appears in conversation
• HTMX updates without page reload
• Scrolls to latest message

Combat Session

Test Steps:

1. Start combat encounter
2. Take combat action

Expected Results:

• Combat UI displayed
• Turn order shown
• Action buttons enabled on player's turn
• Damage/effects displayed
• HP bars update

HTMX Behavior:

• Combat actions submit via HTMX
• Combat log updates dynamically
• Turn advances without reload
• Victory/defeat screen appears

Session History

Test Steps:

1. Navigate to /sessions/history
2. View past sessions

Expected Results:

• All sessions listed (active and completed)
• Session summaries shown
• Click session → view details
• Filter/search works (if implemented)

---

Multiplayer Testing

Create Multiplayer Session

Test Steps:

1. Navigate to /multiplayer/create
2. Select party size (4 players)
3. Select difficulty (Medium)
4. Click "Create Session"

Expected Results:

• Session created via API
• Redirected to lobby
• Invite code displayed
• Invite link copyable

Lobby (Host)

Test Steps:

1. View lobby as host
2. Wait for players to join

Expected Results:

• Host badge displayed
• Player list updates when players join (realtime)
• "Start Session" button disabled until all ready
• "Start Session" enabled when all ready

Realtime Updates:

• New player joins → list updates
• Player ready status changes → updates
• No page reload required

Lobby (Player)

Test Steps:

1. Click invite link in different browser
2. Select character
3. Join session

Expected Results:

• Session info displayed
• Character selection shown
• Join button enabled
• Redirected to lobby after join

Lobby Actions:

• Toggle "Ready" status
• See other players' status update
• Host starts session → redirect to active session

Active Multiplayer Session

Test Steps:

1. Play through multiplayer session
2. Take turns in combat

Expected Results:

• Campaign title displayed
• Timer counts down
• Party status shows all members
• Narrative updates
• Combat turn order shown

Realtime Behavior:

• Other players' actions appear immediately
• Turn advances when player acts
• HP updates across all clients
• Timer warnings appear

Combat Turn:

• Action buttons enabled only on your turn
• "Waiting for other players..." when not your turn
• Action submits via HTMX
• Combat log updates

Session Complete

Test Steps:

1. Complete multiplayer session
2. View rewards screen

Expected Results:

• Victory message displayed
• Completion time shown
• Rewards listed (gold, XP, items)
• Level up notification (if applicable)
• Party stats shown (MVP, etc.)

---

Responsive Design Testing

Mobile (320px - 480px)

Test on:

• iPhone SE (375x667)
• iPhone 12 (390x844)
• Android (360x640)

Check:

• Navigation menu collapses to hamburger
• Forms are usable (inputs not cut off)
• Buttons are tap-friendly (min 44x44px)
• Character cards stack vertically
• Combat UI scales properly
• No horizontal scroll

Tablet (481px - 768px)

Test on:

• iPad Mini (768x1024)
• iPad Air (820x1180)

Check:

• Layout uses medium breakpoint
• Character grid shows 2 columns
• Navigation partially expanded
• Touch targets adequate

Desktop (769px+)

Test on:

• 1024x768 (small desktop)
• 1920x1080 (standard desktop)
• 2560x1440 (large desktop)

Check:

• Full navigation visible
• Character grid shows 3-4 columns
• Combat UI uses full width
• No excessive whitespace

---

Accessibility Testing

Keyboard Navigation

Test Steps:

1. Navigate site using only keyboard (Tab, Shift+Tab, Enter, Space)
2. Test all interactive elements

Expected Results:

• All links/buttons focusable
• Focus indicator visible
• Logical tab order
• Forms submittable via Enter
• Modals closable via Escape

Screen Reader

Test with:

• NVDA (Windows)
• JAWS (Windows)
• VoiceOver (macOS/iOS)

Check:

• All images have alt text
• Form labels associated correctly
• ARIA labels on icon-only buttons
• Headings in logical hierarchy
• Focus announcements clear

Color Contrast

Tools:

• WAVE (browser extension)
• axe DevTools (browser extension)

Check:

• Text contrast ≥ 4.5:1 (AA)
• Large text contrast ≥ 3:1 (AA)
• Interactive elements have visible focus
• Color not sole indicator (e.g., errors)

---

HTMX Specific Testing

Form Submission

Test:

• Form submits without page reload
• Success response replaces form
• Error response shows validation
• Loading indicator appears
• Double-submit prevented

Delete Actions

Test:

• Confirmation dialog appears
• Element removed on success
• Error message on failure
• No page reload

Live Search

Test:

• Search triggers after typing stops (debounce)
• Results update without reload
• Loading indicator shown
• Empty state displayed correctly

Polling

Test:

• Content updates at interval
• Polling stops when condition met
• Network errors handled gracefully

Realtime + HTMX Hybrid

Test:

• Appwrite Realtime triggers HTMX reload
• Multiple browser tabs sync
• No duplicate updates
• Disconnection handled

---

Error Handling Testing

API Errors

Simulate:

• 400 Bad Request
• 401 Unauthorized
• 403 Forbidden
• 404 Not Found
• 500 Internal Server Error

Expected:

• User-friendly error message displayed
• Error logged to console (dev only)
• No sensitive data exposed
• Retry option available (if applicable)

Network Errors

Simulate:

• Disconnect network
• Slow 3G connection
• API backend down

Expected:

• Loading indicator appears
• Timeout after reasonable delay
• Error message displayed
• Fallback behavior (if applicable)

---

Performance Testing

Page Load Speed

Test:

• First contentful paint < 1.5s
• Time to interactive < 3s
• No layout shift (CLS < 0.1)

Tools:

• Chrome DevTools (Lighthouse)
• WebPageTest.org

HTMX Requests

Test:

• Requests complete < 500ms (local)
• Debouncing prevents spam
• Caching used where appropriate

---

Browser Compatibility

Feature Detection

Test:

• Works without JavaScript (forms submit)
• WebSocket support detected
• Fallback to polling if no WebSocket
• HTMX gracefully degrades

Browser-Specific Issues

Chrome:

• HTMX works correctly
• Realtime WebSocket stable

Firefox:

• All features functional
• No console errors

Safari:

• WebSocket support
• Form validation
• CSS grid/flexbox

Edge:

• All features functional

---

Security Testing

Authentication

Test:

• Protected routes redirect to login
• Session timeout works
• Cannot access other users' data
• CSRF protection enabled on forms

Input Validation

Test:

• XSS prevention (input sanitized)
• SQL injection prevention (API handles)
• File upload validation (if applicable)
• Rate limiting enforced

---

Testing Checklist Template

Copy this template for each release:

## Release X.X.X Testing Checklist

**Tester:** [Your Name]
**Date:** [YYYY-MM-DD]
**Environment:** [Local / Staging / Production]
**Browser:** [Chrome / Firefox / Safari / Edge]

### Authentication
- [ ] Registration works
- [ ] Login works
- [ ] Logout works

### Characters
- [ ] Create character
- [ ] View character list
- [ ] Edit character
- [ ] Delete character

### Sessions
- [ ] Create solo session
- [ ] Active session UI
- [ ] Combat works
- [ ] Session history

### Multiplayer
- [ ] Create multiplayer session
- [ ] Lobby (host)
- [ ] Lobby (player)
- [ ] Active multiplayer session
- [ ] Session complete

### Responsive
- [ ] Mobile (375px)
- [ ] Tablet (768px)
- [ ] Desktop (1920px)

### Accessibility
- [ ] Keyboard navigation
- [ ] Screen reader compatible
- [ ] Color contrast

### Performance
- [ ] Page load < 3s
- [ ] No console errors
- [ ] HTMX requests fast

### Notes:
[Any issues found]

---

Reporting Issues

Issue Template

**Title:** [Brief description]

**Environment:**
- Browser: [Chrome 120]
- OS: [Windows 11]
- Screen Size: [1920x1080]

**Steps to Reproduce:**
1. Navigate to `/characters`
2. Click "Delete" on character card
3. Confirm deletion

**Expected Result:**
Character should be deleted and removed from list.

**Actual Result:**
Character deleted but card still visible until page refresh.

**Console Errors:**
[Paste any console errors]

**Screenshots:**
[Attach screenshots if applicable]

**Severity:**
- [ ] Critical (blocking)
- [ ] High (major feature broken)
- [x] Medium (feature degraded)
- [ ] Low (cosmetic)

---

Related Documentation

• TEMPLATES.md - Template structure
• HTMX_PATTERNS.md - HTMX integration patterns
• /api/docs/API_TESTING.md - API backend testing

---

Document Version: 1.0 Created: November 18, 2025 Last Updated: November 18, 2025