Skip to content

WEBSOCKET_QUICKSTART.md

Latest commit

 

History

History
379 lines (275 loc) · 8.8 KB

WEBSOCKET_QUICKSTART.md

File metadata and controls

379 lines (275 loc) · 8.8 KB

🚀 WebSocket Testing Quick Start

⚡ 5-Minute Quick Test

Step 1: Start Backend

cd hexfeed-backend
./mvnw spring-boot:run

Wait until you see: Started FeedSystemDependenciesApplication

Step 2: Run Automated Test

cd hexfeed-backend
./test-websocket-automated.sh --auto

This will:

  • ✅ Login and get JWT token
  • ✅ Open WebSocket test client in browser
  • ✅ Guide you through testing
  • ✅ Create test posts to verify notifications

Step 3: Manual Testing (Recommended)

  1. Open the test client:

    open websocket-test-client.html

  2. Get JWT token:

    curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com"}' \
  | jq -r '.data.token'

  3. In the browser:

    • Paste the JWT token
    • Click "Connect"
    • Click "Subscribe to Location"
    • You should see confirmation with hex IDs!

  4. Create a test post:

    TOKEN="your_token_here"

curl -X POST http://localhost:8080/api/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "content": "Test WebSocket notification!",
    "latitude": 37.7749,
    "longitude": -122.4194
  }'

  5. Watch the browser - you should see the notification appear instantly! 🎉

📱 Testing Methods Comparison

Method Difficulty Best For Interactive
HTML Client (Recommended) ⭐ Easy Visual testing, demos ✅ Yes
Automated Script ⭐ Easy CI/CD, quick verification ⚠️ Semi
Python Client ⭐⭐ Medium Automation, scripting ✅ Yes
Browser Console ⭐⭐ Medium Quick debugging ✅ Yes
Postman ⭐⭐⭐ Advanced API testing workflows ✅ Yes

🧪 Test Scenarios

✅ Basic Connection Test (30 seconds)

# 1. Login
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com"}' \
  | jq -r '.data.token')

# 2. Open HTML client
open websocket-test-client.html

# 3. Paste token, click Connect
# 4. Click "Subscribe to Location"
# 5. Success! ✅

Expected: Connection status shows "Connected", subscription confirmed with 7 hex IDs

✅ Real-time Notification Test (1 minute)

# After completing Basic Connection Test:

# Create a post
curl -X POST http://localhost:8080/api/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "content": "🔴 LIVE notification test!",
    "latitude": 37.7749,
    "longitude": -122.4194
  }'

# Watch the browser - notification appears instantly!

Expected: Browser shows new post notification within 1-2 seconds

✅ Heartbeat Test (2 minutes)

# After connecting and subscribing:
# Just wait and watch the browser

# Every 30 seconds you should see:
# 💓 Heartbeat received

Expected: Regular heartbeat messages every 30 seconds

✅ Stress Test (2 minutes)

# Create 10 posts rapidly
for i in {1..10}; do
  curl -s -X POST http://localhost:8080/api/v1/posts \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $TOKEN" \
    -d "{
      \"content\": \"Stress test post #$i\",
      \"latitude\": 37.7749,
      \"longitude\": -122.4194
    }" &
done

wait

# Check browser - should receive all 10 notifications!

Expected: All 10 notifications received, no drops, no errors

✅ Multiple Locations Test (2 minutes)

# 1. Subscribe to San Francisco (in browser)
#    Lat: 37.7749, Lon: -122.4194

# 2. Create post in SF (should receive)
curl -s -X POST http://localhost:8080/api/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "content": "Post in SF - you SHOULD see this",
    "latitude": 37.7749,
    "longitude": -122.4194
  }'

# 3. Create post in LA (should NOT receive)
curl -s -X POST http://localhost:8080/api/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "content": "Post in LA - you should NOT see this",
    "latitude": 34.0522,
    "longitude": -118.2437
  }'

Expected: Only SF post notification received, LA post filtered out

🔧 Troubleshooting

