dream_mock_server - v1.1.1

dream_mock_server/server

Programmatic Server Control

This module provides functions to start and stop the mock server programmatically. This is useful for integration tests where you need complete control over the server lifecycle.

Usage in Tests

import dream_mock_server/server
import gleam/http/request
import gleam/httpc

pub fn my_streaming_test() {
  // Start the mock server
  let assert Ok(handle) = server.start(3004)
  
  // Make HTTP requests to localhost:3004
  let assert Ok(response) = 
    request.to("http://localhost:3004/stream/fast")
    |> httpc.send
  
  // Stop the server
  server.stop(handle)
}

Available Endpoints

Non-streaming endpoints:

Streaming endpoints:

Values

start

</> 
pub fn start(
  port: Int,
) -> Result(server.ServerHandle, actor.StartError)

Start the mock server on a specific port

Returns a ServerHandle that can be used to stop the server later. The port must be explicitly provided - there is no default.

Example

import dream_mock_server/server

let assert Ok(handle) = server.start(3004)
// ... make HTTP requests to localhost:3004 ...
server.stop(handle)

Errors

Returns an error if the server fails to start, typically due to:

  • Port already in use - Another process is bound to the port
  • Insufficient permissions - Port < 1024 requires root on Unix systems
  • System resource limits - OS limits on open files/sockets reached

Port Conflicts

If the port is already in use, the OTP supervisor will crash with Eaddrinuse. This is expected OTP behavior for startup errors - port conflicts are configuration problems that should fail loudly and immediately. Ensure ports are available before starting the server, or catch the supervisor crash at the deployment level if needed.

start_with_config

</> 
pub fn start_with_config(
  port: Int,
  config: List(config.MockRoute),
) -> Result(server.ServerHandle, actor.StartError)

Start the mock server with caller-provided routes.

In this mode, the server uses only the supplied config list and does not expose the built-in demo endpoints from start(port).

Matching semantics

  • Routes are evaluated in list order.
  • First matching route wins.
  • A route matches when both are true:
    • Path matches according to path_match (Exact or Prefix)
    • Method matches (Some(method)) or the route method is None
  • If no route matches, response is 404 with body "Not found".

Returns a ServerHandle that can be used to stop the server later.

Example

import dream_mock_server/config.{MockRoute, Prefix}
import dream_mock_server/server
import gleam/option.{None}

let config = [
  MockRoute("/v1/chat/completions", Prefix, None, 200, "{\"ok\":true}"),
]
let assert Ok(handle) = server.start_with_config(3004, config)
// ... make requests to localhost:3004 ...
server.stop(handle)

Typical use cases

  • Deterministic proxy/adaptor tests
  • Verifying status and payload handling branches
  • Simulating external API behavior without provider-specific stubs

stop

</> 
pub fn stop(handle: server.ServerHandle) -> Nil

Stop the mock server

Gracefully stops the server using the provided handle. This function is idempotent - calling it multiple times with the same handle is safe.

Example

import dream_mock_server/server

let assert Ok(handle) = server.start(3004)
// ... do work ...
server.stop(handle)
✨ Search Document