# Phase 11 Plan 2: Comprehensive UAT Checklist

**Purpose:** Validate chat feature meets all requirements before declaring v1.1 milestone complete

**Test Environment Requirements:**
- Rails backend running: `./runweb` (port 3000)
- jam-ui running: `cd jam-ui && npm run start` (port 4000)
- 2 browser tabs ready (for multi-user testing if needed)

---

## Automated Tests

**Run command:**
```bash
cd jam-ui
npm test -- test/chat/*.spec.ts
```

**Expected Results:**
- ✅ chat-window.spec.ts: 3 tests passing
- ✅ send-message.spec.ts: 7 tests passing
- ✅ receive-message.spec.ts: 4 tests passing
- ✅ unread-badge.spec.ts: 8 tests passing
- ✅ localStorage-persistence.spec.ts: 7 tests passing
- ✅ chat-button.spec.ts: tests passing

**Total:** 29+ Playwright integration tests

---

## Manual UAT Test Cases

### Category 1: Initialization & Window Management (6 tests)

**UAT-001: Click chat button → window opens**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Join session, click "Chat" button in top nav
- **Expected:** Chat window opens as modeless popup (WindowPortal)

**UAT-002: Window displays correct channel name**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open chat window, check header
- **Expected:** Header shows "Session Chat" (or session ID/name)

**UAT-003: Close button closes window**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Click X button in header
- **Expected:** Window closes, button still visible in nav

**UAT-004: Escape key closes window**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open window, press Escape key
- **Expected:** Window closes (NEW feature from Plan 11-01)

**UAT-005: Window position persists during session**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open window, drag to new position, close, reopen
- **Expected:** Window reopens at same position (WindowPortal feature)

**UAT-006: Rapid open/close doesn't cause errors**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Click chat button 10 times rapidly (open/close/open/close)
- **Expected:** No console errors, window responds correctly

---

### Category 2: Message Display & Formatting (5 tests)

**UAT-007: Messages display with all elements**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open chat with existing messages
- **Expected:** Each message shows avatar (initials), sender name, text, timestamp

**UAT-008: Timestamps format correctly**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** View messages from different time periods
- **Expected:** "Just now" → "5 min ago" → "Yesterday" → day name → MM/DD/YYYY

**UAT-009: Empty state shows before first message**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Join new session with no messages
- **Expected:** Shows "Start the conversation!" (updated in Plan 11-01)

**UAT-010: Long messages wrap properly**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Send message near 255 chars
- **Expected:** Text wraps to multiple lines, doesn't overflow container

**UAT-011: Multiple messages from same user display correctly**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Send 3 messages in a row
- **Expected:** All messages show avatar/name/timestamp (not grouped)

---

### Category 3: Message Composition & Sending (8 tests)

**UAT-012: Textarea accepts input**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Type text in textarea (1-255 chars)
- **Expected:** Input appears in textarea, Send button enables

**UAT-013: Character count displays correctly**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Type text and watch character count
- **Expected:** Shows "X/255" in real-time

**UAT-014: Character count turns yellow at 231 chars**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Type until character count reaches 231
- **Expected:** Count text changes to yellow color (warning)

**UAT-015: Character count turns red at 256+ chars**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Type until character count exceeds 255
- **Expected:** Count text changes to red, validation message appears

**UAT-016: Send button disabled when empty or over limit**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Try with empty textarea, then with 256+ chars
- **Expected:** Send button disabled in both cases

**UAT-017: Enter key sends message**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Type message, press Enter (without Shift)
- **Expected:** Message sends, textarea clears

**UAT-018: Shift+Enter inserts newline**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Type text, press Shift+Enter, type more text
- **Expected:** Newline inserted, message NOT sent

**UAT-019: Textarea clears after successful send**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Send message successfully
- **Expected:** Textarea clears, focus returns to textarea

---

### Category 4: Message Receiving (WebSocket) (5 tests)

**UAT-020: Message received via WebSocket appears in list**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Have another user send message (or simulate via Redux dispatch)
- **Expected:** Message appears in message list immediately

**UAT-021: Auto-scroll to bottom on new message (when at bottom)**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** View chat at bottom, receive new message
- **Expected:** List auto-scrolls to show new message

