@spec allow(module(), pid(), pid() | (-> pid() | [pid()])) :: :ok | {:error, term()}

Allow a child process to use the current process's test doubles.

Delegates to DoubleDown.Testing.allow/3. Use this when spawning Tasks or other processes that need to dispatch through the same test handlers.

{:ok, pid} = MyApp.Worker.start_link([])
DoubleDown.Double.allow(MyContract, pid)

Also accepts a lazy pid function for processes that don't exist yet at setup time:

DoubleDown.Double.allow(MyContract, fn -> GenServer.whereis(MyWorker) end)

@spec defer((-> term())) :: DoubleDown.Contract.Dispatch.Defer.t()

Create a deferred execution marker for use in expect/stub/fake bodies.

When a handler body needs to call another facade (including Backend.Repo), wrapping the call in defer/1 avoids deadlocking the NimbleOwnership GenServer. The deferred function runs outside the lock, in the calling process, after the handler's state update has been committed.

# Stateful fake that calls another contract:
Counter
|> Double.fallback(fn
  _contract, :increment, [n], count ->
    {Double.defer(fn ->
      greeting = Greeter.greet("from_counter")
      {greeting, n}
    end), count + n}

  _contract, :get_count, [], count ->
    {count, count}
end, 0)

# Stateless stub that calls Repo:
Double.stub(MyContract, :find_config, fn [org_id] ->
  Double.defer(fn ->
    Backend.Repo.get_by(Config, organisation_id: org_id)
  end)
end)

When you need defer: any time an expect, stub, or fake body calls through a facade — the handler runs inside a NimbleOwnership lock, and a nested dispatch would deadlock without it.

@spec dynamic(module()) :: module()

Set up a dynamically-faked module with its original implementation as the fallback.

Requires the module to have been set up with DoubleDown.DynamicFacade.setup/1. Layer expects and stubs on top:

SomeClient
|> DoubleDown.Double.dynamic()
|> DoubleDown.Double.expect(:fetch, fn [_] -> {:error, :timeout} end)

Calls without a matching expect or stub delegate to the original module's implementation.

Returns the module for piping.

@spec expect(
  module(),
  atom(),
  DoubleDown.Double.Types.expect_fun() | :passthrough,
  keyword()
) ::
  module()

Add an expectation for a contract operation.

The responder function may be:

• 1-arity fn [args] -> result end — stateless, returns a bare result
• 2-arity fn [args], state -> {result, new_state} end — reads and updates the stateful fake's state. Requires a stateful fallback (fallback/2..4) first.
• 3-arity fn [args], state, all_states -> {result, new_state} end — same as 2-arity plus a read-only snapshot of all contract states for cross-contract access. Requires a stateful fallback (fallback/2..4) first.

Expectations are consumed in order — the first expect for an operation handles the first call, the second handles the second, and so on.

Instead of a function, pass :passthrough to delegate to the fallback (fn, stateful, or module) while still consuming the expect for verify! counting.

Returns the contract module for piping.

Options

• :times — enqueue the same function n times (default 1). Equivalent to calling expect n times with the same function.

@spec fake(module(), atom(), DoubleDown.Double.Types.fake_fun()) :: module()

Add a per-operation fake for a contract operation.

Overrides a single operation with a stateful function that reads and updates the fallback's state. Requires a stateful fallback to be installed first via fallback/3:

DoubleDown.Repo
|> DoubleDown.Double.fallback(&Repo.OpenInMemory.dispatch/4, Repo.OpenInMemory.new())
|> DoubleDown.Double.fake(:insert, fn [changeset], state ->
  {{:error, add_error(changeset, :email, "taken")}, state}
end)

The function may be:

• 2-arity fn [args], state -> {result, new_state} end
• 3-arity fn [args], state, all_states -> {result, new_state} end (cross-contract state access)

Per-op fakes are permanent (not consumed like expects) and can return Double.passthrough() to delegate to the fallback. Setting a per-op fake twice for the same operation replaces the previous one.

For whole-contract fallback handlers, see fallback/2..4.

Dispatch priority: expects > per-op fakes > per-op stubs > fallback > raise.

Returns the contract module for piping.

@spec fallback(module(), function() | module()) :: module()

Install a whole-contract fallback handler.

The fallback handles any operation not covered by an expect, per-op fake, or per-op stub. Several forms are supported:

StatefulHandler module (recommended for stateful fallbacks)

