Test Catalog

The inventory of what is tested, per system. This complements Testing (which is the harness/how-to) and the Seed Catalog (the fixtures these tests run against). For the Grasshopper-specific view see also Grasshopper API.

Big picture

Go — unit & repository tests

The three-branch repo harness

Every database/repo function is expected to ship happy-path + error branch + cache path, realized by three reusable doubles:

The *_coverage_test.go files (~45 of the 150) are the dedicated branch-completion companions. Shared vocabulary lives in test/testhelpers — TestMainSetup, SkipIfShort, RequirePostgres (which resets all Postgres sequences once per run via a DO $$ block, db.go:81), assertions.go, factory.go. No golden files anywhere — email/template tests assert via strings.Contains needles.

Repo coverage by domain (150 files)

Pure & service unit suites

• utils (15, best-covered pure pkg, -race + coverage in CI) — money precision (money_test.go:140 — the 0.1+0.2 classic, accumulated rounding, %-of-%), discount/charges (discount_calc_test.go with property-based TestMergeRangesProperties + native fuzz FuzzMergeRanges/FuzzFindBestDiscount), encryption (AES round-trip, per-encryption nonce uniqueness, thread-safety :266), JWT + G2A JWT (token uniqueness, cross-use rejection, tamper/expiry), PIN randomness, webhook-secret generation (200 iters, whsec_ prefix, len 70, zero duplicates).
• services (7, NOT in CI) — inventory_test.go proves FEFO (reserved earlier-expiry pool drained before general, :329) + multi-vendor split; webhook_sender_test.go verifies X-Signature == HMAC-SHA256(body, token) and that the token isn't leaked in a header; *_email Jet renders.
• email (3, NOT in CI) — voucher/recharge/esim Jet templates, HTML + text variants, substring assertions.
• database/models (10, pure) — enum Scan/Value/IsValid round-trips (only 10 tests for 87 model files — thin).
• cache (4, Valkey), middleware (1 — only g2a_auth), jobs (1 — only prefetch phase-6 backoff), http/handler (9), services/shopify (2).

Go — integration, orchestration & E2E (test/)

The orchestration harness (two faking tracks)

DB-backed E2E driving real orders through the Fiber app + order service + retry cron + webhook handler + wallet ledger against real Postgres, with the vendor faked two ways:

• Track A — mocky-balboa (Cloudflare Worker mock) for real third parties (Runa, Neo, Wupex, iRewardify, SEAGM, DTOne). Chaos via the /_chaos API driven by testhelpers/mockychaos (modes one_shot/count/probabilistic/always; failures status/delay_then_fail/malformed/drop; MustHaveFired catches tests that silently hit the happy path).
• Track B — octopusfake (in-process httptest) for the federated self-vendors (OCTO_TOPUP/OCTO_ESIM): programmable auth + chaos engine + opt-in order engines (create→poll→deliver lifecycle) + HMAC-SHA256 webhook signing so inbound verification is exercised.

All orchestration files carry //go:build orchestration; testhelpers/vendor_binding rebinds a vendor row to the mock (per-vendor mutex), cronrunner steps a single order's retry without waiting on gocron, and test/shared/concurrency.go RunConcurrentN fires N goroutines released simultaneously for real race pressure.

Orchestration suites (~226 subtests)

Every suite has explicit concurrency/money-conservation subtests (ConcurrentSameRef, TwoCronTicks_RefundOnce, no_double_mint). No orchestration suite for TRS, EPIN, or GH voucher — GH is exercised only indirectly as the mint stub inside the G2A suite.

The rest of test/

• test/clientapi non-orchestration (~40 files, in CI) — the bulk integration layer: core API (auth/orders/charges 1779 L/wallets/transactions/payouts/catalog), money-leak/conservation per product type (voucher/topup/esim_money_leak — no-footprint-on-invalid, exactly-one-debit, ledger-sum==balance-delta, 100-order audit), dedup (+ fuzz), validation (+ native Go fuzz targets with a seed corpus).
• test/clientportal — password_reset_test.go (9 e2e: no account-existence leak, single-use token) + a placeholder.
• test/admin — scaffolding + placeholder only; no real admin handler tests.
• test/flows — product data-integrity, inventory-allocation flow (inventory_allocation_final_test.go 800 L).
• test/frontend/pages — Jet status pages.
• test/load/g2a/g2a_load.js — a k6 script; MODE=journey mints real codes + debits the wallet (staging only, no CI guard).

Grasshopper — vitest (25 files, ~330 cases)

Runs inside the real workerd runtime via @cloudflare/vitest-pool-workers with real D1/KV/RateLimit bindings from wrangler.jsonc; singleWorker + isolatedStorage for determinism, migrations applied per-suite via TEST_MIGRATIONS, injected dummy secrets (always-pass Turnstile, 32-byte ENCRYPTION_KEY, RATE_LIMIT_FAIL_OPEN='').

What CI actually runs

.github/workflows/test-backend-api.yml: lint → build → parallel {cache, utils, models, database, clientapi, vendor-contract, orchestration}, all with -race -count=1 -covermode=atomic, Postgres 16 + Valkey 7.2. The orchestration/contract jobs hit deployed mocky, whose chaos rules are global — concurrent CI runs can interfere (a documented flakiness source). Grasshopper's only workflows are deploy-grasshopper{,-sandbox}.yml, which deploy without running vitest.

Notable security-relevant assertions

• Constant-time compares — admin token (prefix rejected), PIN (generic "invalid code or PIN", no which-was-wrong leak), nonce/poll-token (unit + fuzz).
• Fail-closed / fail-open — nonce fail-closed when secret unset; rate-limit {success:false} never forgiven, throw forgiven only when explicitly enabled.
• Anti-replay — nonce bound to code hash (unit + fuzz + endpoint); voucher single-winner claim; TwoCronTicks_RefundOnce money conservation.
• Idempotency — client_reference recreate only on definitive notFound; sync upsert; webhook idempotent + bad-signature/bad-path-token rejected (octopusfake HMAC).
• Crypto — encryption round-trip + thread-safety (Go) + fresh-IV + wrong-secret-throws (both sides); webhook-secret zero-duplicates over 200 iters.

Coverage gaps (consolidated)

Key files

• Repo harness: database/repo/{main_test,fault_injection_internal_test,sqlmock_cache_hits_internal_test}.go, test/testhelpers/*
• Orchestration: test/clientapi/*_orchestration_test.go, test/octopusfake/, test/testhelpers/{vendor_binding,cronrunner,mockychaos}, test/shared/concurrency.go, test/testenv/
• Grasshopper: frontend/grasshopper/test/**, vitest.config.ts
• CI: .github/workflows/test-backend-api.yml