spotlightcam/docs/WEBRTC_TESTING_GUIDE.md

# WebRTC P2P File Transfer - Testing Guide

## Prerequisites

You need **TWO browser windows/tabs** or **TWO different devices** to test P2P file transfer:
- User A (sender)
- User B (receiver)

## Test Setup

### 1. Start the application

```bash
docker compose up --build
```

### 2. Login as two different users

**Window/Tab 1 - User A:**
- Email: `john@example.com`
- Password: `Dance123!`

**Window/Tab 2 - User B:**
- Email: `sarah@example.com`
- Password: `Swing456!`

## Test Scenarios

### Test 1: Create Match & Accept

**User A (john_dancer):**
1. Go to Events page
2. Click on "Warsaw Dance Festival 2025"
3. In event chat, click on a user (e.g., sarah_swings)
4. Click "Request Match"
5. Wait for acceptance

**User B (sarah_swings):**
1. You should receive a notification about match request
2. Go to Matches page (or click notification)
3. Accept the match request
4. Click on the match to open private chat

**Both users should now see:**
- Private match chat room
- WebRTC status: "Ready to connect"
- "Send video (WebRTC)" button

---

### Test 2: WebRTC Connection Establishment

**User A (initiator):**
1. In match chat, click "Send video (WebRTC)" button
2. Select a video file (any size, but start with small ~5-10MB for testing)
3. Click "Send video (P2P)" button in the popup

**Expected behavior:**
- User A: WebRTC status changes to "Connecting..."
- User A: Creates WebRTC offer and sends via Socket.IO
- User B: Receives offer and creates answer automatically
- Both: Exchange ICE candidates
- Both: WebRTC status changes to "Connected (P2P)" with green indicator
- Both: See "🔒 E2E Encrypted (DTLS)" in status bar

**Console logs to check (F12 Developer Tools):**
```
User A:
📤 Sent WebRTC offer
📤 Sent ICE candidate (multiple times)
✅ DataChannel opened
✅ RTCPeerConnection initialized

User B:
📥 Received WebRTC offer from: [userId]
📤 Sent WebRTC answer
📥 Received ICE candidate from: [userId]
✅ DataChannel received
✅ DataChannel opened
```

---

### Test 3: P2P File Transfer

**User A (sender):**
1. After connection established, file transfer should start automatically
2. Watch progress bar (0% → 100%)
3. See console logs showing chunks being sent

**User B (receiver):**
1. See "📥 Receiving: [filename]" in status bar
2. Watch progress bar (0% → 100%)
3. File should **automatically download** when complete
4. Check Downloads folder for the file

**Console logs:**
```
User A (sender):
📤 Sent file metadata: {fileName: "...", fileSize: ..., fileType: "video/..."}
📤 Sent chunk 1/X (Y%)
📤 Sent chunk 2/X (Y%)
...
✅ File transfer complete: [filename]

User B (receiver):
📥 Receiving file: [filename]
📥 Received chunk 1/X (Y%)
📥 Received chunk 2/X (Y%)
...
✅ File received and downloaded: [filename]
```

**Expected behavior:**
- Progress updates in real-time for both users
- Transfer speed depends on connection (typically 1-5 MB/s on local network)
- After completion:
  - User A: Progress resets, selected file cleared
  - User B: File automatically downloads
  - Chat message appears: "📹 Video sent: [filename] ([size] MB)"

---

### Test 4: Test Different File Sizes

Try transferring:
- ✅ Small video (~5-10 MB) - should take 5-15 seconds
- ✅ Medium video (~50-100 MB) - should take 1-2 minutes
- ✅ Large video (~500 MB) - should take 5-10 minutes

**Note:** WebRTC DataChannel is reliable and will retry failed chunks automatically.

---

### Test 5: Connection Recovery

**Test scenario:** What happens if connection drops during transfer?

1. Start a file transfer
2. During transfer, close User B's browser tab
3. Reopen User B's tab and login again
4. Go back to the match chat

**Expected behavior:**
- Transfer fails on User A's side
- User needs to manually restart the transfer
- Connection can be re-established by clicking "Send video (WebRTC)" again

---

### Test 6: Multiple Files

**Test scenario:** Send multiple files in the same session

1. Send first file (wait for completion)
2. Select and send second file
3. Repeat

**Expected behavior:**
- Each file transfer works independently
- Connection stays open after first transfer (if both users stay in chat)
- Subsequent transfers are faster (no reconnection needed)

---

## Troubleshooting

### Problem: "Connection timeout" error

**Possible causes:**
- Network firewall blocking WebRTC
- No STUN/TURN server reachable
- Both users behind symmetric NAT

**Solution:**
- Check browser console for errors
- Try on different network
- Ensure both users are on same local network (easier for testing)

### Problem: Connection stays "Connecting..." forever

**Check:**
1. Both users are in the same match chat
2. Socket.IO is connected (check "Write a message..." field - should not be disabled)
3. Browser console for WebRTC errors
4. Try refreshing both browser windows

### Problem: File doesn't download on receiver side

**Check:**
1. Browser's download permissions
2. Console for errors
3. File might be blocked by popup blocker

### Problem: "DataChannel is not open" error

**Solution:**
- Wait for connection to show "Connected (P2P)" before clicking "Send video (P2P)"
- If connection fails, try refreshing and reconnecting

---

## Network Requirements

### Local Network Testing (Recommended for first test)
- Both users on same WiFi/LAN
- No special configuration needed
- STUN servers will find local network path

### Internet Testing (Different networks)
- STUN servers help with most NAT types
- May fail with symmetric NAT on both sides
- Consider adding TURN server for production (relay fallback)

---

## Success Indicators

✅ **Connection successful if:**
- Status shows "Connected (P2P)" with green dot
- Console shows "DataChannel opened"
- No errors in console

✅ **Transfer successful if:**
- Progress bar reaches 100% on both sides
- Receiver gets automatic download
- Chat message appears with file info
- File size matches original

---

## Performance Metrics

**Expected performance on local network:**
- Connection time: 2-5 seconds
- Transfer speed: 5-20 MB/s
- Chunk size: 16 KB
- Overhead: Minimal (<1% for metadata)

**Expected performance over internet:**
- Connection time: 3-10 seconds
- Transfer speed: 1-10 MB/s (depends on uplink/downlink)
- More ICE candidates exchanged

---

## Browser Compatibility

✅ **Tested browsers:**
- Chrome 90+ (recommended)
- Firefox 88+
- Edge 90+
- Safari 14+ (may have limitations)

❌ **Not supported:**
- Internet Explorer
- Very old browser versions

---

## Advanced: Monitor WebRTC Stats

Open browser console and run:

```javascript
// Get peer connection stats (paste in console during active connection)
const pc = window.peerConnectionRef; // You'd need to expose this for debugging
if (pc) {
  pc.getStats().then(stats => {
    stats.forEach(stat => console.log(stat));
  });
}
```

Look for:
- `candidate-pair` - shows selected ICE candidate pair
- `data-channel` - shows bytes sent/received
- `transport` - shows DTLS state

---

## Next Steps After Testing

If everything works:
1. ✅ Mark WebRTC implementation as complete
2. Consider adding TURN server for production
3. Add UI improvements (connection retry button, transfer history)
4. Add file type validation (video only)
5. Add file size limits
6. Add analytics/telemetry for WebRTC success rate

If issues found:
1. Document the exact error messages
2. Check network environment (NAT type, firewall)
3. Consider TURN server for problematic networks
4. Add more error handling and user feedback

---

**Happy Testing! 🚀**