❌ "Cannot connect to WebSocket"

Fix:

# 1. Check if backend is running
curl http://localhost:8080/actuator/health

# 2. If not running, start it
./mvnw spring-boot:run

# 3. Wait for "Started" message, then try again

❌ "WebSocket authentication failed"

Fix:

# Get fresh token
TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com"}' \
  | jq -r '.data.token')

echo "Use this token: $TOKEN"

Make sure to include "Bearer " prefix in the HTML client!

❌ "No notifications received"

Fix:

# 1. Check Kafka is running
docker ps | grep kafka

# 2. If not running, start services
docker-compose up -d

# 3. Check backend logs
tail -f logs/hexfeed-backend.log | grep -i "websocket\|kafka"

# 4. Verify subscription
# In browser, click "Get Connection Status"
# Should show: subscribed_hex_count: 7

❌ "Connection drops after few minutes"

This is expected if heartbeat stops. The client should:

  • Send pong response every 30 seconds (automatic in HTML client)
  • Reconnect automatically if disconnected

Check browser console for heartbeat messages.

📊 Performance Benchmarks

Expected performance metrics:

Metric Target Actual
Connection Time < 200ms ~
Subscription Response < 300ms ~
Notification Latency < 1s ~
Concurrent Users 1000+ ~
Memory per Connection < 1MB ~

Test your setup:

# Monitor connections
curl http://localhost:8080/actuator/metrics/websocket.connections 2>/dev/null || echo "Actuator not enabled"

# Check logs for performance
tail -f logs/hexfeed-backend.log | grep -i "websocket\|performance"

🐍 Python Alternative

If you prefer command-line testing:

# Install dependencies
pip install websocket-client requests

# Run interactive client
python3 websocket_test_client.py

# Or automated
python3 websocket_test_client.py --auto

Commands in Python client:

hexfeed> login                          # Login and get token
hexfeed> connect                        # Connect to WebSocket
hexfeed> subscribe 37.7749 -122.4194    # Subscribe to location
hexfeed> post 37.7749 -122.4194 Hello!  # Create test post
hexfeed> stats                          # Show statistics
hexfeed> quit                           # Exit

📦 Postman Collection

Import the Postman collection:

# Location
hexfeed-backend/HexFeed_WebSocket_Testing.postman_collection.json

# Import in Postman
# File > Import > Select the JSON file

Testing flow:

  1. Run "Setup > Login and Get JWT Token"
  2. Note: Postman WebSocket support is limited
  3. Use for REST API testing, HTML client for WebSocket

🎯 Success Checklist

Mark as complete when verified:

  • ✅ Backend starts without errors
  • ✅ HTML client opens and loads
  • ✅ Login returns JWT token
  • ✅ WebSocket connects successfully (green status)
  • ✅ Subscription returns 7 hex IDs
  • ✅ Notifications received for new posts
  • ✅ Heartbeat works (every 30s)
  • ✅ Multiple posts all trigger notifications
  • ✅ Location filtering works (no notifications from far posts)
  • ✅ Reconnection works after disconnect
  • ✅ No memory leaks (check with long test)
  • ✅ Stress test passes (10 rapid posts)

All checked? 🎉 WebSocket is working perfectly!

🚀 Next Steps

After successful WebSocket testing:

  1. Integration Testing: Test full flow: REST → Kafka → WebSocket
  2. Load Testing: Test with 100+ concurrent users
  3. Frontend Integration: Connect React/Vue/Angular app
  4. Production Setup:
    • Enable TLS (wss:// instead of ws://)
    • Configure external message broker (RabbitMQ)
    • Setup monitoring (Grafana dashboards)
  5. Mobile Testing: Test with mobile WebSocket clients

📚 Documentation

🆘 Need Help?

  1. Check logs: tail -f logs/hexfeed-backend.log
  2. Review troubleshooting section above
  3. Check GitHub issues: (if applicable)
  4. Review Spring WebSocket docs

Happy Testing! 🎉

Remember: Real-time is magical when it works! ✨