Testing

Two suites, deliberately separated

Unit -- bun test test/unit

40 tests, 0 network calls, ~200ms total. Runs on every change.

E2e -- bun test test/e2e

9 tests, real testnet transactions, ~2 minutes. Run on demand.

Bare bun test (no path) discovers both suites — that’s test:all’s intentional job, not an accident. The default bun run test script is correctly scoped to test/unit only.

What the unit suite actually guards against

Every hand-rolled Soroban XDR encoder in src/scval-encoders.ts was wrong on at least one real attempt during development — each bug produced a silent on-chain wasm trap, not a TypeScript error, because the SDK happily accepts a structurally-valid-but-semantically-wrong ScVal tree. The unit tests decode the actual produced structure and assert its exact shape:

test/unit/scval-encoders.test.ts

test("encodes a data-less enum variant as [Symbol(name)], not a bare Symbol", () => {
  // Regression test for the exact bug hit during development: SignerStorage
  // ::Persistent (no associated data) still encodes as a 1-element Vec --
  // never a bare ScVal::Symbol, which the host silently rejects.
  const v = asVec(unitVariant("Persistent"));
  expect(v.length).toBe(1);
  expect(v[0].sym().toString()).toBe("Persistent");
});

Other unit tests cover the host’s canonical Map key ordering (Symbol("Ed25519") sorts before Symbol("Policy"), lexicographically — get this wrong and the signatures map is silently malformed), the MCP tool schema generator’s type mapping, and the address auto-fill heuristic.

What the e2e suite proves live

policy-gate.e2e.test.ts
mcp-protocol.e2e.test.ts

Deploys one fresh environment, then drives the real allow/reject sequence directly through invokeAsWallet:

An allowed, uncapped deposit succeeds
An allowed withdrawal within the spend cap succeeds
A withdrawal exceeding the cumulative cap is rejected on-chain (Auth, InvalidAction)
A call to a method off the allow-list is rejected on-chain
The wallet owner (unrestricted) can still call the same disallowed method — proving the restriction is agent-signer-specific, not contract-wide

Deploys its own independent fresh environment, then spawns the compiled dist/cli.js binary as a real subprocess and drives it through a genuine @modelcontextprotocol/sdk client:

Tool listing matches exactly what the on-chain allow-list permits
wallet_info reports the correct wallet and policy addresses
A deposit call with no address argument succeeds, address auto-filled
A withdrawal beyond the cap surfaces as isError: true, not a crash

Every e2e test generates and funds its own fresh testnet keys — none of them read .env, and none of them depend on the state of any previous run. Two runs of the same test file never interfere with each other.

Running everything

cargo test --workspace   # 17 Rust contract tests
bun run typecheck        # src/ + scripts/ + test/
bun run test             # 40 unit tests
bun run build            # compiled dist/cli.js, required before e2e's MCP test
bun run test:e2e         # 9 end-to-end tests against live testnet

Get Started

Core Concepts

Guides

Two suites, deliberately separated

Unit -- bun test test/unit

E2e -- bun test test/e2e

What the unit suite actually guards against

What the e2e suite proves live

Running everything

​Two suites, deliberately separated

Unit -- bun test test/unit

E2e -- bun test test/e2e

​What the unit suite actually guards against

​What the e2e suite proves live

​Running everything

Two suites, deliberately separated

What the unit suite actually guards against

What the e2e suite proves live

Running everything