# UAT Checklist: v1.2 Session Attachments

**Milestone:** v1.2 Session Attachments
**Tester:** [To be filled]
**Date:** [To be filled]
**Environment:** Local development (jam-ui:4000, web:3000)

## Prerequisites

Before starting UAT:
- [ ] jam-ui running on http://beta.jamkazam.local:4000
- [ ] web (Rails) running on http://www.jamkazam.local:3000
- [ ] User account created and can log in
- [ ] Second user account for multi-user tests (optional but recommended)
- [ ] Test files prepared:
  - [ ] Small PDF file (< 10 MB)
  - [ ] Large file (> 10 MB) for error testing
  - [ ] Invalid file type (.exe, .zip) for error testing
  - [ ] Image file (.png or .jpg)
  - [ ] Audio file (.mp3 or .wav)

---

## 1. File Upload & Validation (REQ-1.x)

### REQ-1.1: Attach Button in Session Toolbar
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 1.1.1 | Navigate to active session | Attach button visible in toolbar | | |
| 1.1.2 | Click Attach button | Native OS file dialog opens | | |
| 1.1.3 | Button not visible outside session | No Attach button on dashboard/lobby | | |
| 1.1.4 | Upload in progress | Button shows disabled state | | |

### REQ-1.2: File Type Validation
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 1.2.1 | Select .pdf file | File accepted (no error) | | |
| 1.2.2 | Select .xml file | File accepted (no error) | | |
| 1.2.3 | Select .png file | File accepted (no error) | | |
| 1.2.4 | Select .mp3 file | File accepted (no error) | | |
| 1.2.5 | Select .exe file | Toast: "File type not supported..." | | |
| 1.2.6 | Select .zip file | Toast: "File type not supported..." | | |
| 1.2.7 | File dialog filter | Only approved types shown (when possible) | | |

### REQ-1.3: File Size Limit
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 1.3.1 | Select file < 10 MB | Upload starts successfully | | |
| 1.3.2 | Select file > 10 MB | Toast: "File size exceeds 10 MB limit" | | |
| 1.3.3 | Error prevents upload | Upload does NOT start for oversized file | | |
| 1.3.4 | Re-select after error | Can select different file after error | | |

### REQ-1.4: Upload Progress Indicator
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 1.4.1 | Start upload | Progress indicator appears in chat | | |
| 1.4.2 | During upload | Indicator shows filename being uploaded | | |
| 1.4.3 | Upload completes | Progress indicator disappears | | |
| 1.4.4 | Non-blocking | Can continue chatting during upload | | |

---

## 2. Chat Integration & Display (REQ-2.x)

### REQ-2.1: Attachment Message Format
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 2.1.1 | Upload complete | Message shows "[Name] attached [File]" | | |
| 2.1.2 | Timestamp display | Upload timestamp shown | | |
| 2.1.3 | Visual distinction | Attachment styled differently from text | | |

### REQ-2.2: Attachment Metadata Display
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 2.2.1 | Filename visible | Full filename with extension shown | | |
| 2.2.2 | File size visible | Size in KB or MB format | | |
| 2.2.3 | Uploader name | User name who uploaded shown | | |
| 2.2.4 | Timestamp | When attachment was uploaded | | |

### REQ-2.3: Attachment Icon/Indicator
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 2.3.1 | Attachment visual | Has paperclip icon or distinct styling | | |
| 2.3.2 | Different from text | Can easily distinguish from text messages | | |

### REQ-2.4: Clickable Attachment Links
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 2.4.1 | Click PDF attachment | Opens in new browser tab | | |
| 2.4.2 | Click image attachment | Opens/displays in new tab | | |
| 2.4.3 | Click audio attachment | Opens/plays in new tab | | |
| 2.4.4 | Link styling | Filename appears clickable (underline/color) | | |

### REQ-2.5: Chat History Includes Attachments
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 2.5.1 | Page refresh | Attachments visible after refresh | | |
| 2.5.2 | Join existing session | Previous attachments visible in chat | | |
| 2.5.3 | Chronological order | Attachments sorted with messages by time | | |

---

## 3. Real-time Communication (REQ-3.x)

### REQ-3.1: WebSocket Attachment Broadcast
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 3.1.1 | Multi-user upload | Other user sees attachment immediately | | |
| 3.1.2 | No refresh needed | Attachment appears without manual refresh | | |
| 3.1.3 | All participants | All musicians in session see attachment | | |

### REQ-3.2: Attachment Deduplication
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 3.2.1 | Uploader view | Uploader sees exactly ONE attachment message | | |
| 3.2.2 | Other user view | Other users see exactly ONE attachment message | | |
| 3.2.3 | No duplicates | Same attachment never appears twice | | |

---

## 4. File Viewing & Download (REQ-4.x)

### REQ-4.1: Open in New Browser Tab
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 4.1.1 | Click attachment | Opens in new tab (not same tab) | | |
| 4.1.2 | Session preserved | Original session page still open | | |

### REQ-4.2: Browser-Native Handling
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 4.2.1 | PDF file | Browser PDF viewer displays | | |
| 4.2.2 | Image file | Browser displays image inline | | |
| 4.2.3 | Audio file | Browser audio player shows | | |
| 4.2.4 | XML/TXT file | Browser displays or prompts download | | |

