> For the complete documentation index, see [llms.txt](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/testing.md).

# Testing

```bash
bun run test        # vitest run
bun run lint        # eslint .
bun run build       # production build
```

Config: `vitest.config.ts` (TypeScript path aliases mirrored from `tsconfig.json`). Tests live in `src/lib/__tests__`.

## Suite

| File                    | Covers                                                                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `chain.test.ts`         | Chain `4663` params, `wallet_addEthereumChain` config, WETH/USDG checksums, explorer URL builders                                  |
| `money.test.ts`         | Base-unit conversions, decimals bounds, multiplier-adjusted reference, spread bps, buy/sell execution cost, formatters             |
| `assets.test.ts`        | Canonical filtering to chain `4663`, snake\_case normalization, active/inactive partition, defaults for missing metadata           |
| `eligibility.test.ts`   | Client acknowledgement validation, server region gating, `RESTRICTED_REGIONS` override, fail-closed on missing claim               |
| `reality-score.test.ts` | Each component weight, missing-route floor, halted handling, freshness decay, banding boundaries                                   |
| `swap-exec.test.ts`     | `needsApproval` (including `undefined` allowance), exact-amount `approveArgs`, no-unlimited invariant                              |
| `zerox.test.ts`         | `swapRequestSchema` (chain, allowlist, amount, slippage), error sanitization, per-IP rate limiting                                 |
| `ai-schema.test.ts`     | Reality Check schema validation, shape coercion for model drift, fenced-JSON extraction, malformed output, 429 / 402 / 5xx mapping |
| `reality-check.test.ts` | Prompt construction, snapshot cache key stability, identity-free snapshots                                                         |
| `portfolio.test.ts`     | Valuation, position weights, HHI and effective positions, fractional-balance precision, halted/unpriced exclusion                  |

**99 tests across 10 files.** Typecheck and lint clean.

## What the tests are actually protecting

These are the assertions that catch a wrong number rather than a crash:

* An allowlist bypass in `swapRequestSchema` turns the quote endpoint into an open, key-funded proxy.
* A float creeping into `toBaseUnits` silently misprices a trade.
* A missing-route case scoring mid-range makes an unexecutable trade look fine.
* An eligibility check that fails open removes the entire compliance gate.
* A drifted AI response rendering as a verdict instead of failing closed.
* A concentration metric computed over unpriced holdings understates real risk.
* A sanitizer regression leaks `ZEROX_API_KEY` into a client-visible error string. `zerox.test.ts` asserts the key never appears in sanitized output.

## Release checklist

```bash
bun run test
bun run lint
bun run build
grep -rl "ZEROX_API_KEY\|ROBINHOOD_RPC_URL" dist/client || echo "clean"
```

Then run a security scan. An exit code of `0` with `Error` text in the output is a failed check — read output in full.

## Adding tests

Pure logic goes in `src/lib`, tested directly — no component render needed. Anything touching `process.env` should set and restore it inside the test so ordering cannot leak state between files.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/operations/testing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.