Trackeep/Others/mobile-app/SYNC_TEST_GUIDE.md

Mobile App Sync Testing Guide

Overview

This guide helps you test the bi-directional synchronization between the Trackeep mobile app and web dashboard.

Prerequisites

1. Backend Server: Ensure your Trackeep backend is running
2. Web Dashboard: Access the web dashboard at http://localhost:3000 (or your configured URL)
3. Mobile App: Run the React Native app using:

   npm start
   npm run android  # or npm run ios
   

First Launch Setup

1. Server Configuration: On first launch, the mobile app will show the server setup screen:

   • Enter your backend URL (e.g., http://localhost:8080)
   • Enter your credentials
   • Test connection before completing setup

2. Authentication: After setup, you'll be redirected to login with your existing credentials

Testing Real-Time Sync

Test 1: Create Content on Mobile, Verify on Web

1. On Mobile App:

   • Open the Dashboard
   • Tap the FAB (+) button
   • Create a new task, bookmark, or note
   • Verify it appears in the mobile dashboard

2. On Web Dashboard:

   • Navigate to the corresponding section (Tasks, Bookmarks, or Notes)
   • The new item should appear within seconds (if WebSocket is connected)
   • If not, refresh the page to see the synced item

Test 2: Create Content on Web, Verify on Mobile

1. On Web Dashboard:

   • Create a new task, bookmark, or note
   • Save the item

2. On Mobile App:

   • The item should appear automatically if real-time sync is working
   • Pull to refresh on the dashboard to force sync
   • Check the specific section to verify the item appears

Test 3: Offline Mode Testing

1. Enable Offline Mode:

   • Turn off internet connection on your mobile device
   • The app should show "🔴 Offline" status

2. Create Content Offline:

   • Create several tasks, bookmarks, or notes
   • Notice the pending changes counter increases

3. Restore Connection:

   • Turn internet back on
   • App should show "🟢 Connected" and auto-sync
   • Verify items appear on web dashboard

Test 4: Conflict Resolution

1. Simulate Conflict:
   • Create the same item on both mobile and web while offline
   • Bring both online simultaneously
   • Verify how conflicts are resolved (last write wins or merge)

Key Features to Test

Real-Time Updates

• ✅ WebSocket connection status
• ✅ Instant updates across devices
• ✅ Connection recovery after disconnection

Offline Support

• ✅ Offline data persistence
• ✅ Pending changes tracking
• ✅ Automatic sync when online
• ✅ Manual sync button

Data Integrity

• ✅ All data types sync correctly (tasks, bookmarks, notes)
• ✅ Timestamps preserved
• ✅ User associations maintained
• ✅ Tags and metadata sync

Troubleshooting

Common Issues

1. WebSocket Connection Failed:

   • Check if backend WebSocket endpoint is accessible
   • Verify firewall settings
   • Check browser console for WebSocket errors

2. Sync Not Working:

   • Verify server URL in mobile app settings
   • Check authentication tokens
   • Review backend logs for sync errors

3. Offline Mode Not Detected:

   • Check network permissions on mobile device
   • Verify NetInfo plugin is working
   • Test with airplane mode

Debug Tools

1. Mobile App Debugging:

   # Enable debug mode
   npx react-native log-android
   npx react-native log-ios
   

2. Backend Logs:

   • Monitor sync endpoint logs
   • Check WebSocket connection logs
   • Review database transaction logs

3. Browser Console:

   • Monitor WebSocket connections
   • Check for real-time update events
   • Verify API responses

Performance Testing

Test Scenarios

1. Large Dataset Sync:

   • Create 100+ items on one device
   • Measure sync time to other device
   • Verify no data loss

2. Concurrent Updates:

   • Multiple users updating same data
   • Test conflict resolution
   • Verify data consistency

3. Network Conditions:

   • Test on slow networks (2G/3G)
   • Test with intermittent connectivity
   • Verify sync resilience

Expected Results

Successful Sync Indicators

1. Mobile App:

   • Status shows "🟢 Connected"
   • Last sync time updates
   • No pending changes counter
   • Real-time updates received

2. Web Dashboard:

   • New items appear without refresh
   • WebSocket connection established
   • No sync errors in console

Performance Benchmarks

• Small items (< 1KB): Should sync within 1-2 seconds
• Large items (> 100KB): Should sync within 5-10 seconds
• Batch sync (50+ items): Should complete within 30 seconds

Automated Testing

For comprehensive testing, consider implementing:

1. Unit Tests:

   • Sync logic validation
   • Offline queue management
   • Conflict resolution

2. Integration Tests:

   • End-to-end sync workflows
   • WebSocket connection testing
   • API integration validation

3. E2E Tests:

   • Multi-device sync scenarios
   • Offline/online transitions
   • User interaction flows

Reporting Issues

When reporting sync issues, include:

1. Device information (OS, version)
2. Network conditions
3. Steps to reproduce
4. Screenshots of error messages
5. Backend logs (if available)
6. Browser console errors

Success Criteria

The sync implementation is considered successful when:

• ✅ All data types sync bi-directionally
• ✅ Real-time updates work within 5 seconds
• ✅ Offline mode functions correctly
• ✅ No data loss during sync
• ✅ Conflicts are handled gracefully
• ✅ Performance meets benchmarks
• ✅ Error recovery works reliably