diff --git a/.planning/phases/11-chat-finalization/11-02-UAT-CHECKLIST.md b/.planning/phases/11-chat-finalization/11-02-UAT-CHECKLIST.md new file mode 100644 index 000000000..d0ce441d6 --- /dev/null +++ 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:** _______________