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

Allow a child process to use the current process's handlers.

Use this when spawning Tasks or other processes that need to dispatch through the same test handlers.

@spec enable_log(module()) :: :ok

Enable dispatch logging for a contract.

After enabling, all dispatches through X.Port will be recorded. Retrieve with get_log/1.

@spec get_log(module()) :: [{module(), atom(), [term()], term()}]

Retrieve the dispatch log for a contract.

Returns a list of {contract, operation, args, result} tuples in the order they were dispatched.

@spec reset() :: :ok

Reset all handlers and logs for the current process.

@spec set_fn_handler(module(), (atom(), [term()] -> term())) :: :ok

Register a function as the handler for a contract.

The function receives (operation, args) and returns the result.

@spec set_handler(module(), module()) :: :ok

Register a module as the handler for a contract.

The module must implement the contract's @behaviour.

@spec set_mode_to_global() :: :ok

Set the ownership server to global mode.

In global mode, all handlers registered by the calling process are visible to every process in the VM — no allow/3 calls needed. This is useful for integration-style tests that involve supervision trees, named GenServers, Broadway pipelines, or Oban workers where individual process pids are not easily accessible.

The calling process becomes the "shared owner". Any handlers set by this process (before or after calling set_mode_to_global/0) are accessible to all processes.

Warning

Global mode is incompatible with async: true. When global mode is active, all tests share the same handlers, so concurrent tests will interfere with each other. Only use global mode in tests with async: false.

Call set_mode_to_private/0 to restore per-process isolation.

Example

setup do
  DoubleDown.Testing.set_mode_to_global()
  DoubleDown.Testing.set_handler(MyApp.Repo, MyApp.Repo.OpenInMemory)
  on_exit(fn -> DoubleDown.Testing.set_mode_to_private() end)
  :ok
end

@spec set_mode_to_private() :: :ok

Restore the ownership server to private (per-process) mode.

After calling this, handlers are once again scoped to the process that registered them. Use this to clean up after set_mode_to_global/0.

@spec set_stateful_handler(module(), (... -> {term(), term()}), term()) :: :ok

Register a stateful handler for a contract.

The function may be 4-arity or 5-arity:

• 4-arity: fn contract, operation, args, state -> {result, new_state} end
• 5-arity: fn contract, operation, args, state, all_states -> {result, new_state} end

5-arity handlers receive a read-only snapshot of all contract states as the 5th argument. This enables cross-contract state access (e.g. a Queries handler reading the Repo InMemory store). The all_states map is keyed by contract module and includes a DoubleDown.Contract.GlobalState sentinel key. The handler must return only its own contract's new state — not the global map.

State is stored in NimbleOwnership and updated atomically on each dispatch.

@spec start() :: {:ok, pid()} | {:error, term()}

Start the DoubleDown ownership server.

Call this once in test/test_helper.exs.