Socket.IO requests

A Socket.IO request connects to a Socket.IO server, joins a namespace, emits events and logs every event the server sends back. It speaks the Socket.IO protocol itself, so you work with event names and JSON arguments instead of raw frames. Use it to test a chat, game or dashboard backend built on Socket.IO without writing a client.

Connect and emit an event

1. In the API client, click New › Other Protocols › Socket.IO, or right-click a collection and choose Add Other Request › Socket.IO. Search Everything (⇧ ⌘ A) also has New Socket.IO Request.

2. Type the server’s base URL, for example https://api.example.com or http://localhost:3000. Include the scheme.

3. If the server uses a namespace other than /, or a custom path, set them in Settings. Put the handshake auth payload in Auth.

4. Press ⌘ ↩ or click Connect. The log shows the Engine.IO session opening and then Connected to /.

5. In Event, type the event name and its arguments as a JSON array, then press ⌘ ⇧ ↩ or click Emit.

6. Click Disconnect when you’re done.

123456

The Event tab: an event name, its arguments and the acknowledgement option.

1. Connect (⌘↩)
2. Auth, Headers, Params and Settings tabs
3. Event name
4. Wait for the server's acknowledgement
5. Arguments as a JSON array
6. Emit (⌘⇧↩)

×

Request tabs

Tab	Field	Default	What it does
Event	Event	message	The event name to emit.
Event	Wait for acknowledgement	Off	Asks the server to acknowledge the event and logs its reply.
Event	Arguments (a JSON array)	[ { "hello": "world" } ]	Each array item is one argument. A value that isn’t an array is sent as a single argument. {{variables}} are filled in first.
Event	Saved		Save Current Message keeps the arguments; choose a saved entry to load it, or remove it with Delete.
Auth	JSON editor	Empty	The auth payload sent with the namespace connect packet, read by the server as socket.handshake.auth. Leave it empty to send none. {{variables}} work.
Headers	Key/value table		Headers for the WebSocket handshake. Values can use {{variables}}.
Params	Key/value table		Query parameters added to the connection URL, read by the server as socket.handshake.query. Values can use {{variables}}.
Settings	Path	/socket.io/	The server’s Socket.IO path.
Settings	Namespace	/	The namespace to connect to and emit on, for example /admin.
Settings	Skip TLS certificate verification	Off	Accepts any certificate on https:// servers, for development.

Emit is enabled only while connected. For example, to join a room with a token:

Event

Arguments (a JSON array)

[
  { "room": "general" },
  "{{userId}}"
]

With Event set to join, this emits join with two arguments: an object and a string.

Auth

Auth

{ "token": "{{token}}" }

Protocol support

Cloak Proxy is a Socket.IO 3 and 4 client using Engine.IO version 4 over WebSocket. It connects with the WebSocket transport directly and doesn’t use HTTP long-polling, so the server must allow the websocket transport (Socket.IO servers do by default). Socket.IO 2 servers and servers that only allow polling aren’t supported.

The connection URL is built from your base URL, the Path, the Params, EIO=4 and transport=websocket. http:// becomes ws:// and https:// becomes wss://; you can also type a ws:// or wss:// URL. A path in the URL itself is replaced by Path, and query parameters in the URL are kept.

Connecting, joining a namespace and waiting for an acknowledgement each time out after 10 seconds.

Read the Messages log

Entry	Meaning
Engine.IO open · sid … · ping 25s	The Engine.IO session opened, with its session id and the server’s ping interval.
Connected to /	The namespace accepted the connection, with the socket id.
Connect error on /admin	The namespace refused the connection, usually because of auth. Select it for the server’s message.
Event name, outgoing	An event you emitted with its arguments, and the acknowledgement id when you asked for one.
Event name, incoming	An event the server sent, with (wants ack) if the server asked you to acknowledge it.
Ack #3 or Ack for message	An acknowledgement and its arguments.
Disconnected from / / Closed	The namespace or the whole connection ended, with the reason.

Select an entry to see its arguments as a JSON tree. Hide events hides informational entries, the search field filters entries, and Clear empties the log.

Run Socket.IO requests in the collection runner

The collection runner and cloakctl run a saved Socket.IO request in one step: connect to the namespace with the saved auth, emit the saved event once, collect the result, and disconnect.

Mode	Body	Extra header
Wait for acknowledgement off	A JSON array of every event the server sent, each as { "event": "name", "args": [ … ] }. Collecting stops when no new event has arrived for half a second, or after the request timeout (30 seconds by default) if none arrive.	x-messages-received with the number of events
Wait for acknowledgement on	The acknowledgement’s arguments as a JSON array.	x-socketio-ack: true

The status is always 200 OK with Content-Type: application/json. A failed connection, a refused namespace or a missing acknowledgement is reported as an error with no response.

Socket.IO requests have no Scripts tab of their own. Put tests in the collection’s or a folder’s post-response script, and check pm.info.requestName for tests meant for one request:

Collection post-response script

if (pm.info.requestName === "Join room") {
  pm.test("server confirmed the join", () => {
    const events = pm.response.json();
    const joined = events.find((e) => e.event === "joined");
    pm.expect(joined, "joined event").to.exist;
    pm.expect(joined.args[0].room).to.eql("general");
  });
}

Tokens in auth payloads

The auth payload, headers and params are saved with the request in your workspace files. Reference tokens from a secret environment variable or the vault, as in { "token": "{{token}}" }, so they don’t end up in Git or exports.

Related

WebSocket requestsPlain WebSocket connections with raw frames.

Collection runnerRun realtime requests with tests.

Variables and environmentsKeep URLs and tokens out of your requests.

Scripts and testsThe pm API for checking responses.