Testing¶
Tomoda's test strategy has six layers, each with a clear cost / coverage tradeoff:
| Layer | Where | Runs against | Invocation |
|---|---|---|---|
| Unit | backend/internal/**/*_test.go, frontend/__tests__/ |
In-process mocks (testify/mock) + miniredis for Redis-backed code |
task test:unit / npm test |
| In-process integration | backend/tests/integration/, frontend/__tests__/integration/ |
miniredis (backend) / mocked fetch + WebSocket (frontend). No docker required. |
go test ./tests/integration/... / npm test |
| Endpoint (real routes) | backend/tests/integration/endpoint_harness_test.go (tests named *Integration*) |
Full Wire graph + real route table (wiring.SetupRouter) over the dev Postgres (one database per test process, one schema per test); miniredis; external providers faked with httptest servers via config URLs (Google.PlacesDetailsURL, Resolution.SerperSearchURL, Photon.URL, Semantic.BaseURL) |
task test:integration (skips when Postgres is down) |
| Real-stack integration | backend/**/*_test.go (Go tests with Integration in name) |
Real Postgres + Redis + RustFS from docker-compose.dev.yml |
task test:integration |
| Smoke | backend/cmd/server/main_test.go, backend/tests/smoke/, e2e/tests/{smoke,pages,auth}.spec.ts |
Wire DI graph assembly + a minimal health-only chi router (backend); mocked-API Playwright (frontend) | go test ./cmd/server/... ./tests/smoke/... / ./scripts/dev/run_e2e.sh |
| Simulation | backend/cmd/test/sim-workers/ |
Real DB + Redis, simulated user fleet | task test:simulation |
Where a test lives (canonical layout)¶
The kind of test decides its home. This is enforced, not a suggestion:
- Unit — co-located
foo_test.gobesidefoo.gounderinternal/**. No real infra; must pass under-short. May reach unexported symbols (same package) or use thefoo_testexternal package. - Integration — under
backend/tests/integration/<service>/, packageintegration(or<service>_integration), written against the service's exported API only (no unexported access). Anything that needs a real Postgres (testutil.NewPostgres), miniredis, or RustFS is an integration test and belongs here, not co-located ininternal/**. Test functions carryIntegrationin the name sotask test:integrationselects them. - Smoke —
backend/tests/smoke/(packagesmoke): Wire DI graph + startup wiring. - Shared helpers — reusable fixtures/builders live in
backend/tests/testsupport/(an importable package); the DB harness (per-process database, per-test schema) stays ininternal/testutil. Don't duplicate helpers per package.
testutil.NewPostgres creates one database per test process (tomoda_it_<ts>_<pid>_<rand>, with the PostGIS/PGroonga/pgvector extensions) and a throwaway schema per test inside it. PGroonga keeps a single Groonga DB per Postgres database, so parallel test processes must not share one. Leaked databases are swept by later runs once they are an hour old. Creating and dropping a schema holds about 1,300 locks, and the server shares one lock table (max_locks_per_transaction times max_connections) across every session, so at most two test processes provision or drop at once (advisory-lock slots on the base database). Without that, a wide go test ./... can exhaust the table and fail other sessions on the same server, such as a long seed load, with "out of shared memory".
task test:unit runs the co-located unit tests (-short); task test:integration runs backend/tests/integration/... against the dev Postgres (PostGIS + PGroonga); task test:smoke runs backend/tests/smoke/.... All three run in CI (the integration job gets PostGIS + PGroonga + pgvector from its runner's Postgres sidecar).
Unit tests¶
Backend¶
task test:unit # go test -v -short ./...
Unit tests live next to the code they test (foo.go ↔ foo_test.go). The
-short flag skips anything that needs a live database.
Test doubles: the project uses testify/mock — hand-rolled
Mock<Iface> structs with mock.Mock embedded. Repository interfaces
have these doubles in the same package (see e.g.
backend/internal/services/mock_*_test.go). There is no gomock /
mockgen step; if you need a new mock for an interface that doesn't
have one, add it by hand following the existing pattern.
Redis-backed code uses miniredis
(github.com/alicebob/miniredis/v2) instead of mocking the redis.Client
interface — that catches real pub/sub, SETNX, ZRANGEBYSCORE, and TTL
semantics that mocks miss. Pattern:
mr := miniredis.RunT(t) // auto-closes on test end
rdb := redis.NewClient(&redis.Options{Addr: mr.Addr()})
// pass rdb where the production code expects redis.UniversalClient / Cmdable
miniredis.RunT(t) gives a fresh server per test — no shared state.
Note that miniredis uses a fake clock for TTLs; call mr.FastForward(d)
to advance it when testing expiry behavior.
Frontend¶
cd frontend
npm test
Frontend unit tests are at frontend/__tests__/ and use Jest +
@testing-library/react-native. Coverage includes hooks
(useSearch, useLocalizedName), contexts (AuthContext,
FriendsContext), service clients (chatService, eventService,
friendService, discoveryService), pure utilities (date, location,
password validator), and a handful of UI primitives. Mock the network
boundary via jest.mock of the service module, or stub global.fetch
/ global.WebSocket for service-level tests.
In-process integration tests¶
cd backend && go test ./tests/integration/...
cd frontend && npm test # picks up __tests__/integration/ automatically
These wire multiple components together but don't require docker.
- Backend (
backend/tests/integration/, packageintegration): miniredis-backed flows that exercise contracts across packages. Examples: twowebsocket.Hubinstances exchanging messages viachat:event:*pub/sub with origin-dedup; threescheduler.Schedulerinstances electing a single leader and failing over;Workerqueue ownership;ChatServicecache hit/miss + trim; auth refresh-token full lifecycle. - Frontend (
frontend/__tests__/integration/):AuthContext+ login flow with a mockedfetch;chatServiceWS lifecycle (connect → message → reconnect → max-attempts → heartbeat); chat screen render-and-send with a mocked WebSocket.
These run on every go test ./... / npm test and are the best
catch-net for breakage from refactors that unit tests miss but a full
stack-up integration test would be too slow to debug.
Real-stack integration tests¶
task test:integration # go test -v -run Integration ./...
These spin up against the already-running local Docker stack —
Postgres, Redis, RustFS. Make sure task dev (or at least
docker-compose -f docker-compose.dev.yml up -d) is running first,
otherwise the connection setup in the test will fail.
Use this layer for things miniredis can't fake — real SQL behavior, JSONB serialization, PostGIS spatial queries, pgx type handling, AWS SDK round-trips against RustFS.
Smoke tests¶
Backend¶
go test ./cmd/server/... ./tests/smoke/...
Fast checks that the binary's startup wiring is sound:
backend/cmd/server/main_test.go— table-driven test of the--moderesolver (full/multi-hub/async/api-hub/ws-hub) and a Wire DI smoke that calls the realInitializeAppagainst miniredis + sqlite to assert every top-level component is non-nil.backend/tests/smoke/— runtime-shape checks:Hub.Runstarts without panic (with + without Redis),/healthresponds, the mode matrix is coherent (api-hub ∪ ws-hub == multi-hub).
These don't exercise behavior — they catch infrastructure regressions (broken DI graph, missing health endpoint, mode misconfiguration).
Frontend (Playwright)¶
E2E tests live at e2e/ in the repo root (config:
e2e/playwright.config.ts). The Playwright suite is treated as smoke
— shallow, fast, broad — not deep flow verification:
e2e/tests/smoke.spec.ts— backend/health+ frontend/reach.e2e/tests/pages.spec.ts— each top-level route loads without console errors, with the backend API stubbed viapage.route('**/api/v1/**', ...).e2e/tests/auth.spec.ts— auth gate redirects unauthed users, login form renders the right fields, login submit posts and redirects out of/auth/login.
The driver script scripts/dev/run_e2e.sh orchestrates the full stack:
- Detects Docker or Podman + a compose tool.
npm install+npx playwright install chromiumine2e/.- Brings up the full application stack with
docker compose up -d --build(usesdocker-compose.yml, the production-style compose file with backend + frontend containers built locally). - Polls
http://localhost:8080/healthuntil the backend is healthy (max ~60s). - Polls
http://localhost:8081until the frontend returns200 OK. - Runs
npx playwright test. - Optionally tears the stack down.
./scripts/dev/run_e2e.sh
The report ends up at e2e/playwright-report/index.html. On CI,
playwright.config.ts enables 2 retries and forces workers: 1 for
deterministic runs.
Trace on first retry
trace: 'on-first-retry' means Playwright records a trace the second
time a test runs after failing. View it with
npx playwright show-trace path/to/trace.zip — far more useful than
raw logs.
Simulation tests¶
Simulation tests stress the system from the user side — simulated workers that move around, send messages, create events, and trigger discovery / presence updates. They're how we shake out load-related bugs that don't show up under single-user testing.
task test:simulation
What it does:
- Runs
backend/cmd/test/data— drops the schema, recreates the extensions, migrates, then re-seeds fresh test data (~20+ users, events, chats) and clears Redis keys. - Runs
task db:seed:catalog— pulls the published location seed set from GCS (minus the heavy global files) and loads it into the fresh DB, so sim workers have real places to reference. Needsgcloudlogin. - Runs
backend/cmd/test/sim-workers— spins up the worker pool that simulates user behavior.Ctrl+Cto stop.
The infra (Postgres, Redis, RustFS) must already be up via task dev
or task docker:up. The script doesn't bring up its own dependencies.
Backstage test data¶
task db:test:setup and task test:simulation finish by seeding Backstage (SeedBackstage in backend/cmd/test/lib/backstage.go), so every screen has something to open. The seeder refuses to run outside a local or test environment, and Tomoda accounts are never created in dev or prod this way.
Five Tomoda accounts, all with password password. Each is linked to a member account, so the normal path works: sign in to the app as the member, step up with the Tomoda account's password, then switch into Backstage. Signing in to a Tomoda account directly also needs the emailed code.
| Tomoda account | Role | Linked member |
|---|---|---|
adminuser1@tomoda.life |
admin |
testuser1@tomoda.life |
adminuser2@tomoda.life |
support |
testuser2@tomoda.life |
adminuser3@tomoda.life |
moderator |
testuser3@tomoda.life |
adminuser4@tomoda.life |
auditor |
testuser4@tomoda.life |
adminuser5@tomoda.life |
developer |
testuser5@tomoda.life |
A sixth, adminuser6@tomoda.life (support), is left unlinked to try linking from Backstage: sign in to it directly (password plus the emailed code), open Today, choose "Link your personal account", confirm with its password, then sign in to testuser6@tomoda.life with password password. Afterwards Today shows "Switch to personal account", and signing in as testuser6 shows the Backstage row in the Hub.
| Screen | Seeded |
|---|---|
| Reports | Twelve member groups: open (grouped, single, urgent), actioned and dismissed, across user, moment, event and chat message targets (real seeded content where it exists) |
| Cover review | Six photo submissions (pending, approved, rejected) and two cover report groups, one on a place that also has a pending photo |
| Support cases | Six cases: open, pending (assigned, with a reply and an internal note) and solved; two problem reports with diagnostics, one with a screenshot |
| Announcements | Live (info and warning), scheduled, ended and withdrawn |
| Feature switches | problem_report.shake switched off with a reason |
| Audit | Reads, decisions, role changes and switches by all five accounts over the last few days |
| Insights | Thirty days of daily totals and ten members' engagement for the last fourteen days |
Crashes read the crash-reporting provider and show "not connected" locally. Assist suggestions are not seeded. Every seeded row has a stable id and is written with ON CONFLICT DO NOTHING (announcement windows move with the run, and the seeded members are backdated so they predate them), so calling SeedBackstage again adds nothing; the integration test in backend/tests/integration/backstageseed/ runs it twice and compares the counts.
Coverage¶
task test:coverage
Runs the full backend suite with -coverprofile=coverage.out, then
renders an HTML report at backend/coverage.html and opens it in your
browser. Treat the number as a guide, not a target. Many
integration paths are covered indirectly by the in-process integration
tests, smoke tests, real-stack E2E, and simulation — none of which
contribute to Go's coverage profile for the package under test.
What runs in CI¶
The backend CI workflow (.github/workflows/backend-ci.yml) runs verify:backend,
the sqlc drift guard, test:smoke, test:unit and build:backend on the
in-cluster tomoda-arc runners. The integration job runs on tomoda-arc-db, whose
runner pod carries the production Postgres image, ghcr.io/tomoda-labs/tomoda-postgres
(PostGIS, PGroonga, pgvector, h3-pg), as a sidecar on localhost:5432 with the extensions
and the tomoda database already created. It runs the schema drift check (with the
runner image's Postgres 17 pg_dump) and backend/tests/integration/... with
REQUIRE_DB=1, so an unreachable database fails instead of skipping. The image tag is
pinned in the devops repo (k8s/envs/platform/arc-runners-db/values.yaml); see the
ARC runners (devops docs).
task ci is the umbrella target — lint, vet, format,
typecheck, test, build. Run it locally before pushing if you
want a fast confidence check that CI will be happy.
CI runs in GitHub Actions: backend-ci.yml / frontend-ci.yml for checks,
images.yml for image builds (see Container images).
Playwright in CI
The Playwright suite needs npm install && npx playwright install
before running. The driver script scripts/dev/run_e2e.sh handles
both. Headless Chromium binaries are not committed; CI must
install them.