Skip to content

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.go beside foo.go under internal/**. No real infra; must pass under -short. May reach unexported symbols (same package) or use the foo_test external package.
  • Integration — under backend/tests/integration/<service>/, package integration (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 in internal/**. Test functions carry Integration in the name so task test:integration selects them.
  • Smoke — backend/tests/smoke/ (package smoke): 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 in internal/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/, package integration): miniredis-backed flows that exercise contracts across packages. Examples: two websocket.Hub instances exchanging messages via chat:event:* pub/sub with origin-dedup; three scheduler.Scheduler instances electing a single leader and failing over; Worker queue ownership; ChatService cache hit/miss + trim; auth refresh-token full lifecycle.
  • Frontend (frontend/__tests__/integration/): AuthContext + login flow with a mocked fetch; chatService WS 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 --mode resolver (full / multi-hub / async / api-hub / ws-hub) and a Wire DI smoke that calls the real InitializeApp against miniredis + sqlite to assert every top-level component is non-nil.
  • backend/tests/smoke/ — runtime-shape checks: Hub.Run starts without panic (with + without Redis), /health responds, 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 via page.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:

  1. Detects Docker or Podman + a compose tool.
  2. npm install + npx playwright install chromium in e2e/.
  3. Brings up the full application stack with docker compose up -d --build (uses docker-compose.yml, the production-style compose file with backend + frontend containers built locally).
  4. Polls http://localhost:8080/health until the backend is healthy (max ~60s).
  5. Polls http://localhost:8081 until the frontend returns 200 OK.
  6. Runs npx playwright test.
  7. 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:

  1. 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.
  2. 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. Needs gcloud login.
  3. Runs backend/cmd/test/sim-workers — spins up the worker pool that simulates user behavior. Ctrl+C to 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.