Test Infrastructure

Testing spans five layers: co-located unit tests, real-Postgres repository tests, the test/clientapi/ client-API + orchestration suites, load tests, and fuzz targets. Two purpose-built harnesses carry the heavy work — octopusfake (in-process Octopus upstream) and mocky-balboa (a Cloudflare-worker mock vendor with a chaos API).

Layers & how to run

Race detector (-race) is used throughout CI. testhelpers.SkipIfShort(t) (test/testhelpers/db.go:53) lets long-running/DB tests be skipped with -short.

Repository test patterns

Two complementary styles:

• Real-Postgres integration — the bulk of database/repo/*_test.go. CI spins up a postgres service, runs migrations + seeders, then go test ./database/repo/.... Isolation is per-test (transaction/cleanup helpers in test/testhelpers/db.go).
• Fault injection (database/repo/fault_injection_internal_test.go) — a faultDB wraps a real DatabaseClient and forwards everything until a fail-flag is flipped, then returns a configured error. This unlocks the error branches integration tests can't reach (connection failures, scan errors, malformed JSON). newFaultRepo builds a Repository around it. Combined with cache-fault helpers, this is how the repo layer hits the "every function needs happy + error + cache-path tests" bar.

testhelpers

test/testhelpers/ — shared infrastructure imported by the suites:

test/shared/ adds concurrency.go (RunConcurrentN — fires N goroutines released simultaneously for race/idempotency tests, CountSuccess), isolation.go, suites.go, config_groups.go, fuzz.go, auth.go.

octopusfake — in-process Octopus upstream

test/octopusfake/octopusfake.go is a programmable net/http/httptest fake of the Octopus public /api/v1 used to test the federated Octopus vendor adapters (OCTO / OCTO_TOPUP / OCTO_ESIM) deterministically — including chaos, concurrency, fuzz and load that can't run against the live sandbox. It is not mocky-balboa: no separate service, just a server you start and program from a Go test.

• Core: auth (/auth/login, /auth/refresh), /api/v1/wallets, a chaos-rule engine (Arm(Rule) — first armed rule matching method + path-contains applies; malformed-body kinds, consumption modes), a request recorder, and HMAC webhook signing.
• Order engines (opt-in): EnableTopupOrderEngine() / EnableEsimOrderEngine() give fake orders a real create → status-poll → deliver lifecycle; SetTopupBehavior(createStatus, pollStatus, failureCode) models async PENDING→DELIVERED and failure paths. The eSIM engine renders activation_code/iccid deliverables.
• SetHandler(method, path, h) overrides any exact route for bespoke scenarios.
• Drives the goleak soak tests in services/external_vendors/{direct_topup,esim}/octopus/*_soak_test.go (the OCTO family uses octopusfake instead of a mocky route — see Octopus adapters).

Vendor orchestration harness

test/clientapi/<vendor>_orchestration_test.go (build tag orchestration) drives real orders end-to-end through a vendor pointed at mocky-balboa, exercising chaos, malformed responses, async polling, signed webhooks, idempotency, retry caps, the link path, validation, and vendor logging. Runa is the ~28-subtest reference.

Ten suites exist today:

runa · wupex · neo · irewardify        (voucher)
seagm_topup · dtone_topup              (top-up)
dtone_esim · octopus_esim · octopus_topup   (esim / octo)
g2a                                    (inbound channel)

Adding a new vendor suite (checklist)

1. Add a per-vendor sub-app + routes to mocky-balboa (frontend/mocky-balboa/src/index.ts) that mimic the real vendor's contract.
2. Seed chaos rules for that route (4xx/5xx/timeout/malformed/drop) in mocky's chaos_rules.
3. In the test, BindVendorToMocky("CODE", "mocky-path") (from testhelpers) to point the vendor's host at mocky and restore on cleanup.
4. Use mockychaos.NewForTest(t) to reset to a clean baseline, then Arm specific rules per subtest.
5. Drive orders through the real client API; step retries with cronrunner one-shot helpers instead of sleeping.
6. Assert idempotency with shared.RunConcurrentN (N concurrent same-client_reference requests → exactly one durable effect).
7. Gate the file with //go:build orchestration and mirror the Runa suite's structure (chaos, malformed, async, webhook, idempotency, retry-cap, validation, logging).

See the vendor chaos + tests rule — every new adapter ships with a mocky route (incl. chaos hooks) plus unit + contract + service tests in the same PR.

mocky-balboa

frontend/mocky-balboa/ — a Cloudflare Worker (Hono + D1) mock vendor server with a /_chaos management API. Adapters are pointed at it by overwriting their host vendor-attribute (via BindVendorToMocky); tests arm failure scenarios through the mockychaos client. Base URL resolves from $MOCKY_BASE_URL (default http://localhost:8788; CI sets https://mocky-balboa.octopuscards.io). Deploys via GitHub Actions (deploy-mocky-balboa.yml) — see Cloudflare. Uses bun, not npm.

CI

.github/workflows/test-backend-api.yml — parallel jobs:

Frontend/worker deploys are separate workflows (grasshopper, mocky-balboa, docs, website — see Deploy & Release). The orchestration-tagged suites are not obviously wired into this CI file (they need mocky-balboa reachable) — verify whether they run in CI or only locally/against the deployed mock.

Findings

Key files

• Harnesses: test/octopusfake/octopusfake.go, frontend/mocky-balboa/src/
• Helpers: test/testhelpers/{db,factory,mocky,vendor_binding}.go, test/testhelpers/mockychaos/client.go, test/testhelpers/cronrunner/runner.go
• Shared: test/shared/{concurrency,isolation,suites}.go
• Fault injection: database/repo/fault_injection_internal_test.go
• Reference suite: test/clientapi/runa_orchestration_test.go
• CI: .github/workflows/test-backend-api.yml; hook .githooks/pre-push