🌐 WebSocket Testing Guide

Overview

This guide provides comprehensive instructions for testing the HexFeed WebSocket real-time notification system.

Prerequisites
Testing Methods
Test Scenarios
Troubleshooting
Performance Testing

Prerequisites

1. Backend Running

Ensure the backend is running:

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

2. Get JWT Token

First, authenticate to get a JWT token:

# Login
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'

Save the token - you'll need it for WebSocket authentication!

Testing Methods

Method 1: HTML Test Client (Recommended)

Open the test client:

open hexfeed-backend/websocket-test-client.html
# Or navigate to: file:///path/to/hexfeed-backend/websocket-test-client.html

Follow the UI:
- Enter your JWT token
- Click "Connect"
- Enter latitude/longitude (e.g., 37.7749, -122.4194)
- Click "Subscribe to Location"
- Watch the message log for real-time updates!

Method 2: Browser Console (Quick Test)

// 1. Include libraries (paste in console)
var script1 = document.createElement('script');
script1.src = 'https://cdn.jsdelivr.net/npm/sockjs-client@1/dist/sockjs.min.js';
document.head.appendChild(script1);

var script2 = document.createElement('script');
script2.src = 'https://cdn.jsdelivr.net/npm/@stomp/stompjs@7/bundles/stomp.umd.min.js';
document.head.appendChild(script2);

// 2. Wait a few seconds for libraries to load, then connect
var token = 'YOUR_JWT_TOKEN_HERE';
var socket = new SockJS('http://localhost:8080/ws');
var stompClient = new StompJs.Client();
stompClient.webSocketFactory = () => socket;
stompClient.connectHeaders = { 'Authorization': `Bearer ${token}` };

stompClient.onConnect = function(frame) {
    console.log('✅ Connected!');
    
    // Subscribe to messages
    stompClient.subscribe('/user/queue/feed', function(message) {
        console.log('📨 Received:', JSON.parse(message.body));
    });
    
    // Subscribe to location
    stompClient.publish({
        destination: '/app/subscribe',
        body: JSON.stringify({ latitude: 37.7749, longitude: -122.4194 })
    });
};

stompClient.onStompError = (error) => console.error('❌ Error:', error);
stompClient.activate();

Method 3: Postman

Create WebSocket Request:
- New → WebSocket Request
- URL: ws://localhost:8080/ws
Add Authentication:
- In Headers tab, add:
```
Authorization: Bearer YOUR_JWT_TOKEN
```

Connect and Subscribe:

Click "Connect"

Send message to /app/subscribe:

