# Testing Guide - SamCloud Music

**Purpose**: Step-by-step testing procedures to validate functionality  
**Last Updated**: July 1, 2025  
**Status**: Current Session Testing

---

## 🧪 Quick Test Suite

### **1. Application Startup Test**
```bash
# Navigate to project directory
cd "/Volumes/SamMgmt/Containers/SamCloud Music"

# Start the application
docker-compose up --build

# Expected: Container starts without errors
# Expected: App accessible at http://localhost:6544
```

**Success Criteria**:
- ✅ No startup errors in console
- ✅ App loads at port 6544
- ✅ All 5 tabs visible: Listen, Library, Search, Downloads, Settings

### **2. Navigation Test**
**Open**: http://localhost:6544

**Test Top Navigation**:
1. Click each tab: Listen, Library, Search, Downloads, Settings
2. Verify content changes for each tab
3. Check URL does not change (SPA behavior)

**Test Bottom Navigation**:
1. Click each bottom nav icon: 🎵 📚 🔍 📥 ⚙️
2. Verify same tab switching as top nav
3. Check active state highlighting

**Success Criteria**:
- ✅ Both navigation systems work
- ✅ No JavaScript errors in console
- ✅ Active states display correctly

### **3. Jellyfin Authentication Test**
**Steps**:
1. Go to Settings tab
2. Enter Jellyfin server details:
   - Server URL: `https://jellyfin.samcloud.ca`
   - Username: `[your_username]`
   - Password: `[your_password]`
3. Click "Save Settings"
4. Check console for authentication result

**Success Criteria**:
- ✅ No 500 errors during auth
- ✅ Settings persist in localStorage
- ✅ Authentication success message

### **4. Library Loading Test**
**Prerequisites**: Successful authentication

**Steps**:
1. Go to Library tab
2. Wait for library to load
3. Check for library items display
4. Test tab switching: Songs, Albums, Artists, Playlists

**Success Criteria**:
- ✅ No 500 errors on `/api/jellyfin/library`
- ✅ Library items display correctly
- ✅ All filter tabs work (no "All" tab)

### **5. Download Functionality Test**
**Steps**:
1. Go to Search tab
2. Enter a song/artist to search
3. Click download button
4. Go to Downloads tab
5. Monitor progress

**Success Criteria**:
- ✅ Download initiates successfully
- ✅ Progress bar updates in real-time
- ✅ Files saved to correct folder structure
- ✅ Download history displays

---

## 🔍 Debugging Tests

### **Console Error Check**
**Steps**:
1. Open browser DevTools (F12)
2. Go to Console tab
3. Navigate through all app tabs
4. Look for JavaScript errors

**Expected Errors** (non-critical):
- Source map 404s (acceptable)
- WebSocket connection warnings (if not using real-time features)

**Critical Errors** (must fix):
- ❌ Uninitialized variable errors
- ❌ TypeError in tab switching
- ❌ Failed API calls (except expected auth failures)

### **Network Tab Check**
**Steps**:
1. Open DevTools → Network tab
2. Refresh page
3. Navigate to Library tab (with auth)
4. Check API call responses

**Expected Calls**:
- ✅ `GET /` → 200 OK
- ✅ `POST /api/jellyfin/auth` → 200 OK (with valid creds)
- ⚠️ `GET /api/jellyfin/library` → Testing (should be 200, currently 500)

### **LocalStorage Check**
**Steps**:
1. Open DevTools → Application tab
2. Go to Local Storage → localhost:6544
3. Check for Jellyfin config persistence

**Expected Entries**:
- `jellyfin_server_url`
- `jellyfin_username`
- `jellyfin_password` (encrypted/hashed)
- `jellyfin_authenticated` (boolean)

---

## 🚨 Known Issues During Testing

### **Issue 1: Jellyfin Library 500 Error**
**Test**: Library loading after authentication  
**Error**: `AttributeError: 'str' object has no attribute 'get'`  
**Status**: 🔄 Fix in progress  
**Workaround**: Check backend logs for detailed error

### **Issue 2: Navigation Conflicts**
**Test**: Both top/bottom navigation  
**Symptom**: Possible event listener conflicts  
**Status**: 🔄 Monitoring for issues  
**Workaround**: Use top navigation if bottom fails

### **Issue 3: WebSocket Warnings**
**Test**: Download progress updates  
**Symptom**: Connection warnings in console  
**Status**: ⚠️ Low priority  
**Impact**: Progress updates may be delayed

---

## 📊 Test Results Template

```
## Test Session: [DATE/TIME]

### Application Startup: ✅/❌
- Container startup: ✅/❌
- Port 6544 accessible: ✅/❌  
- UI loads completely: ✅/❌

### Navigation: ✅/❌
- Top navigation: ✅/❌
- Bottom navigation: ✅/❌
- Tab switching: ✅/❌

### Authentication: ✅/❌
- Settings form: ✅/❌
- Jellyfin auth: ✅/❌
- localStorage: ✅/❌

### Library: ✅/❌
- Library loading: ✅/❌
- Item display: ✅/❌
- Filter tabs: ✅/❌

### Downloads: ✅/❌
- Search function: ✅/❌
- Download initiation: ✅/❌
- Progress tracking: ✅/❌

### Critical Issues Found:
- [List any blocking issues]

### Non-Critical Issues:
- [List minor issues]

### Next Actions:
- [What needs to be fixed next]
```

---

## 🔗 Related Documentation

- [Known Issues](../troubleshooting/known-issues.md) - Current bugs and fixes
- [API Reference](api-reference.md) - Endpoint documentation  
- [Architecture](architecture.md) - System design
- [Progress Log](../development/progress-log.md) - Development history

---

**Testing Notes**: Always test in order: Startup → Navigation → Auth → Library → Downloads  
**Critical Path**: Must fix library loading before testing music player functionality