# 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

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

```markdown
## 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

```markdown
**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](TEMPLATES.md)** - Template structure
- **[HTMX_PATTERNS.md](HTMX_PATTERNS.md)** - HTMX integration patterns
- **[/api/docs/API_TESTING.md](../../api/docs/API_TESTING.md)** - API backend testing

---

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