Testing real-time applications requires multiple connected clients.

Use the following testing procedure:

1. Start the backend.
2. Open Chrome.
3. Connect to the chat application.
4. Open another browser window.
5. Connect using a different username.
6. Send a message from the first browser.
7. Verify that the second browser receives it.
8. Send a message from the second browser.
9. Verify that the first browser receives it.
10. Disconnect one browser and inspect the backend logs.

Also test room-based communication by opening separate clients and joining different rooms.

Clients in the same room should receive room messages, while clients outside that room should not.

You do not always need a browser to test Socket.IO.

The socket.io-client package can also be used from Node.js scripts.

Install it as a development dependency:

npm install -D socket.io-client

Create a test script to connect to your server, emit an event, receive a response, and disconnect.

This approach is useful for automated testing and backend integration tests.

npm install -D socket.io-client

Create test-client.js in the project root.

The script will:

1. Connect to the Socket.IO server.
2. Listen for connection events.
3. Emit a test message.
4. Listen for the broadcast message.
5. Disconnect after receiving the message.

import { io } from 'socket.io-client';

const socket = io('http://localhost:3000');

socket.on('connect', () => {
  console.log('Connected:', socket.id);

  socket.emit('chat:send', {
    username: 'TestUser',
    message: 'Hello from Node.js test client'
  });
});

socket.on('chat:message', (message) => {
  console.log('Received:', message);
  socket.disconnect();
});

socket.on('connect_error', (error) => {
  console.error('Connection failed:', error.message);
});

A connection failure can happen for several reasons.

Common causes:

1. The backend is not running.
2. The browser is connecting to the wrong port.
3. The server and client use incompatible Socket.IO versions.
4. Cross-origin access is not configured correctly.
5. A reverse proxy is not forwarding WebSocket upgrade requests.
6. Authentication middleware rejects the connection.
7. A network firewall blocks the connection.

Diagnostic steps:

• Check the backend terminal.
• Inspect the browser Network tab.
• Look for failed Engine.IO requests.
• Inspect the connect_error event.
• Verify the server URL.
• Verify the authentication payload.

Remember that the initial Socket.IO transport may use HTTP long-polling before upgrading to WebSocket. A failed polling request can indicate an HTTP, proxy, or origin configuration issue.

Sometimes the connection succeeds but messages are not delivered.

Check the following:

1. Is the client emitting the correct event name?
2. Is the server listening for the same event name?
3. Is the server broadcasting to the intended namespace?
4. Is the client listening for the correct response event?
5. Is the target client connected?
6. Is the target client part of the requested room?
7. Is the server rejecting the payload?
8. Is the event handler registered more than once or being removed unexpectedly?

Event names are case-sensitive. For example, chat:send and Chat:Send are different events.

Add logs at the event receiver and sender to identify where the communication flow stops.

socket.on('chat:send', (payload) => {
  console.log('Received chat:send event');
  console.log('Payload:', payload);

  io.emit('chat:message', payload);

  console.log('Broadcast completed');
});

Socket.IO uses the debug package internally and exposes namespaces for diagnostic logging.

You can enable detailed logs through the DEBUG environment variable.

For example, on Linux or macOS:

DEBUG=socket.io* npm run dev

On Windows PowerShell:

$env:DEBUG='socket.io*'; npm run dev

This can help identify connection, namespace, and server-side Socket.IO behavior.

Debug logging is useful during development but should be configured carefully in production because detailed logs can increase output volume and expose operational information.

DEBUG=socket.io* npm run dev