A module implementing DoubleDown.Contract.Dispatch.StatefulHandler. The module's new/2 builds initial state, and its dispatch/4 or dispatch/5 handles operations:

# Default state
DoubleDown.Double.fallback(MyContract, Repo.OpenInMemory)

# With seed data
DoubleDown.Double.fallback(MyContract, Repo.OpenInMemory, [%User{id: 1}])

# With seed data and options
DoubleDown.Double.fallback(MyContract, Repo.OpenInMemory, [%User{id: 1}],
  fallback_fn: fn _contract, :all, [User], state -> Map.values(state[User]) end
)

StatelessHandler module

A module implementing DoubleDown.Contract.Dispatch.StatelessHandler. The module's new/2 builds a stateless dispatch function:

# Writes only — reads will raise
DoubleDown.Double.fallback(MyContract, DoubleDown.Repo.Stub)

# With a fallback function for reads
DoubleDown.Double.fallback(MyContract, DoubleDown.Repo.Stub,
  fn _contract, :all, [User] -> [] end)

Module implementation

A module implementing the contract's @behaviour (but not a StatefulHandler or StatelessHandler). All operations delegate via apply(module, operation, args):

DoubleDown.Double.fallback(MyContract, MyApp.Impl)

Mimic-style limitation: if the module's :bar internally calls :foo, and you've stubbed :foo, the module won't see your stub — it calls its own :foo directly.

Stateful function

A 4-arity fn contract, operation, args, state -> {result, new_state} end or 5-arity fn contract, operation, args, state, all_states -> {result, new_state} end with initial state:

DoubleDown.Double.fallback(MyContract, &handler/4, initial_state)

Stateless function

A 3-arity fn contract, operation, args -> result end:

DoubleDown.Double.fallback(MyContract, fn _contract, operation, args ->
  case {operation, args} do
    {:list, [_]} -> []
    {:count, []} -> 0
  end
end)

Fallback types are mutually exclusive — setting one replaces the other.

Dispatch priority: expects > per-op fakes > per-op stubs > fallback > raise.

Returns the contract module for piping.

@spec passthrough() :: DoubleDown.Contract.Dispatch.Passthrough.t()

Return a passthrough sentinel for use in expect responders.

When returned from an expect responder, delegates the call to the fallback/fake as if the expect had been registered with :passthrough. The expect is still consumed for verify! counting.

This enables conditional passthrough — the responder can inspect the state and decide whether to handle the call or delegate:

DoubleDown.Repo
|> Double.fallback(&Repo.OpenInMemory.dispatch/4, Repo.OpenInMemory.new())
|> Double.expect(:insert, fn [changeset], state ->
  if duplicate?(state, changeset) do
    {{:error, add_error(changeset, :email, "taken")}, state}
  else
    Double.passthrough()
  end
end)

@spec stub(module(), atom(), DoubleDown.Double.Types.stub_fun()) :: module()

Add a per-operation stub for a contract operation.

The function receives the argument list and returns the result. Stubs are stateless — for stateful per-operation overrides, use fake/3 or expect/4 with a 2-arity or 3-arity responder.

Stubs handle any number of calls and are used after all expectations for an operation are consumed. Setting a stub twice for the same operation replaces the previous one.

The stub may return Double.passthrough() to delegate to the fallback for that specific call.

DoubleDown.Double.stub(MyContract, :list, fn [_] -> [] end)

For whole-contract fallback handlers, see fallback/2..4.

Dispatch priority: expects > per-op fakes > per-op stubs > fallback > raise.

Returns the contract module for piping.

@spec verify!() :: :ok

Verify that all expectations have been consumed.

Reads the current handler state for each contract and checks that all expect queues are empty. Stubs are not checked — they are allowed to be called zero or more times.

Raises with a descriptive message if any expectations remain unconsumed.

Returns :ok if all expectations are satisfied.

@spec verify!(pid()) :: :ok

Verify expectations for a specific process.

Same as verify!/0 but checks the expectations owned by pid instead of the calling process. Used internally by verify_on_exit!/0.

@spec verify_on_exit!(map()) :: :ok

Register an on_exit callback that verifies expectations after each test.

Call this in a setup block so that tests which forget to call verify!/0 explicitly still fail on unconsumed expectations:

setup :verify_on_exit!

Or equivalently:

setup do
  DoubleDown.Double.verify_on_exit!()
end

The verification runs in the on_exit callback (a separate process), using the test pid captured at setup time.