Documentation

Author: renatillas

src/wisp/simulate.gleam

@@ -270,7 +270,25 @@ pub const default_browser_headers: List(#(String, String)) = [
 ]
 
 /// Create a websocket upgrade request with proper headers.
-/// This creates a request that simulates a WebSocket upgrade handshake.
+///
+/// This creates a request that simulates a WebSocket upgrade handshake by
+/// setting the necessary headers: `connection`, `upgrade`, `sec-websocket-key`,
+/// and `sec-websocket-version`.
+///
+/// ## Example
+///
+/// ```gleam
+/// let request = simulate.websocket_request(http.Get, "/chat")
+/// let response = handle_request(request)
+///
+/// case response.body {
+///   wisp.WebSocket(upgrade) -> {
+///     let handler = wisp.upgrade_to_websocket(upgrade)
+///     // Test the websocket handler
+///   }
+///   _ -> panic as "Expected WebSocket upgrade"
+/// }
+/// ```
 ///
 pub fn websocket_request(method: http.Method, path: String) -> Request {
   request(method, path)
@@ -280,9 +298,24 @@ pub fn websocket_request(method: http.Method, path: String) -> Request {
   |> header("sec-websocket-version", "13")
 }
 
-/// A websocket mock that captures sent messages for testing.
-/// This allows you to verify what messages your websocket handler sends
-/// in response to incoming messages.
+/// A websocket mock for testing websocket handlers.
+///
+/// This opaque type represents a test websocket connection that captures all
+/// messages sent by the handler. It maintains the handler's state and tracks
+/// all text and binary messages sent through the connection.
+///
+/// You cannot construct this type directly - use `create_websocket` to create
+/// a test websocket from a websocket handler.
+///
+/// ## Functions
+///
+/// - `create_websocket` - Create a new test websocket
+/// - `send_websocket_text` - Send a text message to the handler
+/// - `send_websocket_binary` - Send a binary message to the handler
+/// - `websocket_sent_text_messages` - Get all text messages sent by the handler
+/// - `websocket_sent_binary_messages` - Get all binary messages sent by the handler
+/// - `reset_websocket` - Reset to initial state
+/// - `close_websocket` - Close the connection
 ///
 pub opaque type WebSocket {
   WebSocket(
@@ -316,8 +349,39 @@ type WebSocketMessage {
   IsClosed(reply_with: process.Subject(Bool))
 }
 
-/// Create a new websocket mock that captures all sent messages.
-/// Returns both the websocket and the websocket connection.
+/// Create a new websocket mock for testing.
+///
+/// This function creates a test websocket that captures all messages sent by the
+/// handler, allowing you to verify the handler's behavior without needing a real
+/// WebSocket connection. The mock automatically tracks text and binary messages
+/// sent through the connection.
+///
+/// ## Example
+///
+/// ```gleam
+/// let handler = websocket.new(
+///   on_init: fn(_conn) { 0 },
+///   on_message: fn(state, message, connection) {
+///     case message {
+///       websocket.Text(text) -> {
+///         websocket.send_text(connection, "Echo: " <> text)
+///         websocket.Continue(state + 1)
+///       }
+///       _ -> websocket.Continue(state)
+///     }
+///   },
+///   on_close: fn(_state) { Nil },
+/// )
+///
+/// let assert Ok(ws) = simulate.create_websocket(handler)
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "Hello")
+/// let assert ["Echo: Hello"] = simulate.websocket_sent_text_messages(ws)
+/// ```
+///
+/// ## Returns
+///
+/// - `Ok(WebSocket)` - A test websocket that can be used with other simulate functions
+/// - `Error(actor.StartError)` - If the underlying actor fails to start
 ///
 pub fn create_websocket(
   handler websocket: websocket.WebSocket,
@@ -421,21 +485,67 @@ fn handle_message(
   }
 }
 
-/// Get all text messages that were sent through the mock connection.
-/// Messages are returned in the order they were sent.
+/// Get all text messages that have been sent by the websocket handler.
+///
+/// Messages are returned in the order they were sent. This is useful for
+/// verifying that your handler sends the expected messages in response to
+/// incoming messages.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(ws) = simulate.create_websocket(handler)
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "Hello")
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "World")
+///
+/// let messages = simulate.websocket_sent_text_messages(ws)
+/// assert messages == ["Response 1", "Response 2"]
+/// ```
 ///
 pub fn websocket_sent_text_messages(websocket: WebSocket) -> List(String) {
   process.call(websocket.subject, 1000, GetSentTextMessages)
 }
 
