rekordbox-viewer/TESTING_GUIDE.md

# 🧪 S3 Music Storage Testing Guide

## 🎯 Overview

This guide will help you test the complete S3 music storage and matching system, including:
- Local MinIO setup
- Music file uploads
- Song matching with original file paths
- Browser playback
- Pure Rekordbox XML export

## 🚀 Quick Start

### 1. Start the Infrastructure

```bash
# Start MinIO and MongoDB
docker-compose -f docker-compose.dev.yml up -d

# Verify services are running
docker ps
```

You should see:
- `minio` container running on port 9000
- `minio-client` container (for setup)
- `mongodb` container running on port 27017

### 2. Install Dependencies

```bash
# Backend dependencies
cd packages/backend
npm install

# Frontend dependencies
cd ../frontend
npm install
```

### 3. Test S3 Connection

```bash
# Test S3 service connection
cd packages/backend
node test-s3.js
```

Expected output:
```
✅ S3 connection successful
✅ Bucket 'music-files' created/verified
✅ Audio metadata service working
```

### 4. Run Complete Setup Test

```bash
# From the root directory
node test-complete-setup.mjs
```

This will test:
- Environment variables
- Docker services
- S3 connection
- Audio metadata service
- Port availability
- API endpoints (when backend is running)

## 📋 Step-by-Step Testing

### Phase 1: Basic Setup Testing

#### 1.1 Verify MinIO Access
- Open browser: http://localhost:9000
- Login: `minioadmin` / `minioadmin`
- Verify bucket `music-files` exists

#### 1.2 Start Backend
```bash
cd packages/backend
npm run dev
```

Test endpoints:
```bash
# Health check
curl http://localhost:3000/api/health

# Should show S3 configuration
```

#### 1.3 Start Frontend
```bash
cd packages/frontend
npm run dev
```

- Open: http://localhost:5173
- Navigate to "Music Storage" tab

### Phase 2: XML Import Testing

#### 2.1 Import Rekordbox XML
1. Go to "Configuration" page
2. Upload your `testfiles/master_collection_23-5-2025.xml`
3. Verify songs are imported with original file paths

#### 2.2 Verify Original Paths
```bash
# Check database for original paths
curl http://localhost:3000/api/songs | jq '.songs[0].location'
```

Should show original file paths like:
```
"/Users/username/Music/Artist/Album/Song.mp3"
```

### Phase 3: Music File Upload Testing

#### 3.1 Upload Music Files
1. Go to "Music Storage" → "Music Library" tab
2. Drag & drop some MP3 files
3. Verify upload progress and completion

#### 3.2 Verify Upload Results
```bash
# Check uploaded files
curl http://localhost:3000/api/music/files | jq '.files[0]'
```

Should show:
```json
{
  "originalName": "Song.mp3",
  "title": "Song Title",
  "artist": "Artist Name",
  "s3Key": "music/uuid.mp3",
  "hasS3File": true
}
```

### Phase 4: Song Matching Testing

#### 4.1 Test Auto-Matching
1. Go to "Music Storage" → "Song Matching" tab
2. Click "Auto-Link Files"
3. Watch the matching process

#### 4.2 Verify Matching Results
```bash
# Check matching statistics
curl http://localhost:3000/api/matching/stats | jq
```

Should show:
```json
{
  "totalSongs": 100,
  "totalMusicFiles": 50,
  "matchedSongs": 45,
  "unmatchedSongs": 55,
  "matchRate": 0.45
}
```

#### 4.3 Test Location-Based Matching
Upload files with names that match original paths:
- Original: `/Music/Artist/Album/Song.mp3`
- Upload: `Song.mp3` → Should get high confidence match

### Phase 5: Browser Playback Testing

#### 5.1 Test Play Button
1. Go to "Songs" page
2. Look for songs with music file badges 🎵
3. Click play button on a song
4. Verify audio plays in browser

#### 5.2 Test Music Player
1. Go to "Music Storage" → "Music Library"
2. Click "Play" on uploaded files
3. Test player controls (play, pause, volume)

### Phase 6: XML Export Testing

#### 6.1 Export XML
```bash
# Export XML
curl http://localhost:3000/api/export/xml -o exported.xml
```

#### 6.2 Verify Pure Rekordbox XML
```bash
# Check XML structure
head -20 exported.xml
```

