Testing WebSocket Events

BETA The event command includes the websocket start-server subcommand that starts a mock WebSocket server that you can use to test your client.

To use this command, you must first implement a WebSocket client that handles the server’s messages. For details, see Getting Events Using WebSockets.

Starting the server

Use the websocket start-server subcommand to start a mock WebSocket server that you use to test your client. In a terminal window, enter:

twitch event websocket start-server

The mock EventSub WebSocket server should start with messages like this:

% twitch event websocket start-server
2023/03/19 11:45:17 `Ctrl + C` to exit mock WebSocket servers.
2023/03/19 11:45:17 Started WebSocket server on 127.0.0.1:8080

2023/03/19 11:45:17 Simulate subscribing to events at: http://127.0.0.1:8080/eventsub/subscriptions
2023/03/19 11:45:17 POST, GET, and DELETE are supported
2023/03/19 11:45:17 For more info: https://dev.twitch.tv/docs/cli/websocket-event-command/#simulate-subscribing-to-mock-eventsub

2023/03/19 11:45:17 Events can be forwarded to this server from another terminal with --transport=websocket
Example: "twitch event trigger channel.ban --transport=websocket"

2023/03/19 11:45:17 You can send to a specific client after its connected with --session
Example: "twitch event trigger channel.ban --transport=websocket --session=e09efae0_8775fbe4"

2023/03/19 11:45:17 For further usage information, please see our official documentation:
https://dev.twitch.tv/docs/cli/websocket-event-command/

2023/03/19 11:45:17 Connect to the WebSocket server at: ws://127.0.0.1:8080/ws

To end the server, enter Ctrl + C on your keyboard.

Connecting to the server

The URI that you use in your client code to connect your client to the server is: ws://localhost:8080/ws.

After connecting your client to the server, the server sends the client a Welcome message followed by Ping and Keepalive messages.

Forwarding mock events to clients

Once the server is running, open another terminal window and execute normal EventSub events, using twitch event trigger, with the additional flag --transport=websocket
To successfully forward mock events you must have at least one client already connected to your local WebSocket server. If there is not, a failure message will appear when you execute the command.

In a terminal window, the command should be executed like this:

twitch event trigger channel.ban --transport=websocket

By default, this will send to every client connected to the WebSocket server. If you prefer to target a specific client, you can specify its session ID with the --session flag:

twitch event trigger channel.ban --transport=websocket --session=e411cc1e_a2613d4e

Simulate subscribing to mock EventSub

Running the server allows access to both a mock WebSocket server and a mock EventSub endpoint: http://localhost:8080/eventsub/subscriptions

This endpoint simulates all the features provided by the EventSub Subscription API endpoints. This feature is optional, and is not required to forward mock EventSub events to your client, except when you have the --require-subscription flag enabled.

If you used the --require-subscription flag, you also must subscribe to at least one EventSub event or the server will disconnect your client and send the Close message “Connection unused”.

Testing Reconnect Messages

Occasionally Twitch’s EventSub WebSocket server will need to drop connections. When this occurs a Reconnect message is sent, subscriptions are saved, and the client will need to drop within 30 seconds to connect to the new URL.

To simulate this case within your local WebSocket server, from another terminal window you can run

twitch event websocket reconnect

This will immediately start another WebSocket server in the background that can be accessed at the same WebSocket URL endpoint. Clients connecting to the endpoint will be sent to the new server, and reconnecting with the provided reconnect_url will restore subscriptions you previously made. Clients should follow the Reconnect flow exactly as described to ensure no messages or subscriptions are dropped.

After 30 seconds all clients still connected to the old WebSocket server will be automatically disconnected with the Close message “Reconnect grace time expired”.

Advanced Testing

While most common features are available through the WebSocket server’s normal operation, there is the ability to simulate additional features, including all Close message codes and changing subscription statuses.

Close Messages

Through normal operation, the local WebSocket server will send about half of the Close messages. To simulate any specific Close message you can immediately disconnect the client by executing twitch event websocket close

In this command you must specify flags:

The --session flag, containing the targeted client’s session_id given in the Welcome message.
The --reason flag, with the Close message code corresponding with the Close message you wish to send to the client.

twitch event websocket close --session=05d9cfeb_cf06ebe7 --reason=4006

Modifying Subscription Statuses

When running GET EventSub Subscriptions to the mock EventSub endpoints provided earlier, the server will only be able to set EventSub subscriptions to a status that is relevant to the operation of the server.

You can override the Status field that is set for a specific Subscription by executing twitch event websocket subscription