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

# 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

# Backend dependencies
cd packages/backend
npm install

# Frontend dependencies
cd ../frontend
npm install

3. Test S3 Connection

# 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

# 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

cd packages/backend
npm run dev

Test endpoints:

# Health check
curl http://localhost:3000/api/health

# Should show S3 configuration

1.3 Start Frontend

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

# 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

# Check uploaded files
curl http://localhost:3000/api/music/files | jq '.files[0]'

Should show:

{
  "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

# Check matching statistics
curl http://localhost:3000/api/matching/stats | jq

Should show:

{
  "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

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

6.2 Verify Pure Rekordbox XML

# Check XML structure
head -20 exported.xml

Should show:

<?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

# 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

# Check MinIO logs
docker logs minio

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

Backend Issues

# Check backend logs
cd packages/backend
npm run dev

# Check environment variables
echo $S3_ENDPOINT
echo $S3_ACCESS_KEY_ID

Frontend Issues

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

Database Issues

# Reset database
curl -X POST http://localhost:3000/api/reset

# Check MongoDB connection
docker exec -it mongodb mongosh

Test Script Issues

# 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.