84 lines
3.3 KiB
Markdown
84 lines
3.3 KiB
Markdown
|
# wizardconnect
|
||
|
|
|
||
|
|
Relay-based protocol library for connecting dapps to HD wallets over WebSocket (Nostr NIP-17 gift-wrapped messages).
|
||
|
|
|
||
|
|
## Testing philosophy
|
||
|
|
|
||
|
|
Tests are more important than the code itself. A correct implementation that lacks tests is worse than a slightly imperfect implementation that is well-tested, because untested code will silently break and the breakage will only surface in production — often as subtle protocol bugs that are hard to reproduce.
|
||
|
|
|
||
|
|
This codebase communicates over a live relay with timing-sensitive handshakes and stateful reconnection logic. These bugs cannot be caught by reading the code. They only appear in integration tests that exercise the real relay.
|
||
|
|
|
||
|
|
**Always write tests before or alongside any non-trivial change.** If you add a feature, add a test. If you fix a bug, add a regression test that would have caught it.
|
||
|
|
|
||
|
|
### Test types
|
||
|
|
|
||
|
|
**Unit tests** (`npm test` in a package):
|
||
|
|
- Fast, no network, run on every change
|
||
|
|
- Test individual functions and classes in isolation
|
||
|
|
- Use vitest, mock external deps
|
||
|
|
- Should cover all edge cases in pure logic (state managers, message builders, URI encoding, etc.)
|
||
|
|
|
||
|
|
**Integration tests** (`npm run test:integration` in a package):
|
||
|
|
- Hit the real relay at `wss://relay.cauldron.quest:443`
|
||
|
|
- Test the full protocol handshake end-to-end
|
||
|
|
- Located in `src/__tests__/*.integration.test.ts`
|
||
|
|
- Run with generous timeouts (60s per test) via `vitest.integration.config.ts`
|
||
|
|
- Must pass before any release
|
||
|
|
|
||
|
|
### Running tests
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# All packages, unit tests only (fast):
|
||
|
|
npm run test
|
||
|
|
|
||
|
|
# Wallet package integration tests (requires network):
|
||
|
|
cd packages/wallet && npm run test:integration
|
||
|
|
|
||
|
|
# Custom relay:
|
||
|
|
TEST_RELAY_URL=wss://your-relay:443 npm run test:integration
|
||
|
|
```
|
||
|
|
|
||
|
|
### Test CLI (manual/exploratory testing)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Start a dapp session and watch the protocol:
|
||
|
|
npm run dapp
|
||
|
|
|
||
|
|
# Connect a test wallet to a dapp URI:
|
||
|
|
npm run wallet -- --uri wiz://...
|
||
|
|
|
||
|
|
# Test the approval flow:
|
||
|
|
npm run dapp -- --sign
|
||
|
|
```
|
||
|
|
|
||
|
|
The test CLI (`packages/test-cli/`) is not a substitute for automated tests — it is a debugging tool.
|
||
|
|
|
||
|
|
## Documentation
|
||
|
|
|
||
|
|
Protocol and architecture documentation lives in `docs/`. Keep it up to date when making changes:
|
||
|
|
|
||
|
|
| File | Update when… |
|
||
|
|
|------|-------------|
|
||
|
|
| `docs/protocol.md` | Protocol messages, handshake logic, or `PathName`/`PathXpub`/`NextIndex` types change |
|
||
|
|
| `docs/connection-uri.md` | URI format, key exchange flow, or credential structure changes |
|
||
|
|
| `docs/transport.md` | `RelayClient`, `initiateRelay`, reconnect logic, or encryption scheme changes |
|
||
|
|
| `docs/wallet.md` | `WalletAdapter`, `WalletConnectionManager`, or connection lifecycle changes |
|
||
|
|
| `docs/dapp.md` | `DappConnectionManager` API or session lifecycle changes |
|
||
|
|
| `docs/pubkey-derivation.md` | xpub delivery, `DappPubkeyStateManager`, or gap-fill logic changes |
|
||
|
|
| `docs/index.md` | New top-level docs files are added |
|
||
|
|
|
||
|
|
## Packages
|
||
|
|
|
||
|
|
- `@wizardconnect/core` — transport + protocol primitives (relay client, key exchange, hdwalletv1 message types)
|
||
|
|
- `@wizardconnect/wallet` — wallet-side helpers (`WalletConnectionManager`, `WalletAdapter`, `PubkeyStateManager`)
|
||
|
|
- `@wizardconnect/test-cli` — manual test CLI (`dapp` and `wallet` modes)
|
||
|
|
|
||
|
|
## Build
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install
|
||
|
|
npm run build # builds all packages in dependency order
|
||
|
|
```
|
||
|
|
|
||
|
|
Packages must be built before integration tests run (tests import from `dist/`).
|