docs(11-02): prepare comprehensive UAT checklist for chat finalization

- Created 11-02-UAT-CHECKLIST.md with 50+ test cases across 9 categories - Automated test suite: 29+ Playwright tests - Manual UAT categories: Initialization, Message Display, Composition, Receiving, Read/Unread Tracking, Error Handling, Performance, Accessibility, Edge Cases - Regression checks for Backing Track and JamTrack players - Test environment requirements documented - Issue tracking template (P0/P1/P2/P3 severity levels)
2026-01-29 01:04:56 +05:30 · 2026-01-29 01:04:56 +05:30 · f2ccce86f7
parent a401285940
commit f2ccce86f7
1 changed files with 387 additions and 0 deletions
--- a/.planning/phases/11-chat-finalization/11-02-UAT-CHECKLIST.md
+++ b/.planning/phases/11-chat-finalization/11-02-UAT-CHECKLIST.md
@ -0,0 +1,387 @@
+# 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:** _______________