-/// Get all binary messages that were sent through the mock connection.
-/// Messages are returned in the order they were sent.
+/// Get all binary messages that have been sent by the websocket handler.
+///
+/// Messages are returned in the order they were sent. This is useful for
+/// verifying that your handler sends the expected binary data in response to
+/// incoming messages.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(ws) = simulate.create_websocket(handler)
+/// let assert Ok(ws) = simulate.send_websocket_binary(ws, <<1, 2, 3>>)
+///
+/// let messages = simulate.websocket_sent_binary_messages(ws)
+/// assert messages == [<<1, 2, 3>>]
+/// ```
 ///
 pub fn websocket_sent_binary_messages(websocket: WebSocket) -> List(BitArray) {
   process.call(websocket.subject, 1000, GetSentBinaryMessages)
 }
 
-/// Reset the mock to its initial state, clearing all captured messages.
+/// Reset the websocket to its initial state, clearing all captured messages.
+///
+/// This calls the handler's `on_init` callback again and clears the list of
+/// sent messages. The websocket is also marked as not closed, allowing you to
+/// send messages again after a close.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(ws) = simulate.create_websocket(handler)
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "Hello")
+/// let assert ["Response"] = simulate.websocket_sent_text_messages(ws)
+///
+/// // Reset to initial state
+/// let ws = simulate.reset_websocket(ws)
+/// let assert [] = simulate.websocket_sent_text_messages(ws)
+///
+/// // Can send messages again from a clean slate
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "Hello again")
+/// ```
 ///
 pub fn reset_websocket(websocket: WebSocket) -> WebSocket {
   let WebSocket(websocket: internal_websocket, connection:, state: _, subject:) =
@@ -446,8 +556,28 @@ pub fn reset_websocket(websocket: WebSocket) -> WebSocket {
   WebSocket(websocket: internal_websocket, connection:, state:, subject:)
 }
 
-/// Simulate sending a text message to a websocket handler.
-/// Returns the updated state and any effects that occurred.
+/// Simulate sending a text message to the websocket handler.
+///
+/// This calls the handler's `on_message` callback with a `Text` message. The
+/// handler's state is updated based on the callback's response. Any messages
+/// sent by the handler can be retrieved using `websocket_sent_text_messages`
+/// or `websocket_sent_binary_messages`.
+///
+/// If the websocket has been closed, this function returns the websocket
+/// unchanged without calling the handler.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(ws) = simulate.create_websocket(handler)
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "Hello")
+/// let assert ["Echo: Hello"] = simulate.websocket_sent_text_messages(ws)
+/// ```
+///
+/// ## Returns
+///
+/// - `Ok(WebSocket)` - The websocket with updated state
+/// - `Error(Nil)` - If the handler returns `Stop` or `StopWithError`
 ///
 pub fn send_websocket_text(
   ws: WebSocket,
@@ -471,8 +601,28 @@ pub fn send_websocket_text(
   }
 }
 
-/// Simulate sending a binary message to a websocket handler.
-/// Returns the updated state and any effects that occurred.
+/// Simulate sending a binary message to the websocket handler.
+///
+/// This calls the handler's `on_message` callback with a `Binary` message. The
+/// handler's state is updated based on the callback's response. Any messages
+/// sent by the handler can be retrieved using `websocket_sent_text_messages`
+/// or `websocket_sent_binary_messages`.
+///
+/// If the websocket has been closed, this function returns the websocket
+/// unchanged without calling the handler.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(ws) = simulate.create_websocket(handler)
+/// let assert Ok(ws) = simulate.send_websocket_binary(ws, <<1, 2, 3>>)
+/// let assert [<<1, 2, 3>>] = simulate.websocket_sent_binary_messages(ws)
+/// ```
+///
+/// ## Returns
+///
+/// - `Ok(WebSocket)` - The websocket with updated state
+/// - `Error(Nil)` - If the handler returns `Stop` or `StopWithError`
 ///
 pub fn send_websocket_binary(
   ws: WebSocket,
@@ -496,8 +646,32 @@ pub fn send_websocket_binary(
   }
 }
 
-/// Simulate closing a websocket connection.
-/// Returns the updated state representing the closed connection.
+/// Simulate closing the websocket connection.
+///
+/// This calls the handler's `on_close` callback with the current handler state.
+/// After closing, any subsequent calls to `send_websocket_text` or
+/// `send_websocket_binary` will be ignored without calling the handler.
+///
+/// Use `reset_websocket` to re-open the connection for further testing.
+///
+/// ## Example
+///
+/// ```gleam
+/// let assert Ok(ws) = simulate.create_websocket(handler)
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "Hello")
+///
+/// // Close the connection
+/// let assert Ok(Nil) = simulate.close_websocket(ws)
+///
+/// // Further messages are ignored
+/// let assert Ok(ws) = simulate.send_websocket_text(ws, "After close")
+/// let assert ["Response 1"] = simulate.websocket_sent_text_messages(ws)
+/// ```
+///
+/// ## Returns
+///
+/// - `Ok(Nil)` - If the connection was closed successfully
+/// - `Error(WebSocketError)` - If closing the connection failed
 ///
 pub fn close_websocket(
   websocket: WebSocket,