Multi-Browser Sync Testing Guide

🎯 Objective

Verify that the intelligent sync with conflict resolution is working correctly across multiple browsers.

📋 Prerequisites

• ✅ Backend API is running (http://localhost:3000)
• ✅ useMockApi: false in environment configuration
• ✅ Corrupted queue cleared in ALL browsers
• ✅ Two or more browsers available for testing

🧪 Test Scenarios

Test 1: Basic Cross-Browser Sync ✅

Goal: Verify data syncs from one browser to another

Steps:

1. Browser A (Chrome):

   • Open app: http://localhost:5200
   • Login/continue as guest
   • Note space ID in dashboard
   • Create a universe called "test-universe-1"
   • Wait 5 seconds (auto-sync)

2. Browser B (Firefox):

   • Open app: http://localhost:5200
   • Login with same user credentials
   • Reload page
   • Expected: Should see "test-universe-1" ✅

3. Verify:

   • Same space ID in both browsers
   • "test-universe-1" visible in Browser B
   • No console errors in either browser

Status: ⬜ Not Tested | ✅ Passed | ❌ Failed

Test 2: Simultaneous Creation (Online) ✅

Goal: Verify concurrent operations merge correctly

Steps:

1. Browser A:

   • Create "universe-A"
   • Wait 5 seconds

2. Browser B (while A is syncing):

   • Create "universe-B"
   • Wait 5 seconds

3. Both Browsers:

   • Reload pages
   • Expected: Both should show universe-A AND universe-B ✅

4. Verify:

   • Browser A shows both universes
   • Browser B shows both universes
   • Backend has both (check network tab or backend logs)

Status: ⬜ Not Tested | ✅ Passed | ❌ Failed

Test 3: Offline Conflict Resolution 🔥

Goal: Verify intelligent merging when working offline

Steps:

1. Browser A:

   • Open DevTools → Network → Offline
   • Create "offline-universe-A"
   • Keep page open

2. Browser B:

   • Open DevTools → Network → Offline
   • Create "offline-universe-B"
   • Keep page open

3. Browser A:

   • Network → Online
   • Wait 10 seconds (allow sync)
   • Check: Backend should have "offline-universe-A"

4. Browser B:

   • Network → Online
   • Wait 10 seconds (allow sync)
   • Check: Backend should have BOTH universes

5. Browser A:

   • Reload page
   • Expected: Should show offline-universe-A AND offline-universe-B ✅

6. Verify:

   • No data loss (both universes present)
   • Console shows merge logs
   • Both browsers synchronized

Status: ⬜ Not Tested | ✅ Passed | ❌ Failed

Test 4: Pull Before Push ✅

Goal: Verify sync pulls backend data before pushing

Steps:

1. Browser A:

   • Create "universe-1", "universe-2", "universe-3"
   • Wait for sync

2. Browser B:

   • Clear local storage (but NOT IndexedDB)
   • Reload page
   • Expected: Should fetch all 3 universes from backend ✅

3. Browser B:

   • Create "universe-4"
   • Wait for sync

4. Browser A:

   • Reload page
   • Expected: Should show all 4 universes ✅

5. Verify:

   • Browser B pulled existing data before pushing
   • New data merged correctly
   • No duplicates

Status: ⬜ Not Tested | ✅ Passed | ❌ Failed

Test 5: Space Name Conflict Resolution ✅

Goal: Verify timestamp-based conflict resolution for scalars

Steps:

1. Browser A (offline):

   • Change space name to "Space-A-Name"

2. Browser B (offline):

   • Wait 2 seconds (ensure later timestamp)
   • Change space name to "Space-B-Name"

3. Browser A (online):

   • Sync → Backend has "Space-A-Name"

4. Browser B (online):

   • Sync → Backend should update to "Space-B-Name" (newer timestamp)

5. Browser A:

   • Reload
   • Expected: Should show "Space-B-Name" (newer wins) ✅

6. Verify:

   • Newer timestamp wins
   • Both browsers show same name
   • Console shows merge decision logs

Status: ⬜ Not Tested | ✅ Passed | ❌ Failed

Test 6: Array Deduplication ✅

Goal: Verify union merge doesn't create duplicates

Steps:

1. Setup:

   • Browser A has universe with ID "12345"
   • Backend has universe with ID "12345"

2. Browser A (offline):

   • Create another universe "67890"
   • Local now has ["12345", "67890"]

3. Browser A (online):

   • Sync
   • Expected: Backend should have ["12345", "67890"] (no duplicate "12345")

4. Verify:

   • No duplicate universe IDs
   • Console shows array merge with correct count
   • Backend has unique IDs only

Status: ⬜ Not Tested | ✅ Passed | ❌ Failed

🔍 Monitoring During Tests

Console Logs to Watch For

✅ Good Signs:

[SyncEngine] 🔄 Starting sync...
[SyncEngine] 📤 Pushing X operations to backend
[SyncEngine] 📥 Pulling changes from backend
[SyncEngine] ✅ Pulled and merged space from backend
[SyncEngine] Array merge: local: 2, remote: 1, merged: 3, added: 1
[SyncEngine] ✅ Sync complete

❌ Bad Signs:

⚠️ Unknown entity type: undefined
❌ Failed to sync operation
Sync failed: Network error

Network Tab

Watch for these API calls:

• GET /api/spaces/:id ← Pull
• PUT /api/spaces/:id ← Push
• POST /api/spaces/initialize ← Initial setup

Backend Logs

Should show:

[SpacesService] Updating space: 69067c087ebb621cd9ff8e3f
[SpacesService] ✅ Space updated with X universes

🐛 Debugging Failed Tests

Test Failed: Data Not Syncing

Check:

1. Is backend running? (http://localhost:3000/api/health)
2. Is useMockApi: false?
3. Are JWT tokens valid? (check Application → Cookies)
4. Is sync enabled? (check console for "Sync enabled: true")

Fix:

• Restart backend
• Clear cookies and re-authenticate
• Check environment configuration

Test Failed: Merge Not Working

Check:

1. Console shows "Pull from backend not implemented yet"? (old code!)
2. Console shows "Array merge" logs? (should!)
3. Backend data matches what you expect? (check via network tab)

Fix:

• Verify code changes were applied
• Hard reload (Ctrl+Shift+R)
• Check git status for uncommitted changes

Test Failed: Console Errors

Check:

1. Still seeing "undefined entity" errors? (corrupted queue!)
2. Authentication errors? (JWT expired)
3. Network errors? (backend down)

Fix:

• Run clear queue script again
• Re-authenticate (logout/login)
• Restart backend

✅ Success Criteria

All tests should pass with:

• No console errors
• Data syncs across browsers
• No data loss in conflict scenarios
• Arrays merge correctly (no duplicates)
• Timestamp-based resolution works
• Offline→Online sync works
• Backend matches all clients

📊 Test Results Template

Copy this template to track your results:

## Test Results - [Date]

### Test 1: Basic Cross-Browser Sync
- Status: ⬜ Not Tested | ✅ Passed | ❌ Failed
- Notes: 

### Test 2: Simultaneous Creation
- Status: ⬜ Not Tested | ✅ Passed | ❌ Failed
- Notes:

### Test 3: Offline Conflict Resolution
- Status: ⬜ Not Tested | ✅ Passed | ❌ Failed
- Notes:

### Test 4: Pull Before Push
- Status: ⬜ Not Tested | ✅ Passed | ❌ Failed
- Notes:

### Test 5: Space Name Conflict
- Status: ⬜ Not Tested | ✅ Passed | ❌ Failed
- Notes:

### Test 6: Array Deduplication
- Status: ⬜ Not Tested | ✅ Passed | ❌ Failed
- Notes:

### Overall Result
- All tests passed: ✅ | ❌
- Issues found: 
- Next steps:

🚀 After Testing

If All Tests Pass ✅

1. Commit changes with message:

   fix: implement intelligent multi-browser sync with conflict resolution
   
   - Implement pullFromBackend with intelligent merging
   - Add union merge for universeIds arrays
   - Add timestamp-based conflict resolution for scalars
   - Add getSpace(id) API method
   - Create comprehensive documentation
   
   Fixes multi-browser synchronization issues
   

2. Update status in related documents

3. Share with team for review

If Tests Fail ❌

1. Document the failure (what happened, expected vs actual)
2. Check debugging section above
3. Review console logs for clues
4. Test in isolation (single browser first)

📚 Related Documentation

• Multi-Browser Sync Fix Complete
• Offline-First Conflict Resolution
• Clear Corrupted Queue Script
• Final Architecture Summary

Last Updated: November 17, 2025
Status: Ready for Testing
Estimated Time: 30-45 minutes for all tests