Should show:
```xml
<?xml version="1.0" encoding="UTF-8"?>

<DJ_PLAYLISTS Version="1.0.0">
  <PRODUCT Name="rekordbox" Version="7.1.3" Company="AlphaTheta"/>
  <COLLECTION Entries="100">
    <TRACK TrackID="123" Name="Song Title" Location="/original/path/to/file.mp3" ...>
      <!-- NO S3 data - pure Rekordbox XML -->
    </TRACK>
```

#### 6.3 Verify No S3 Data
```bash
# Check for S3 data (should find none)
grep -i "s3" exported.xml
# Should return no results
```

### Phase 7: Advanced Testing

#### 7.1 Test Manual Linking
1. Go to "Song Matching" → "Unmatched Music Files"
2. Click "Get suggestions" on a file
3. Manually link to a song
4. Verify link is created

#### 7.2 Test Unlinking
1. Go to "Song Matching" → "Songs with Music Files"
2. Click unlink button on a song
3. Verify S3 data is removed but original path preserved

#### 7.3 Test Multiple File Formats
Upload different audio formats:
- MP3 files
- WAV files
- FLAC files
- Verify metadata extraction works

## 🔍 Verification Checklist

### ✅ Infrastructure
- [ ] MinIO running on port 9000
- [ ] MongoDB running on port 27017
- [ ] Backend running on port 3000
- [ ] Frontend running on port 5173

### ✅ XML Import
- [ ] Songs imported with original file paths
- [ ] All metadata preserved
- [ ] Playlists imported correctly

### ✅ File Upload
- [ ] Files upload to S3 successfully
- [ ] Metadata extracted correctly
- [ ] Progress indicators work
- [ ] File list updates

### ✅ Song Matching
- [ ] Auto-matching works
- [ ] Location-based matching improves accuracy
- [ ] Manual linking works
- [ ] Unlinking preserves original data

### ✅ Browser Playback
- [ ] Play buttons appear for songs with files
- [ ] Audio plays in browser
- [ ] Player controls work
- [ ] Streaming URLs work

### ✅ XML Export
- [ ] XML exports successfully
- [ ] Original structure preserved
- [ ] No S3 data in export
- [ ] Rekordbox can re-import

## 🐛 Troubleshooting

### MinIO Connection Issues
```bash
# Check MinIO logs
docker logs minio

# Restart MinIO
docker-compose -f docker-compose.dev.yml restart minio
```

### Backend Issues
```bash
# Check backend logs
cd packages/backend
npm run dev

# Check environment variables
echo $S3_ENDPOINT
echo $S3_ACCESS_KEY_ID
```

### Frontend Issues
```bash
# Clear cache and restart
cd packages/frontend
rm -rf node_modules/.vite
npm run dev
```

### Database Issues
```bash
# Reset database
curl -X POST http://localhost:3000/api/reset

# Check MongoDB connection
docker exec -it mongodb mongosh
```

### Test Script Issues
```bash
# If you get module errors, ensure you're using the .mjs extension
node test-complete-setup.mjs

# Or run the backend test directly
cd packages/backend && node test-s3.js
```

## 📊 Expected Results

### After Complete Testing
- **Songs**: 100+ songs imported from XML
- **Music Files**: 50+ files uploaded to S3
- **Match Rate**: 70-90% (depending on file names)
- **Playable Songs**: Songs with music files show play buttons
- **XML Export**: Clean Rekordbox XML with no S3 data

### Performance Metrics
- **Upload Speed**: ~10-50 MB/s (depending on file size)
- **Matching Speed**: ~100 songs/second
- **Playback Latency**: <1 second
- **XML Export**: ~1000 songs in <5 seconds

## 🎉 Success Criteria

✅ **Infrastructure**: All services running correctly  
✅ **XML Import**: Original paths preserved  
✅ **File Upload**: S3 storage working  
✅ **Song Matching**: Location-based matching accurate  
✅ **Browser Playback**: Audio streaming working  
✅ **XML Export**: Pure Rekordbox XML  
✅ **Data Integrity**: No data loss, clean separation  

## 🚀 Next Steps

After successful testing:
1. **Production Setup**: Configure AWS S3 instead of MinIO
2. **Performance Tuning**: Optimize for larger libraries
3. **Advanced Features**: Add more matching algorithms
4. **User Experience**: Enhance UI/UX based on testing feedback

---

**Happy Testing! 🎵** 

This guide covers all aspects of the S3 music storage system. Follow the steps sequentially to ensure everything works correctly.