# `Filament.Test.Stub`

Convenience API for creating and driving observable stubs in tests.

Usage in mount opts:

    stubs: [{CartServer, fn _req -> %{items: [], total: 0} end}]

This creates a StubObservable for CartServer. Components calling
use_observable(CartServer, ...) receive the stub's value instead.

To push an update after mount:

    Filament.Test.Stub.push(stub_pid, %{items: ["x"], total: 10})

# `build`

```elixir
@spec build([{server :: term(), stub_fn :: function()}]) ::
  {stubs_map :: %{required(term()) => pid()}, pids :: [pid()]}
```

Build the observable_stubs map expected by Filament.Test.mount/2.
Starts a StubObservable for each {server, stub_fn} pair.
Returns `{stubs_map, pids}` where `stubs_map` is `%{server => pid}` and
`pids` is the list of started stub pids (for cleanup in on_exit).

# `push`

```elixir
@spec push(stub :: pid(), new_state :: term()) :: :ok
```

Push `new_state` to all current subscribers of the stub.
Triggers the same notification path as a real observable's notify_observers/1,
including per-subscriber projection and change-or-bust from D3.

# `start`

```elixir
@spec start(
  stub_fn :: (request :: term() -> initial_value :: term()),
  opts :: keyword()
) ::
  {:ok, pid()}
```

Start a stub observable backed by `stub_fn`.
`stub_fn` receives the subscription request and returns the initial value.

Returns `{:ok, pid}`.

# `state`

```elixir
@spec state(stub :: pid()) :: term()
```

Read back the last state that was pushed to (or initially set in) the stub.

---

*Consult [api-reference.md](api-reference.md) for complete listing*