# Integrity Protocol — Testing Strategy

> How every package in this monorepo is tested, and how the layers fit
> together. See `.agents/AGENTS.md` §6 for the loop this feeds into
> (continuous test-coverage discipline, including when to fan work out to
> parallel background agents) and `docs/INTERFACE_CONTRACT.md` for the
> schemas/ports each layer talks to.

## The test pyramid

```
                    ┌─────────────────────────────┐
                    │   Playwright E2E (browser)   │  integrity-dashboard/e2e/
                    │   real backends, real chain  │  make test-e2e
                    └─────────────────────────────┘
              ┌───────────────────────────────────────┐
              │      Component tests (vitest+msw)      │  integrity-dashboard/src/**/*.test.tsx
              │   real components, HTTP boundary mocked │  npm test
              └───────────────────────────────────────┘
   ┌──────────────────────────────────────────────────────────┐
   │  Per-package unit/integration tests (forge/cargo/pytest)  │  make test
   │        real toolchains — several already infra-backed     │
   └──────────────────────────────────────────────────────────┘
```

**Ground rule that applies at every layer**: no silent mocks. A test either
exercises real code against a real dependency (real anvil, real Postgres,
real OPA server, real `bb prove`/`verify`), or it mocks exactly one seam
deliberately (e.g. `msw` at the HTTP boundary in component tests) and says
so. Nothing pretends a stubbed dependency is the real thing.

## Layer 1 — per-package unit/integration tests

Run via `make test` from the repo root, or per-package directly. Every
suite is real, not smoke-tested against fixtures:

| Package | Runner | What's real |
|---|---|---|
| `contracts/` | `forge test` | Real EVM (Foundry's local VM), 165 tests |
| `integrity-zkp/` | `nargo test` | Real Noir circuit compilation |
| `integrity-oracle/` | `cargo test` | 37 lib tests (29 backend + 8 scoring-core) + a real e2e test (anvil + Deploy.s.sol + SDK registration + Postgres + Redis + HTTP, opt-in via `ORACLE_E2E=1`) |
| `integrity-sdk/` | `uv run pytest` | Chain-touching tests run against a real anvil (`tests/conftest.py`'s `deployed_chain` fixture: real `anvil` subprocess + real `Deploy.s.sol`/`DeployMarkets.s.sol`), 97 tests, +1 opt-in (`ORACLE_E2E=1`) = 98 |
| `integrity-cli/` | `uv run pytest` | Includes 1 real on-chain chain test, 49 total |
| `bcc_middleware/` | `uv run pytest` + `opa test .` | Real OPA server calls, real per-agent chain resolution, 49 + 12 |
| `integrity-userapi/` | `uv run pytest` | Real Postgres container (not sqlite/mocked), 33 tests |
| `integrity-dashboard/` | `npm test` (vitest) | Real React components, HTTP boundary mocked via `msw` — the ONE deliberate mock in this whole pyramid, and it's scoped to exactly the network seam, not business logic |

This layer runs on every change. Fast (seconds to low minutes per package),
no full-stack boot required.

## Layer 2 — Playwright E2E (`integrity-dashboard/e2e/`)

The layer above component tests: a real Chromium browser driving the real
`integrity-dashboard` app, which talks to a real running backend stack — not
`msw`, not any mock. This is what proves the pieces work *together*
through the actual UI, which no per-package suite (each testing its own
package in isolation) or component test (mocking the network boundary)
can prove on its own.

**What `e2e/global-setup.ts` stands up, for real, before any spec runs:**
1. A dedicated local `anvil` chain (fixed port, see `e2e/constants.ts` —
   deliberately NOT dynamically chosen; Playwright's `webServer` needs
   `VITE_ORACLE_URL` at boot time, before `globalSetup` would otherwise
   have picked a port).
2. The real genesis deploy (`Deploy.s.sol`) + market layer
   (`DeployMarkets.s.sol`) against that chain.
3. An ephemeral, dedicated Postgres + Redis (Docker containers, separate
   from any dev-time `docker-compose` services — an E2E run shouldn't
   write test rows into a database a developer is also using).
4. The real `integrity-oracle` backend (`cargo run`), pointed at the fresh
   chain + fresh DB.
5. One real seed agent, registered through the real
   `integrity_sdk.registration.register_agent` flow — on-chain AND in the
   oracle's own DB (not `skip_oracle_registration`) — so specs assert
   against real, oracle-served data.

`e2e/global-teardown.ts` tears all of it back down after the run.

**Local network only — never live Base Sepolia.** Base Sepolia stays the
live investor/developer demo target (`integrity-dashboard/demo/`, `make demo`);
spinning up a fresh chain per E2E run would be slow, cost real (if tiny)
gas, and be non-deterministic across runs. Mirrors the convention
`integrity-sdk`'s and `integrity-oracle`'s own test suites already use.

**Run it**: `make test-e2e` from the repo root, or `cd integrity-dashboard && npx
playwright test`. Requires `anvil`/`forge` on `PATH`, `cargo`, Docker, and
the `integrity-sdk` `uv` venv already synced (`cd integrity-sdk && uv
sync`) — same toolchain the rest of this repo already assumes, nothing
E2E-specific to install beyond `npx playwright install chromium` once.

**Convention for new specs**: as `integrity-dashboard`'s dashboard pages get
built out (task #21 — Markets, Leaderboard, Wallet, Capital Allocation,
Cognition, Identity, Health, Landing), each new page's Playwright spec
ships in the *same pass* as the page, not as a follow-up. Cover real
negative paths too, not just happy paths (a low-AIS agent's market-entry
control is genuinely disabled by a real on-chain check, an unauthenticated
user is genuinely redirected, a resolved market's payout genuinely reflects
an on-chain balance change) — a spec that only exercises the happy path
proves less than it looks like it does.

**Known simplification**: `bcc_middleware` is not yet part of
`global-setup.ts`'s stack (not needed by the current specs). Any spec that
exercises BCC-commitment history or BAA status should add it to setup
first, not silently pass against a `bcc_middleware`-shaped 404/connection
error the way `agent-detail.spec.ts` currently, honestly, does.

## What's explicitly NOT here yet: hosted CI

This repo is not a git repository today (no remote), so there is nothing
for GitHub Actions (or any hosted CI) to trigger from. `make test` and
`make test-e2e`, run by a human (or an agent) before considering a change
done, are the enforcement mechanism until that changes — see
`.agents/AGENTS.md` §6. This is a real, current gap, not a silently-skipped
one; revisit once/if this repo gets a git remote.