wscat -c: Interactive WebSocket Client
wscat -c ws://host/path connects to a WebSocket and gives you an interactive prompt to send and receive messages.
wscat is a Node-based WebSocket client (from the ws package). -c connects as a client; -l runs a listening server. It is interactive by default, so scripting it in CI needs a little care.
What it does
wscat -c <url> opens a WebSocket connection and drops into an interactive prompt where lines you type are sent as messages and incoming messages are printed. -H adds handshake headers, -s requests a subprotocol, and --no-check skips TLS certificate verification for wss://.
Common usage
wscat -c ws://localhost:8080/socket
wscat -c wss://example.com/ws -H "Authorization: Bearer $TOKEN"
# feed one message non-interactively, then it stays open
echo '{"type":"ping"}' | wscat -c ws://localhost:8080/socketOptions
| Flag | What it does |
|---|---|
| -c, --connect <url> | Connect to a WebSocket URL as a client |
| -H, --header "k: v" | Add a header to the opening handshake |
| -s, --subprotocol <p> | Request a WebSocket subprotocol |
| -x, --execute <cmd> | Send a message after connecting |
| --no-check | Do not verify the TLS certificate (wss) |
In CI
wscat is built for interactive use, so it does not exit on its own. For a non-interactive smoke test use -x to send a message after connecting, or prefer websocat with -n1 when you need the process to terminate cleanly after one exchange. Always bound the step with a timeout so an open socket cannot hang the job.
Common errors in CI
error: connect ECONNREFUSED 127.0.0.1:8080 means nothing is listening on the port. Unexpected server response: 404 means the path is not a WebSocket endpoint. Unexpected server response: 401 means missing auth; add -H "Authorization: ...". A job that never finishes is wscat sitting at its interactive prompt; use -x or a timeout.