{
  "destination": "/app/subscribe",
  "body": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Method 4: Command Line (wscat)

# Install wscat
npm install -g wscat

# Connect (note: wscat doesn't support SockJS, so this is basic)
wscat -c ws://localhost:8080/ws \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Method 5: Python Script

# Install: pip install websocket-client
import websocket
import json

token = "YOUR_JWT_TOKEN"

def on_message(ws, message):
    print(f"📨 Received: {message}")

def on_open(ws):
    print("✅ Connected!")
    # Subscribe
    subscribe_msg = json.dumps({
        "latitude": 37.7749,
        "longitude": -122.4194
    })
    ws.send(f"SUBSCRIBE\ndestination:/app/subscribe\n\n{subscribe_msg}\x00")

ws = websocket.WebSocketApp(
    "ws://localhost:8080/ws",
    header={"Authorization": f"Bearer {token}"},
    on_open=on_open,
    on_message=on_message
)
ws.run_forever()

Test Scenarios

Scenario 1: Basic Connection Test

Objective: Verify WebSocket connection establishment

Steps:

Start backend
Open HTML test client
Enter JWT token
Click "Connect"

Expected Result:

Status changes to "Connected"
Log shows: "✅ Connected to WebSocket successfully!"
Log shows: "📡 Subscribed to /user/queue/feed"

Pass Criteria: ✅ Connection established without errors

Scenario 2: Location Subscription Test

Objective: Verify location-based subscription

Steps:

Connect to WebSocket (Scenario 1)
Enter coordinates:
- Latitude: 37.7749
- Longitude: -122.4194
Click "Subscribe to Location"

Expected Result:

Log shows: "📍 Subscribing to location: 37.7749, -122.4194"

Receive subscription confirmation with:

{
  "centerHexId": "872830828ffffff",
  "subscribedHexIds": ["872830828ffffff", "872830829ffffff", ...],
  "status": "success",
  "message": "Subscribed to 7 hex regions..."
}

Pass Criteria: ✅ Received 7 hex IDs in confirmation

Scenario 3: Real-time Post Notification Test

Objective: Verify real-time post notifications

Steps:

Connect and subscribe to location (Scenarios 1-2)

In another terminal, create a post:

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

Expected Result:

WebSocket client receives notification:

{
  "type": "new_post",
  "hex_id": "872830828ffffff",
  "post": {
    "postId": "...",
    "content": "Test post...",
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Pass Criteria: ✅ Notification received within 1-2 seconds of post creation

Scenario 4: Heartbeat Test

Objective: Verify heartbeat mechanism

Steps:

Connect to WebSocket
Subscribe to location
Wait and observe

Expected Result:

Every 30 seconds, receive heartbeat:

{
  "type": "heartbeat",
  "timestamp": "2024-01-15T10:30:00"
}

Client automatically sends pong response

Pass Criteria: ✅ Heartbeats received regularly, connection stays alive

Scenario 5: Multiple Subscriptions Test

Objective: Verify user can update subscription

Steps:

Connect and subscribe to location A (37.7749, -122.4194)
Subscribe to different location B (34.0522, -118.2437)
Create posts in both locations

Expected Result:

New subscription replaces old one
Only receive notifications for location B

Pass Criteria: ✅ Subscription updates correctly

Scenario 6: Disconnect/Reconnect Test

Objective: Verify reconnection handling

Steps:

Connect and subscribe
Click "Disconnect"
Wait 5 seconds
Click "Connect" again
Subscribe to same location

Expected Result:

Clean disconnection
Successful reconnection
Subscription works after reconnect

Pass Criteria: ✅ No errors, subscription restored

Scenario 7: Authentication Failure Test

Objective: Verify authentication is enforced

Steps:

Try to connect with invalid JWT token
Try to connect without JWT token

Expected Result:

Connection fails with error message
Log shows: "❌ STOMP error" or "WebSocket authentication required"

Pass Criteria: ✅ Connection rejected for invalid/missing auth

Scenario 8: Unsubscribe Test

Objective: Verify unsubscribe functionality

Steps:

Connect and subscribe to location
Click "Unsubscribe"
Create a post in that location

Expected Result:

Receive unsubscribe confirmation
Do NOT receive new post notification

Pass Criteria: ✅ No notifications after unsubscribe

Scenario 9: Multiple Concurrent Users Test

Objective: Verify system handles multiple users

Steps:

Open 3 browser tabs with test client
Login with different users in each tab
Subscribe all to same location
Create a post in that location

Expected Result:

All 3 users receive the notification
Each user sees their own userId in logs

Pass Criteria: ✅ All users receive notifications independently

Scenario 10: Stress Test

Objective: Verify system handles rapid messages

Steps:

Connect and subscribe

Create 10 posts rapidly in the same location:

for i in {1..10}; do
  curl -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

Expected Result:

Receive all 10 notifications
No dropped messages
No connection errors

Pass Criteria: ✅ All notifications received, no errors

Troubleshooting

Problem: Cannot Connect

Symptoms:

"WebSocket connection error"
"Connection refused"

Solutions:

Verify backend is running: curl http://localhost:8080/actuator/health
Check if port 8080 is available: lsof -i :8080
Check backend logs for errors
Verify JWT token is valid (not expired)

Problem: Authentication Fails

Symptoms:

"WebSocket authentication required"
"Invalid JWT token"

Solutions:

Get fresh JWT token from login API
Ensure token includes "Bearer " prefix
Check token expiration time
Verify SecurityConfig allows WebSocket authentication

Problem: No Notifications Received

Symptoms:

Connected and subscribed, but no messages when creating posts

Solutions:

Check if Kafka is running: docker ps | grep kafka
Verify subscription confirmation was received
Check if post is in same location as subscription
Check backend logs for Kafka consumer errors
Verify WebSocketManagerService is broadcasting messages

Problem: Connection Drops

Symptoms:

Connection disconnects randomly
"Disconnected" status after few minutes

Solutions:

Check if heartbeat is working (should see "💓 Heartbeat received")
Verify pong responses are being sent
Check network stability
Increase connection timeout in configuration
Check for firewall/proxy issues

Problem: Duplicate Notifications

Symptoms:

Receive same notification multiple times

Solutions:

Check if multiple subscriptions are active
Verify user isn't connected multiple times
Check Kafka consumer group configuration
Review WebSocketManagerService subscription logic

Performance Testing

Load Test Setup

# Install Apache Bench WebSocket extension
npm install -g websocket-bench

# Run load test
wsbench -c 100 -n 1000 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  ws://localhost:8080/ws

Performance Metrics to Monitor

Connection Time: < 100ms
Subscription Response: < 200ms
Notification Latency: < 500ms from post creation
Concurrent Connections: Support 1000+ users
Memory Usage: Monitor with JProfiler or VisualVM

Monitoring Commands

# Monitor active WebSocket connections
curl http://localhost:8080/actuator/metrics/websocket.connections

# Monitor message throughput
curl http://localhost:8080/actuator/metrics/websocket.messages

# Check backend logs
tail -f hexfeed-backend/logs/hexfeed-backend.log | grep WebSocket

Automated Test Script

Save this as test-websocket.sh:

#!/bin/bash

echo "🧪 HexFeed WebSocket Automated Test"
echo "==================================="

# 1. Login and get token
echo "1️⃣ Getting JWT 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')

if [ -z "$TOKEN" ] || [ "$TOKEN" = "null" ]; then
    echo "❌ Failed to get JWT token"
    exit 1
fi
echo "✅ Got JWT token: ${TOKEN:0:20}..."

# 2. Test WebSocket connection using HTML client
echo ""
echo "2️⃣ Opening WebSocket test client..."
open websocket-test-client.html
echo "📋 Token copied to clipboard:"
echo "$TOKEN" | pbcopy
echo "✅ Paste the token in the browser and click Connect"

# 3. Wait for manual connection
read -p "Press Enter after connecting in browser..."

# 4. Create test post
echo ""
echo "3️⃣ Creating test post..."
POST_RESPONSE=$(curl -s -X POST http://localhost:8080/api/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "content": "Automated test post - you should receive this via WebSocket!",
    "latitude": 37.7749,
    "longitude": -122.4194
  }')

echo "✅ Post created:"
echo "$POST_RESPONSE" | jq .

echo ""
echo "4️⃣ Check the browser - you should see a notification!"
echo ""
echo "Test complete! 🎉"

Make it executable:

chmod +x test-websocket.sh
./test-websocket.sh

Test Checklist

Use this checklist to verify all functionality:

Next Steps

After completing WebSocket testing:

✅ Integration Testing: Test complete flow (REST → Kafka → WebSocket)
✅ Load Testing: Test with 1000+ concurrent connections
✅ Frontend Integration: Connect React/Vue frontend
✅ Production Setup: Configure external message broker (RabbitMQ/Redis)
✅ Monitoring: Setup Grafana dashboards for WebSocket metrics

Additional Resources

Need Help? Check the troubleshooting section or review backend logs in logs/hexfeed-backend.log

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🌐 WebSocket Testing Guide

Overview

Table of Contents

Prerequisites

1. Backend Running

2. Get JWT Token

Testing Methods

Method 1: HTML Test Client (Recommended)

Method 2: Browser Console (Quick Test)

Method 3: Postman

Method 4: Command Line (wscat)

Method 5: Python Script

Test Scenarios

Scenario 1: Basic Connection Test

Scenario 2: Location Subscription Test

Scenario 3: Real-time Post Notification Test

Scenario 4: Heartbeat Test

Scenario 5: Multiple Subscriptions Test

Scenario 6: Disconnect/Reconnect Test

Scenario 7: Authentication Failure Test

Scenario 8: Unsubscribe Test

Scenario 9: Multiple Concurrent Users Test

Scenario 10: Stress Test

Troubleshooting

Problem: Cannot Connect

Problem: Authentication Fails

Problem: No Notifications Received

Problem: Connection Drops

Problem: Duplicate Notifications

Performance Testing

Load Test Setup

Performance Metrics to Monitor

Monitoring Commands

Automated Test Script

Test Checklist

Next Steps

Additional Resources

FilesExpand file tree

WEBSOCKET_TESTING_GUIDE.md

Latest commit

History

WEBSOCKET_TESTING_GUIDE.md

File metadata and controls

🌐 WebSocket Testing Guide

Overview

Table of Contents

Prerequisites

1. Backend Running

2. Get JWT Token

Testing Methods

Method 1: HTML Test Client (Recommended)

Method 2: Browser Console (Quick Test)

Method 3: Postman

Method 4: Command Line (wscat)

Method 5: Python Script

Test Scenarios

Scenario 1: Basic Connection Test

Scenario 2: Location Subscription Test

Scenario 3: Real-time Post Notification Test

Scenario 4: Heartbeat Test

Scenario 5: Multiple Subscriptions Test

Scenario 6: Disconnect/Reconnect Test

Scenario 7: Authentication Failure Test

Scenario 8: Unsubscribe Test

Scenario 9: Multiple Concurrent Users Test

Scenario 10: Stress Test

Troubleshooting

Problem: Cannot Connect

Problem: Authentication Fails

Problem: No Notifications Received

Problem: Connection Drops

Problem: Duplicate Notifications

Performance Testing

Load Test Setup

Performance Metrics to Monitor

Monitoring Commands

Automated Test Script

Test Checklist

Next Steps

Additional Resources