http_server_mock - v1.0.0

http_server_mock/stub_builder

Builder for Stub — pairs a request matcher with a response definition.

Start with new(), set a matcher via matching() and a response via responding_with(), then call build() to produce a Stub you can register with the server.

Phantom types enforce that both matching and responding_with have been called: passing a partially-configured builder to build is a compile error.

For stateful sequences, call in_scenario first, then optionally when_state_is and then_transition_to — calling the latter two without in_scenario is a compile error enforced by the WithScenario phantom type.

import gleam/http
import http_server_mock/matcher
import http_server_mock/response
import http_server_mock/stub_builder

let stub =
  stub_builder.new()
  |> stub_builder.matching(matcher.new() |> matcher.method(http.Post) |> matcher.path("/users"))
  |> stub_builder.responding_with(response.created())
  |> stub_builder.build()

Types

StubBuilder

opaque </>

A stub under construction.

Three phantom type parameters track builder state:

  • matcher_state — WithoutMatcher until matching is called
  • response_state — WithoutResponse until responding_with is called
  • scenario_state — WithoutScenario until in_scenario is called

Only StubBuilder(WithMatcher, WithResponse, _) can be passed to build. Forgetting either matching or responding_with is a compile error. Calling when_state_is or then_transition_to before in_scenario is also a compile error.

pub opaque type StubBuilder(matcher_state, response_state, scenario_state)

WithMatcher

</>

Phantom type indicating a matcher has been set on a StubBuilder.

pub type WithMatcher

WithResponse

</>

Phantom type indicating a response has been set on a StubBuilder.

pub type WithResponse

WithScenario

</>

Phantom type indicating in_scenario has been called on a StubBuilder. Required before calling when_state_is or then_transition_to.

pub type WithScenario

WithoutMatcher

</>

Phantom type indicating no matcher has been set on a StubBuilder yet.

pub type WithoutMatcher

WithoutResponse

</>

Phantom type indicating no response has been set on a StubBuilder yet.

pub type WithoutResponse

WithoutScenario

</>

Phantom type indicating in_scenario has not yet been called on a StubBuilder.

pub type WithoutScenario

Values

build

</> 
pub fn build(
  builder: StubBuilder(WithMatcher, WithResponse, scenario_state),
) -> types.Stub

Builds the concrete Stub from this builder.

Only callable when both matching and responding_with have been called — the phantom types enforce this at compile time.

Pass the result to http_server_mock.with_stub or http_server_mock.add_stub.

in_scenario

</> 
pub fn in_scenario(
  builder: StubBuilder(
    matcher_state,
    response_state,
    scenario_state,
  ),
  name: String,
) -> StubBuilder(matcher_state, response_state, WithScenario)

Places this stub inside the named scenario, transitioning the builder to WithScenario.

Scenarios allow a sequence of stubs to fire in order: the first time the matcher fires it transitions state; subsequent calls match the next stub. Must be called before when_state_is or then_transition_to.

matching

</> 
pub fn matching(
  builder: StubBuilder(
    matcher_state,
    response_state,
    scenario_state,
  ),
  request_matcher: types.RequestMatcher,
) -> StubBuilder(WithMatcher, response_state, scenario_state)

Sets the request matcher, transitioning the builder to WithMatcher.

new

</> 
pub fn new() -> StubBuilder(
  WithoutMatcher,
  WithoutResponse,
  WithoutScenario,
)

Creates an empty stub builder with no matcher, response, or scenario set.

responding_with

</> 
pub fn responding_with(
  builder: StubBuilder(
    matcher_state,
    response_state,
    scenario_state,
  ),
  response_def: types.ResponseDefinition,
) -> StubBuilder(matcher_state, WithResponse, scenario_state)

Sets the response definition, transitioning the builder to WithResponse.

then_transition_to

</> 
pub fn then_transition_to(
  builder: StubBuilder(
    matcher_state,
    response_state,
    WithScenario,
  ),
  new_state: String,
) -> StubBuilder(matcher_state, response_state, WithScenario)

Transitions the scenario to the given state after this stub fires.

Requires in_scenario to have been called first — enforced at compile time.

when_state_is

</> 
pub fn when_state_is(
  builder: StubBuilder(
    matcher_state,
    response_state,
    WithScenario,
  ),
  state: String,
) -> StubBuilder(matcher_state, response_state, WithScenario)

Makes this stub only fire when the scenario is in the given state.

Requires in_scenario to have been called first — enforced at compile time.

with_id

</> 
pub fn with_id(
  builder: StubBuilder(
    matcher_state,
    response_state,
    scenario_state,
  ),
  id: String,
) -> StubBuilder(matcher_state, response_state, scenario_state)

Assigns a custom ID to this stub.

IDs are used with remove_stub to unregister a specific stub. If not set, a unique ID is generated automatically.

with_priority

</> 
pub fn with_priority(
  builder: StubBuilder(
    matcher_state,
    response_state,
    scenario_state,
  ),
  priority: Int,
) -> StubBuilder(matcher_state, response_state, scenario_state)

Sets the priority for this stub.

Lower values win when multiple stubs match a request. Defaults to 5.

✨ Search Document