# Module BSV::Wallet::Fixtures <a id="module-BSV-Wallet-Fixtures"></a>

Dev/test named-wallet registry.

Centralises every named-wallet fixture the wallet uses — `alice`, `bob`,
`carol` (integration specs), `sdk` (e2e harness funder), `w1`..`w5` (e2e
wallet fleet), `test` (unit spec DB). Companion to {BSV::Wallet.configure} —
same audience-split frame: end-user config is
<code>BSV::Wallet.configure</code>, dev/test fixtures are
<code>BSV::Wallet::Fixtures.configure</code>.

Three usage modes:

    1. Do nothing — operators with a complete shell ENV
       (BSV_WALLET_WIF_<NAME>, BSV_WALLET_POSTGRES) get the
       standard registrations via the gem-bundled default at
       +config/fixtures.rb+ (auto-loaded if no user override).

    2. Pin values in +~/.bsv-wallet/fixtures.rb+:
         f.wallet :alice, wif: 'L1...', database_url: 'postgres://...'

    3. Register dynamically at runtime — the e2e harness derives
       +w1+..+w5+ WIFs from the funding key and registers each.

- **@see** `BSV::Wallet::Fixtures.configure`
- **@see** `BSV::Wallet::Fixtures.load_config_file!`

## Constants
### `DEFAULT_FILE` <a id="constant-DEFAULT_FILE"></a> <a id="DEFAULT_FILE-constant"></a>
Path to the gem-bundled default fixtures file. Auto-loaded when no user
override exists, so a fresh checkout / CI runner picks up the standard
`alice`/`bob`/`carol`/`sdk`/`w1`..`w5` registrations from shell ENV without
any setup.

## Public Class Methods
### `configure()` <a id="method-c-configure"></a> <a id="configure-class_method"></a>
Configuration block — yields the singleton Registry so the user's
+~/.bsv-wallet/fixtures.rb+ (or runtime callers like the e2e harness) can
register wallets.

    BSV::Wallet::Fixtures.configure do |f|
      f.postgres_base = ENV.fetch('BSV_WALLET_POSTGRES', nil)
      f.wallet :alice, wif: ENV.fetch('BSV_WALLET_WIF_ALICE', nil)
    end
- **@return** [Registry]
- **@yield** [Registry]

### `load_config_file!(path = nil)` <a id="method-c-load_config_file-21"></a> <a id="load_config_file!-class_method"></a>
Load the dev/test fixtures file.

Resolution: tries each candidate in order, uses the first that exists —
explicit `path` argument > `BSV_WALLET_FIXTURES` env var >
+~/.bsv-wallet/fixtures.rb+ (user override) > `DEFAULT_FILE` (gem-bundled).
The gem default registers the standard named wallets from shell ENV, so an
operator with `BSV_WALLET_POSTGRES` + +BSV_WALLET_WIF_<NAME>+ set needs no
personal fixtures file. Errors propagate.

<strong>Idempotent.</strong> Returns nil on every call after the first (until
<code>reset!</code>) so callers (e.g. <code>CLI.boot</code>) can defensively
invoke this without overwriting earlier registrations from the same process
(e.g. the e2e harness's derived `w1`..`w5` WIFs).
- **@param** `path` [String, nil]
- **@return** [String, nil] path loaded, or nil if already loaded /
no file resolves

### `registry()` <a id="method-c-registry"></a> <a id="registry-class_method"></a>
Singleton registry. Lazy: first access instantiates.
- **@return** [Registry]

### `reset!()` <a id="method-c-reset-21"></a> <a id="reset!-class_method"></a>
Reset the singleton — drops all registrations AND the "already-loaded" flag so
the next `registry` access starts fresh and the next
<code>load_config_file!</code> call loads a file again. Test helper.

### `wallet(name)` <a id="method-c-wallet"></a> <a id="wallet-class_method"></a>
Look up a named fixture wallet. Returns nil when the name is not registered.
- **@param** `name` [Symbol, String]
- **@return** [Wallet, nil]