Testing WebSocket Services
Aethrix Studio imports AsyncAPI documents and gives you two ways to work with a WebSocket endpoint, mirroring the producer/consumer split used for Kafka:
| Mode | What it does |
|---|---|
| Send | Opens or reuses a connection and sends one message; it can optionally wait for the reply |
| Listen | Opens a fresh connection and shows the messages a server pushes as they arrive, until the message count or the timeout ends the listen |
Quickest Scenario
- In API Playground, click Import API definition.
- For Service Type, select
WebSocket - AsyncAPI (3.0). - For Service Description, enter the AsyncAPI document's URL or a local file path.
- Step through the wizard — Authentication (only if the document's endpoint is protected), Analyze, Application & Service Name — and click Import.
- Select a sending operation, fill in the Message:, and click Send.
- Select a receiving operation, set Max Messages: and Timeout (ms):, click Send, and watch each pushed message appear in the event panel; click Stop when you have what you need.
Sending a message
Operations that send open the WebSocket message editor:
| Field | Notes |
|---|---|
| URI: | The ws:// or wss:// endpoint. When the AsyncAPI document declares a servers entry, the URL field is pre-filled from it (for example wss://host/ping). |
| Sub-Protocol: | Optional WebSocket sub-protocol to negotiate with the server. |
| Message: | The payload, edited as text with syntax highlighting. A Caret: indicator in the footer shows the current line and column. |
Two behaviors worth knowing:
- Connections are reused per URI. Repeated sends to the same URI share one pooled connection, so a session that expects a single handshake keeps working across sends.
- Waiting for a reply is optional. A send can read the next frame before returning, or simply report that the message was sent.
Binary frames are carried as Base64 text.
Listening for messages
Operations that receive open the WebSocket listener editor:
| Field | Range | Notes |
|---|---|---|
| URI: | — | The wss:// / ws:// endpoint to listen on. |
| Sub-Protocol: | — | Optional sub-protocol to negotiate. |
| Max Messages: | 1 – 1000 | The listen stops once this many messages have arrived. |
| Timeout (ms): | 1000 – 300000 | The listen also stops when this elapses. |
Click Send and the editor switches to the event panel: each message the server pushes becomes a row the moment it arrives, and clicking a row shows its content in the inspector. While the listen runs, the panel takes the place of the request form and a Stop button ends the listen early — the messages already received are kept. When the listen ends, the ordinary response view returns and shows the collected result with a Messages received: count.
Each listen opens a new connection and closes it when the listen ends — the listener does not reuse the sender's pooled connection.
Keeping a Listen While You Test
A listen does not end when you navigate away. Select a different operation and its editor is fully usable while the listen keeps receiving. The toolbar shows a live pill with the number of running streams and a Stop all button, and the service tree marks each node whose stream is still live. Selecting the listen operation again re-attaches the panel with every message that arrived while you were elsewhere. Sending again on the same node stops the previous listen first — one stream per node; different nodes stream in parallel.
Authentication
A WebSocket connection begins as an HTTP upgrade request, so credentials travel as ordinary HTTP headers on that request. Configure them in the Authentication tab — Bearer token, Basic, and the other modes — exactly as you would for a REST request. See the Authentication Guide.
Fallbacks and limits
For every AsyncAPI construct Aethrix degrades or rejects — external references past the depth guard, self-referencing schemas, JSON-Pointer ~1 escapes, and operations without a matching channels entry — see Import Diagnostics — Unsupported structures & fallbacks (WebSocket tab). That section is the single, exclusive reference.
In Test Automation
Four connection-lifecycle steps operate on a named connection, so a scenario can open a connection once, exchange messages, and close it:
| Step | What it does |
|---|---|
| WebSocket Connect | Opens a named WebSocket connection for use by subsequent WebSocket steps. |
| WebSocket Send | Sends a message on a named WebSocket connection. |
| WebSocket Receive | Receives messages on a named WebSocket connection. |
| WebSocket Close | Closes a named WebSocket connection. |
To simulate a WebSocket endpoint instead of calling a real one, see Service Simulation.