6 releases (3 breaking)

0.6.2 Apr 10, 2024
0.6.1 Oct 9, 2023
0.6.0 Jan 11, 2023
0.4.0 Nov 3, 2022
0.1.0 Sep 15, 2022

#30 in WebSocket

Download history 4/week @ 2024-02-27 7/week @ 2024-03-12 7/week @ 2024-04-02 137/week @ 2024-04-09 103/week @ 2024-04-23

276 downloads per month

MIT license

316 lines


Websocket server for (integration)testing and development of a websocket client.

  • Send custom messages to a client.
  • Record messages sent by client.

This server is controlled with HTTP-requests. The client being tested, will connect to it with a websocket and then we can interact with this client by sending HTTP requests at an API. That same API can be used to check what messages this client has sent to the server.

I needed this for e2e and integration testing a bot that listened on a websocket.

Build Status Crates.io


  1. Start the webmocket webserver.

    webmocket # or "cargo run"
    # 2022-09-15T14:38:07Z INFO  webmocket] Listening on
  2. Connect a websocket client (webpage, bot, client, etc.). e.g. wscat. Then send a few messages to the server. Typically this would be the subject under test.

    wscat --connect
    # Connected (press CTRL-C to quit)
    # > hello, this is the first message
    # > my name is Foo and I am a Bar
    # > { "message": "this would be JSON" }
  3. Check messages received from client:

    curl | jq
    # [
    #   "hello, this is the first message",
    #   "my name is Foo and I am a Bar",
    #   "{ \"message\": \"this would be JSON\" }"
    # ]
  4. Fire websocket messages to the client using a normal HTTP library. e.g. curl.

    wscat --connect
    curl -X POST -H"Content-type: text/plain; charset=UTF-8" \
      --data 'Hello from the server 👋' \

    We should see wscat print the message to the console.

  5. Check ping/pong

    wscat --connect --show-ping-pong
    curl -X POST -H"Content-type: text/plain; charset=UTF-8" \
      --data 'Hello from the server 👋' \

    We should see wscat replying to the Ping from the server with a Pong. We can then check that the server recieved a pong.


In order to install the platform on development machine, run

cargo install webmocket

TODO: build binaries and make the avaiable for download.




Webmocket is configured through env vars. These must be set before starting.

var default
WEBMOCKET_ADDR IP address of the listening host. Must be a valid IPV4
WEBMOCKET_PORT Port on which the service will listen. Must be a valid unix port 3000
WEBMOCKET_WS_PATH Path on which the websocket can be connected. Must start with / /ws

E.g. to set all variables, one could run:



Alternative is to run webmocket in a container. Usefull in e.g. a CI pipeline, or when you don't want or don't have cargo around.

docker run --rm --detach --expose 3000:3000 berkes/wemocket:latest

Environment variables as described under Configure can be passed in to configure the service. For example:

docker run --rm --detach --expose 3000:3000 --env WEBMOCKET_WS_PATH=/chat/stream

This will run the webmocket service with the websocket endpoint on

Note: The port 3000 is hardcoded in the image so changing the WEBMOCKET_PORT to anything other than 3000 won't work.


Get the source-code, then

cargo test

This builds the application and runs the tests locally.


TODO: CI/CD setup


TODO: CI/CD setup


The service is intended for local development or tests (A CI server or such): it keeps its database in memory. This means that if you're going to send a lot of data to it, it will need a lot of memory.

The service does not bind to HTTPS (or SSL), because that is hard to achieve. if the client insists on SSL only, you may need to configure some proxy before it.


If needs arise, or pull-requests arrive, some additional features could be added:

  • Make it a library to include in tests rather than running it as standalone service.
  • Proxy to an actual websocket and record messages as they would be sent server to client.
  • Proxy to an actual websocket and record messages as they would be sent client to server.
  • Store these recorded messages VCR style (though not nessecarily that format).
  • Send those recorded server-to-client messages to a client on-demand.
  • Set expectations on recorded client-to-server messages, to match that client sends what is expected.


~378K SLoC