---

## 5. Error Handling & User Feedback (REQ-5.x)

### REQ-5.1: File Size Exceeded Error
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 5.1.1 | Select >10MB file | Toast appears immediately | | |
| 5.1.2 | Toast message | "File size exceeds 10 MB limit" | | |
| 5.1.3 | No upload attempt | Upload does NOT start | | |
| 5.1.4 | Recovery | Can select different file afterward | | |

### REQ-5.2: Invalid File Type Error
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 5.2.1 | Select .exe file | Toast appears immediately | | |
| 5.2.2 | Toast message | Contains "not supported" and allowed types | | |
| 5.2.3 | No upload attempt | Upload does NOT start | | |
| 5.2.4 | Recovery | Can select different file afterward | | |

### REQ-5.3: Upload Network Error
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 5.3.1 | Simulate network error | Toast: "Upload failed. Please try again." | | |
| 5.3.2 | Progress indicator | Disappears on error | | |
| 5.3.3 | No partial data | No corrupted attachment in chat | | |
| 5.3.4 | Retry possible | Can upload again after error | | |

### REQ-5.4: Upload Success Feedback
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 5.4.1 | Successful upload | Toast: "File uploaded successfully" | | |
| 5.4.2 | Attachment visible | Attachment appears in chat | | |
| 5.4.3 | Auto-dismiss | Success toast disappears after 3-5 seconds | | |

### REQ-5.5: Missing/Deleted File Handling
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 5.5.1 | Click deleted file | Toast: "File no longer available" | | |
| 5.5.2 | No app crash | Application remains stable | | |

---

## 6. Backend Integration (REQ-6.x)

### REQ-6.1: Use Existing MusicNotation API
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 6.1.1 | Upload completes | Backend returns 201 Created | | |
| 6.1.2 | Metadata returned | Response includes id, file_name, file_url | | |

### REQ-6.2: Attachment Type Classification
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 6.2.1 | Upload PDF | attachment_type = 'notation' | | |
| 6.2.2 | Upload audio | attachment_type = 'audio' | | |

### REQ-6.3: Session Association
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 6.3.1 | Upload in session | Attachment linked to correct session | | |
| 6.3.2 | Different session | Attachments don't appear in wrong session | | |

---

## 7. Performance & UX (REQ-7.x)

### REQ-7.1: Non-blocking Upload
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 7.1.1 | During upload | Can type chat messages | | |
| 7.1.2 | During upload | Can browse session UI | | |
| 7.1.3 | Progress visible | Upload indicator present but not intrusive | | |

### REQ-7.2: Chat Auto-scroll with Attachments
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 7.2.1 | New attachment | Chat scrolls to show new attachment | | |
| 7.2.2 | Same as messages | Scroll behavior matches text messages | | |

### REQ-7.3: Responsive Layout
| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| 7.3.1 | Long filename | Truncates with ellipsis | | |
| 7.3.2 | Hover on truncated | Full filename shown in tooltip | | |
| 7.3.3 | Window resize | Layout doesn't break | | |

---

## Edge Cases

| # | Test Case | Expected Result | Pass/Fail | Notes |
|---|-----------|-----------------|-----------|-------|
| E.1 | Rapid click attach | File dialog opens once | | |
| E.2 | Upload same file twice | Both uploads work independently | | |
| E.3 | Upload during disconnect | Error toast, no data corruption | | |
| E.4 | Very long filename (50+ chars) | Truncates properly, full name in tooltip | | |
| E.5 | Empty chat, first message is attachment | Displays correctly | | |

---

## Summary

| Section | Total Tests | Pass | Fail | Skip |
|---------|-------------|------|------|------|
| 1. File Upload & Validation | 15 | | | |
| 2. Chat Integration & Display | 14 | | | |
| 3. Real-time Communication | 6 | | | |
| 4. File Viewing & Download | 6 | | | |
| 5. Error Handling | 15 | | | |
| 6. Backend Integration | 5 | | | |
| 7. Performance & UX | 8 | | | |
| Edge Cases | 5 | | | |
| **TOTAL** | **74** | | | |

## Bug Report

### P0 (Blocker - Must fix before release)

| Bug ID | Description | Steps to Reproduce | Expected | Actual | Status |
|--------|-------------|-------------------|----------|--------|--------|
| | | | | | |

### P1 (High - Should fix before release)

| Bug ID | Description | Steps to Reproduce | Expected | Actual | Status |
|--------|-------------|-------------------|----------|--------|--------|
| | | | | | |

### P2 (Medium - Can fix after release)

| Bug ID | Description | Steps to Reproduce | Expected | Actual | Status |
|--------|-------------|-------------------|----------|--------|--------|
| | | | | | |

---

## Sign-off

- [ ] All P0 bugs resolved
- [ ] All P1 bugs resolved or documented with workaround
- [ ] UAT pass rate >= 95%
- [ ] Product owner approval (if applicable)

**UAT Result:** [ ] PASS / [ ] FAIL

**Tester Signature:** _________________________ **Date:** _________