**UAT-022: No auto-scroll if user scrolled up**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Scroll up in message list, receive new message
- **Expected:** List does NOT auto-scroll (preserves user's position)

**UAT-023: Auto-scroll re-enables when user scrolls to bottom**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Scroll up, then manually scroll back to bottom, receive message
- **Expected:** Auto-scroll works again

**UAT-024: No duplicate messages**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Send message, observe after WebSocket echo
- **Expected:** Message appears once only (deduplication works)

---

### Category 5: Read/Unread Tracking (7 tests)

**UAT-025: Badge hidden when count = 0**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open chat window to reset count, close window
- **Expected:** Badge not visible on chat button

**UAT-026: Badge shows count when window closed**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Close window, have message arrive
- **Expected:** Badge appears with count "1"

**UAT-027: Badge shows "99+" when count >= 100**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Simulate 100+ unread messages (via Redux dispatch)
- **Expected:** Badge shows "99+" instead of exact count

**UAT-028: Badge resets to 0 when window opened**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Have unread messages, open chat window
- **Expected:** Badge disappears (count resets to 0)

**UAT-029: Badge increments when viewing different channel**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open window for channel A, receive message for channel A
- **Expected:** Badge does NOT increment (viewing active channel)

**UAT-030: Badge does NOT increment when viewing active channel**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open window, keep it open, receive message
- **Expected:** Badge does NOT increment (window is open)

**UAT-031: lastReadAt persists in localStorage**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open window, close, reload page, open DevTools → Application → Local Storage
- **Expected:** See 'jk_chat_lastReadAt' key with timestamp

---

### Category 6: Error Handling (6 tests)

**UAT-032: WebSocket disconnection shows yellow banner**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Disconnect WebSocket (stop backend or simulate), open chat
- **Expected:** Yellow warning banner at top "Unable to connect to chat server" (NEW in Plan 11-01)

**UAT-033: Banner disappears on reconnection**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Reconnect WebSocket, observe chat window
- **Expected:** Yellow banner disappears

**UAT-034: Send failure shows red error with retry button**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Disconnect backend, try to send message
- **Expected:** Red error box "Failed to send message. Please try again." with Retry button (NEW in Plan 11-01)

**UAT-035: Retry button works and clears error**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** After send failure, reconnect backend, click Retry
- **Expected:** Error clears, textarea re-enabled, can send message again

**UAT-036: fetchChatHistory failure shows error message**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Disconnect backend, open chat window
- **Expected:** Red error text "Failed to load messages" (NEW in Plan 11-01)

**UAT-037: Send button disabled when disconnected**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Disconnect WebSocket, observe composer
- **Expected:** Send button disabled, textarea shows disconnection warning

---

### Category 7: Performance (4 tests)

**UAT-038: 50+ messages render without lag**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Load chat with 50+ messages (seed database or simulate)
- **Expected:** Message list renders smoothly, no visible lag

**UAT-039: Auto-scroll smooth (no jank)**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Receive 10 messages rapidly
- **Expected:** Auto-scroll animations smooth, no visual jank

**UAT-040: Typing in textarea responsive**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Type rapidly in textarea
- **Expected:** No input delay, character count updates in real-time

**UAT-041: Window open/close fast**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open and close chat window
- **Expected:** <100ms perceived latency (feels instant)

---

### Category 8: Accessibility (5 tests)

**UAT-042: Tab order logical**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open window, press Tab repeatedly
- **Expected:** Focus moves: button → textarea → send → close (logical order)

**UAT-043: ARIA attributes present**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open DevTools → Accessibility inspector, examine chat elements
- **Expected:** role="dialog", aria-labelledby, aria-describedby on window; aria-invalid on textarea; aria-live on validation

**UAT-044: Escape key closes window (duplicate of UAT-004)**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open window, press Escape
- **Expected:** Window closes (NEW in Plan 11-01)

**UAT-045: Textarea auto-focuses on open**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open chat window
- **Expected:** Textarea receives focus automatically (NEW in Plan 11-01)

**UAT-046: Screen reader announces validation messages**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** (If VoiceOver available) Enable VoiceOver, type 256+ chars
- **Expected:** Screen reader announces "Character limit exceeded" via aria-live

---

### Category 9: Edge Cases (4 tests)

**UAT-047: Send while disconnected → button disabled**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Disconnect WebSocket, try to send
- **Expected:** Send button disabled, shows warning message

**UAT-048: Receive 10 messages rapidly → all appear**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Simulate 10 rapid WebSocket messages
- **Expected:** All 10 messages appear, badge updates correctly if window closed

**UAT-049: Open/close 10x rapidly → no errors**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Click chat button 10 times rapidly (same as UAT-006)
- **Expected:** No console errors, no memory leaks

**UAT-050: Page reload → lastReadAt persists, messages cleared**
- [ ] PASS / [ ] FAIL (P___) - _______________________
- **Steps:** Open chat, close, reload page, check localStorage
- **Expected:** lastReadAt timestamp still there, messages list empty (expected - no history persistence)

---

## Regression Checks

**Backing Track Player:**
- [ ] PASS / [ ] FAIL (P___) - Play/pause/seek/volume still work
- [ ] PASS / [ ] FAIL (P___) - No console errors when using Backing Track

**JamTrack Player:**
- [ ] PASS / [ ] FAIL (P___) - Download/sync/playback/mixdown still work
- [ ] PASS / [ ] FAIL (P___) - No console errors when using JamTrack

**Other Session Features:**
- [ ] PASS / [ ] FAIL (P___) - Session join/leave still works
- [ ] PASS / [ ] FAIL (P___) - No unrelated console errors

---

## Test Results Summary

**Automated Tests:** ___/29+ passing

**Manual Tests by Category:**
1. Initialization & Window Management: ___/6 PASS
2. Message Display & Formatting: ___/5 PASS
3. Message Composition & Sending: ___/8 PASS
4. Message Receiving (WebSocket): ___/5 PASS
5. Read/Unread Tracking: ___/7 PASS
6. Error Handling: ___/6 PASS
7. Performance: ___/4 PASS
8. Accessibility: ___/5 PASS
9. Edge Cases: ___/4 PASS

**Regression Checks:** ___/6 PASS

**Total Manual Tests:** ___/50 PASS

---

## Issues Found

### P0 (Critical - Blocks Release)
None expected at this stage

### P1 (High - Must Fix Before Release)
None expected at this stage

### P2 (Medium - Can Defer to Next Milestone)
- Example: [Description if any found]

### P3 (Low - Polish/Enhancement)
- Example: [Description if any found]

---

## Overall Assessment

**Status:** [ ] PASS (all P0/P1 resolved) / [ ] FAIL (P0/P1 issues remain)

**Notes:**
[Any additional observations or context]

**Ready for Production:** [ ] YES / [ ] NO

---

**Tested by:** _______________
**Date:** _______________
**Browser:** _______________
**OS:** _______________
