WebSocketMock

A lightweight web socket mock server for testing Elixir applications. Create isolated web socket servers on-demand for reliable testing of web socket clients and real-time features.

Features

• Isolated test servers - Each mock runs on a unique port with its own client registry
• Client management - Track connections, send messages, and query connection status
• Test-friendly - Designed for ExUnit with minimal setup

Installation

Add websocket_mock to your test dependencies in mix.exs:

def deps do
  [
    {:websocket_mock, "~> 0.1.0", only: :test}
  ]
end

Quick Start

# Start a mock server
{:ok, mock} = WebSocketMock.start()

# Connect your WebSocket client
{:ok, client_pid} = MyWebSocketClient.start(mock.url)

# Check connection status
assert WebSocketMock.is_connected?(mock)
assert WebSocketMock.num_connections(mock) == 1

# Send messages to clients
[%{client_id: client_id}] = WebSocketMock.list_clients(mock)
:ok = WebSocketMock.send_message(mock, client_id, {:text, "Hello!"})

# Clean up
WebSocketMock.stop(mock)

Usage in Tests

defmodule MyAppTest do
  use ExUnit.Case

  setup do
    {:ok, mock} = WebSocketMock.start()
    on_exit(fn -> WebSocketMock.stop(mock) end)
    %{mock: mock}
  end

  test "websocket client connects and receives messages", %{mock: mock} do
    {:ok, client} = MyApp.WebSocketClient.start(mock.url)
    
    # Verify connection
    assert WebSocketMock.is_connected?(mock)
    
    # Send message from server
    [%{client_id: client_id}] = WebSocketMock.list_clients(mock)
    WebSocketMock.send_message(mock, client_id, {:text, "test message"})
    
    # Assert client received message
    assert_receive {:websocket_message, {:text, "test message"}}
  end


  test "client sends message to server", %{mock: mock} do
    {:ok, client} = MyApp.WebSocketClient.start(mock.url)
    
    # Send message from client
    MyApp.WebSocketClient.send_message(client, {:text, "Hello Server!"})
    
    # Verify server received message
    assert WebSocketMock.received_messsages(mock) == [{:text, "Hello Server!"}]
  end


  test "cient handles response", %{mock: mock} do 
    WebSocketMock.reply_with(mock, {:text, "ping"}, {:text, "pong"})

    # Client will receive {:text, "pong"}
    MyApp.WebSocketClient.send_message(client, {:text, "ping"})
  end

end

Message Types

Send different web socket frame types:

# Text messages
WebSocketMock.send_message(mock, client_id, {:text, "Hello"})

# Binary data
WebSocketMock.send_message(mock, client_id, {:binary, <<1, 2, 3>>})

# Ping/Pong frames
WebSocketMock.send_message(mock, client_id, {:ping, "ping-data"})
WebSocketMock.send_message(mock, client_id, {:pong, "pong-data"})

Documentation

Full documentation is available at https://hexdocs.pm/websocket_mock.

License

MIT License. See LICENSE for details.