Test a WebSocket, an event stream or a gRPC service

Connect to a WebSocket, a Server-Sent Events address or a gRPC method, send messages and check what comes back.

In short

A stream session connects to a WebSocket, a Server-Sent Events address or a gRPC method, sends messages (for a WebSocket or gRPC) and checks what comes back. Save it on a project, run it on its own, or run it as part of a suite step.

Before you start

• Who: saving and running a stream needs Edit on the project. Anyone who can open it reads results.
• Plan: every plan. Each stream run counts one API request for the connection and one more for every ten messages it sends. A gRPC call counts one, and one more for every ten messages beyond the first ten.
• First: a public WebSocket or event-stream address, or a public gRPC server with its .proto files or server reflection turned on.

Steps

1. Open "Build", choose "Mocks, streams & docs", choose the project and open "Streams".
2. Press "Try the sandbox event stream". It saves a stream that listens to three order events and opens it.
3. Press "Run now". The messages appear as they arrive, then the result of each check.
4. For your own API, press "New stream", choose WebSocket, Server-Sent Events or gRPC beside the address and press "Run now". What is on screen is saved as it runs, so there is no second button. Your streams are listed with their last result.

Result: each check passes or fails against the messages that arrived.

Send messages and check the answers

• A WebSocket address starts with ws:// or wss://; an event stream with http:// or https://.
• For a WebSocket, open "Messages to send" and write them in order, separated by a line holding only three dashes. An event stream only listens. Headers, when to stop and checks are folded the same way, each showing what it is set to.
• A check reads any message, every message, the message at a position, or how many arrived. It can look for text, match a pattern, or compare a JSON field such as $.status.
• Addresses, headers and messages may hold variables of the chosen environment. Credentials are masked in every stored run.
• In a suite, open a step's "Then run a stream" and choose a saved stream. It runs once the step's request passed, and the step passes only when the session does.

Call a gRPC method

1. Choose "gRPC" and give the server address, such as https://grpc.example.com. Use http:// for a server that speaks HTTP/2 without TLS.
2. Press "Schemas". Add the .proto files of the service (google/protobuf files are built in), or read the schema from the server if it has reflection turned on.
3. Choose the schema and the method. Press "Fill in a sample message" to start from every field of the request, then change the values.
4. Open "Metadata" if the server needs it and add each name and value, such as authorization and Bearer {{token}}.
5. Press "Run now". The answers appear as JSON, with the status the call ended with.

• Write messages as JSON with the field names of the .proto file or their JSON names. 64-bit numbers may be written as strings, bytes as base64, an enum by its name, and a timestamp as 2026-01-31T09:00:00Z.
• A unary or server-streaming method takes one message. A client-streaming or two-way method sends every message, separated by a line of three dashes, and then reads the answers.
• A message without a variable in it is checked against the schema when you save, so a wrong field name or value is found before anything is sent.
• A call fails when it ends with any status but OK. To test an error on purpose, add a check on the status, such as "Status equals NOT_FOUND".
• Answers show every field, with defaults for fields the server left out, so a check on a zero or empty value works.
• A schema that a call still uses cannot be deleted. Read a schema from the server again with "Read again" after the service changes.

Good to know

• A session listens for at most 60 seconds, receives at most 100 messages and ends when nothing arrives for the silence time you set.
• You can have two sessions open at once, and a workspace five.
• Each run counts one API request for the connection and one more for every ten messages it sends. Nothing is counted when it did not connect.
• Sessions connect from {{brand}}'s servers under the same rules as requests: never to a private or local address, and a redirect is not followed.

If something goes wrong

• It does not connect: check the address scheme (ws://, wss://, http:// or https://), and that it is public.
• The session ends early: nothing arrived within the silence time. Raise it.
• A gRPC call answers with an HTTP status: the address may not be a gRPC server, or a proxy in front of it does not pass HTTP/2 through.
• Reading the schema from the server fails: the server may not offer reflection. Add its .proto files instead.
• A message is refused when you save: the message names the field and what it expected. Fix the value or fill in a sample again.

Related

• /help/api-testing/test-suites
• /help/api-testing/quality-view