The Integration Suite

The stack-backed @numero/test suite is the platform's end-to-end gate: real services in docker, a real chain, real WebSockets, real money-path journeys. It runs three ways — locally on demand, nightly in CI, and as the pnpm release --full pre-promotion gate. All three run the SAME suite with the SAME commands; there is no CI-only variant to drift.

The one command

pnpm test:up            # boot this worktree's hermetic test stack (auto port range)
pnpm test:integration   # run the suite against it
pnpm test:down          # tear down promptly (stack cap is 5 per machine)

The stack is per-worktree (<worktree>-test) on an auto-allocated port range — never hand-pick a prefix, never share another worktree's stack (see the test-stack skill). The suite discovers the running stack's ports from its postgres container.

Profiles

• EVM (default) — hardhat chain + evm-bank. What pnpm test:up boots.
• Solana — pnpm test:up:solana adds the Solana cage (requires the host validator, see testing-solana). The claim-board credit-path rows and other SKIP-REASON(solana-grant-leg) tests only run here.
• solana-cage e2e (test/e2e/solana-cage/) — self-contained: each file spins its own solana-test-validator + cage process. Requires the anchor build artifacts (onchain/target/deploy/*.so): run anchor build --no-idl and bash scripts/build-real-custody.sh in onchain/ once per checkout. The validator binary resolves via SOLANA_TEST_VALIDATOR_BIN → the documented Agave install dir → PATH — the verdict never depends on shell PATH shape.

Skips are typed

Every disabled test carries a greppable // SKIP-REASON(<token>): … line — check:skip-reasons (chained into pnpm typecheck) fails the build on any bare skip. The audit covers the aliases too (xit/xdescribe/xtest and chained modifiers like describe.concurrent.skip count as skips), and it is fail-closed against its own rot: a scanner run that finds zero disabled sites fails rather than passing by seeing nothing. Grep a token to see a whole class:

Token	Meaning
cage-only	tests the table-level chain seam; scheduled for deletion by crypto-at-the-cage
solana-grant-leg	needs the TEST_CHAIN=solana grant-capable cage
persistence-dsl / unbuilt-harness / chaos-dsl / arena-dsl	scaffolded against harness helpers that were never built
retired-premise	the product model the test assumed no longer exists
filed-seam / filed-lobby-ghost	filed product bug; the skip names the unlock
sng-scaffold / observability-scaffold / copilot-later-phase / durable-table-state	plan scaffolds left disabled; adjudication candidates
perf-gate / beta-chip-token	opt-in profiles (PERF_GATE / CHIP_TOKEN=playskpk)
stale-unlock	the named unlock has since shipped — enable or delete

The nightly

.github/workflows/integration-suite.yml runs the suite nightly against staging HEAD (09:17 UTC) and on demand via workflow_dispatch with any ref. It boots the trimmed suite roster (no frontends, no portainer — they serve zero suite traffic), uploads suite.log + failure diagnostics as an artifact, and emits ONE ci.integration_suite.completed span (OK/ERROR, duration, failed counts, sha). Dash0 rule 13 alerts Slack on ERROR. A red nightly is triaged with the integration-suite-red runbook.

Reading a failure

1. The failure SET is the unit, not the count. Compare which files failed against the previous run; a new red is a regression even if the total fell.
2. Every failed test auto-dumps diagnostics to test/.failure-diagnostics/<timestamp>__<test>/ — DB state, service logs, WS message logs. Start there, not at the assertion message.
3. Order-interaction suspects: run the file solo, then in the failing neighborhood. Green-solo/red-in-order means shared state (env keys, game settings toggles, leftover seats) — fix the leak, don't widen timeouts.
4. "4 skipped" in a file with a beforeAll is vitest's rendering of a FAILED beforeAll — read the Failed Suites section, not just the row counts.