How to test a Socket.IO API in API Spector

Socket.IO is not plain WebSocket. It is its own protocol that runs on top of WebSocket (with an HTTP long-polling fallback), and it adds named events, acknowledgements, namespaces, handshake auth, and automatic reconnection. Because of that framing, a raw WebSocket client cannot talk to a Socket.IO server. API Spector now has a dedicated Socket.IO mode, in the app and on the command line.

WebSocket or Socket.IO?

• WebSocket (WS) is a raw, two-way channel. You send and receive opaque text or binary frames. There are no event names, no acknowledgements, and no built-in reconnection. Use the WS mode for a plain WebSocket server.
• Socket.IO (IO) is a library and protocol on top of WebSocket. You emit named events that carry JSON arguments, you can ask for an acknowledgement (a reply to a specific emit), you can use namespaces to split one connection into channels, and the client reconnects on its own. Use the IO mode for a Socket.IO server.

If you point the WS mode at a Socket.IO server it will not work, and the reverse is true as well. Pick the mode that matches the server.

Connect from the app

1. Add a request and set the protocol toggle to IO.
2. Type the server URL in the URL bar, for example https://example.com. Put any handshake headers in the Headers tab.
3. Set the Namespace (for example /admin, or leave it as / for the default) and, if the server expects it, the handshake Auth as JSON, for example {"token":"abc"}.
4. Click Connect. The status dot turns green and a connect note appears in the log.

Emit events and read the replies

Enter an event name, put its arguments in the box as JSON (an array is spread into several arguments, anything else is sent as one), and click Emit. Tick Wait for acknowledgement when the server answers that emit with a callback, and the acknowledgement payload shows up in the log.

The session log lists everything in order: events you emit, events the server sends, acknowledgement payloads, and connect or disconnect notes. Clear it whenever you like.

Script it from the CLI

The same connection works headlessly, which is useful in CI:

api-spector socketio --url https://example.com \
  --namespace /chat \
  --auth '{"token":"abc"}' \
  --emit 'message:["hello", {"room": "general"}]' \
  --ack \
  --listen 5

That connects, emits the message event, waits for its acknowledgement, listens for five seconds, and prints what came back. Add --json for machine-readable output, --header K:V for handshake headers, and --workspace <path> --request <name> to take the URL, headers, namespace, and auth from a saved request. The command exits non-zero when the connection fails, so a broken realtime endpoint fails the pipeline.

Where it runs

Connections run in the app's main process, and in the Node CLI, using the same Socket.IO client, so the app and the command line behave the same. Nothing is proxied through a server you do not control.