dione/test/README.md

cbBTC Dashboard Test Suite

The test suite is organized under the /test folder. All tests run in Node.js with ES modules and mock browser APIs (localStorage, WebSocket, BroadcastChannel, window.ethereum). The setup file test/test_setup.mjs provides the global location object that stream.js requires at import time.

Files

File	Targets	Requires	How to run
test/test_wallets.js	WalletManager — CRUD, persistence, security	None	node --experimental-modules test/test_wallets.js
test/test_stream.js	WalletStreamManager — WebSocket, backoff, routing	test/test_setup.mjs	node --experimental-modules --import ./test/test_setup.mjs ./test/test_stream.js
test/test_tabs.js	WalletStreamManager — multi-tab leader election, failover	test/test_setup.mjs	node --experimental-modules --import ./test/test_setup.mjs ./test/test_tabs.js
test/test_verifier.js	WalletVerifier — Web3 provider error handling	None	node --experimental-modules test/test_verifier.js
test/test_setup.mjs	Provides globalThis.location for stream.js	—	Imported via --import

What Can Be Tested — by Module

1. WalletManager (test_wallets.js)

The WalletManager class manages tracked wallets in localStorage. The test suite covers:

Address Validation

• Rejection of invalid address formats per chain (EVM, Bitcoin, Solana).
• Acceptance of valid addresses for EVM (0x...), Bitcoin legacy (1...), and Solana base58 patterns.

CRUD (Create/Read/Update/Delete)

• addWallet() — adds wallets, persists to storage, returns success/error.
• getWallets() — returns deep copies of tracked wallets.
• findWallet() — returns wallet object or undefined.
• removeWallet() — splices wallet from state and persists.

Duplicate Guard

• Same address + chain pair is rejected on second addWallet() call.

Verification Lifecycle

• Wallets start with isVerified: false.
• verifyWallet() sets the flag to true and stores the signature.
• revokeVerification() resets the flag and clears the signature.

Security: localStorage Tampering

• loadWallets() always resets isVerified to false on restart, regardless of what was written to storage. This prevents a user from forging verification by editing localStorage directly.

2. WalletVerifier (test_verifier.js)

The WalletVerifier class handles Web3 provider interactions. The test suite covers error-path cases:

Missing Extension

• When window.ethereum is undefined, verification fails with "No Web3 wallet extension found".

User Rejection (Account Request)

• When the user denies eth_requestAccounts (EIP-1193 error 4001), verification cancels with "Verification cancelled".

Signature Rejection

• When the user denies the typed-data signature request, the error is mapped to "rejected".

3. WalletStreamManager — Core (test_stream.js)

The WalletStreamManager class manages the WebSocket connection, event routing, and reconnect logic with exponential backoff. The test suite covers:

Multiplexed Subscription

• On connect, the manager sends a single subscribe frame containing all tracked wallets (from WalletManager).

Event Routing

• Incoming server messages are parsed and dispatched to registered on('balance_update', ...) callbacks.
• Events route by data.type (or data.event, or fallback 'message').

Callback Error Isolation

• If one registered callback throws, remaining callbacks for the same event still execute. Exceptions are caught and logged but never propagate.

Dynamic Subscription

• subscribeToNewWallet() sends an immediate subscribe_wallet frame without cycling the connection.

Exponential Backoff + Jitter

• On network drop (simulateNetworkDrop()), the manager retries connecting. The delay follows BASE_DELAY * 2^attempt with ±25% jitter, capped at MAX_DELAY (30s).
• Tests speed up time by overriding setTimeout to fire instantly.

4. WalletStreamManager — Multi-Tab (test_tabs.js)

The leader/follower election and cross-tab synchronization system relies on BroadcastChannel and localStorage heartbeats. The test suite covers:

Leader Election

• First tab to connect finds no heartbeat in localStorage, claims leadership, opens the WebSocket, and starts heartbeats.
• Second tab finds the heartbeat, assigns itself as a follower, and avoids opening a second WebSocket.

Cross-Tab Event Broadcasting

• Leader receives server data on the WebSocket and posts it to BroadcastChannel.
• Followers receive the broadcast and dispatch it to their local listeners.

Proxy Subscription Forwarding

• When a follower calls subscribeToNewWallet(), the request is sent through BroadcastChannel to the leader, which opens the actual network subscription.

Automatic Failover

• When the leader tab closes (disconnect()), it broadcasts LEADER_DEATH before closing the channel.
• Followers detect the signal, claim leadership, remove the old heartbeat, write a new one, and open their own WebSocket connection.

Mock Infrastructure

All tests replace browser APIs with in-memory equivalents:

• localStorage — plain object (mockStorage) with getItem, setItem, removeItem, clear.
• setTimeout — overridden to fire callbacks after 1ms instead of the specified delay, so backoff/retry logic runs instantly.
• WebSocket — MockWebSocket auto-opens after 2ms, exposes simulateServerPush() and simulateNetworkDrop() helpers.
• BroadcastChannel — MockBroadcastChannel delivers messages synchronously to all other registered channels, simulating cross-tab delivery.

Extending the Test Suite

To add a new test:

1. Add a describe/it block or inline assert inside the relevant test_<module>.js file.
2. For stream-related tests, ensure the file is imported via --import ./test/test_setup.mjs.
3. Run the test from the project root with the appropriate command.

To add a new module test:

1. Create test/test_<module>.js with imports using ../<module>.js (relative to the /test folder).
2. Add the required mock infrastructure at the top.
3. Register it in this README with its run command.