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

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:

// 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! 🚀