@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 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(), function() | :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 fake/3 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 fake/3 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(), module()) :: module()

Set a fake implementation as the fallback for a contract.

Fakes have real logic — they maintain state or delegate to a real implementation module. They handle any operation not covered by an expect or per-operation stub.

FakeHandler module (recommended for stateful fakes)

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

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

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

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

Module fake

A module implementing the contract's @behaviour (but not FakeHandler). All unhandled operations delegate via apply(module, operation, args):

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

The module is validated immediately — all contract operations must be exported.

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. For stubs to be visible, the module must call through the facade.

Stateful fake 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.fake(MyContract, &handler/4, initial_state)

The fake's state is threaded through calls automatically. When an expect short-circuits (e.g. returning an error), the fake state is unchanged — correct for error simulation.

Dispatch priority: expects > per-operation stubs > fake > raise. Function fallback (stub/2), module fake, and stateful fake are mutually exclusive — setting one replaces the other.

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.fake(&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(), function() | module()) :: module()

Add a stub for a contract operation or a stateless function fallback.

Per-operation stub

The function receives the argument list and returns the result. 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 function may be:

• 1-arity fn [args] -> result end — stateless
• 2-arity fn [args], state -> {result, new_state} end — stateful (requires fake/3 first)
• 3-arity fn [args], state, all_states -> {result, new_state} end — cross-contract state access (requires fake/3 first)

Any arity may return Double.passthrough() to delegate to the fallback/fake for that specific call.

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

Function fallback (2-arity function)

When the function is 2-arity fn operation, args -> result end, it acts as a fallback for any operation on the contract that has no per-operation expect or stub. This is the same signature as set_fn_handler, so existing handler functions can be reused:

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

StubHandler module

A module implementing DoubleDown.Contract.Dispatch.StubHandler. The module's new/2 builds a dispatch function from an optional fallback:

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

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

For stateful fakes and module delegation, see fake/2 and fake/3.

Dispatch priority: expects > per-operation stubs > fallback/fake > raise. Function fallback, StubHandler, stateful fake, and module fake are mutually exclusive — setting one replaces the other.

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.