Stabilize DB-backed test lanes

Author: dzarlax

.github/workflows/ci.yml

@@ -42,18 +42,16 @@ jobs:
       - name: Vet
         run: CGO_ENABLED=0 go vet ./...
 
-      # Unit tests. All current test files are pure (no DATABASE_URL,
-      # no network) — verified by grepping *_test.go for DATABASE_URL,
-      # pgxpool, net.Dial → zero matches. If a future test grows
-      # external deps, gate it behind a build tag rather than wiring
-      # services into this job; the build job's purpose is catching
-      # logic regressions in seconds, not standing up a stack.
+      # Unit tests. DB-backed integration tests are gated by
+      # HEALTH_DB_TESTS=1 and skip in this default job even if libpq
+      # environment variables happen to exist. Keep this job focused on
+      # fast logic regressions; DB lanes are explicit local/manual runs.
       #
       # CGO_ENABLED stays at 0 (matches the build above). Use the
       # manual Race Detector job when reviewing concurrency-sensitive
       # changes; it runs with CGO=1 because Go's -race requires CGO.
       - name: Test
-        run: CGO_ENABLED=0 go test ./...
+        run: make test-unit
 
   race:
     name: Race Detector

CONTRIBUTING.md

@@ -17,13 +17,40 @@ Use Go 1.24+ and PostgreSQL.
 
 ```bash
 go mod tidy
-go test ./...
+make test-unit
 go vet ./...
 ```
 
 Dependencies are managed through normal Go module resolution. Review dependency changes in `go.mod` and `go.sum`; the repository does not commit a `vendor/` tree.
 
-DB-backed integration tests skip when no Postgres connection is configured. To run them, provide libpq environment variables or `READINESS_TEST_DSN`. Tests create throwaway schemas and drop them during cleanup.
+DB-backed integration tests are explicit. They skip unless `HEALTH_DB_TESTS=1` is set, even when `PGHOST` or other libpq variables are present in your shell. To run them, provide libpq environment variables or `READINESS_TEST_DSN`, then use:
+
+```bash
+HEALTH_DB_TESTS=1 make test-db-storage
+HEALTH_DB_TESTS=1 make test-db-ui
+HEALTH_DB_TESTS=1 make test-db-ui-fast
+HEALTH_DB_TESTS=1 make test-db-energy
+HEALTH_DB_TESTS=1 make test-db-energy-smoke
+HEALTH_DB_TESTS=1 make test-db-readiness
+HEALTH_DB_TESTS=1 make test-db
+```
+
+`test-db` is the routine DB contract aggregate: fast UI DB smoke, EnergyBank DB smoke, and targeted Readiness DB checks. It intentionally does not run the full UI package, full EnergyBank verdict-band suite, or full `./internal/storage` package. Use the full domain lanes when a change touches that area.
+
+Lane commands:
+
+```bash
+make test-db           # routine DB contract: ui-fast + energy-smoke + readiness
+make test-db-ui-fast   # representative UI/admin DB handler checks
+make test-db-energy-smoke # one EnergyBank verdict-band DB contract check
+make test-db-readiness # readiness schema/calibration DB checks
+make test-db-ui        # full internal/ui DB package sweep
+make test-db-energy    # full EnergyBank verdict-band DB group
+make test-db-storage   # full internal/storage DB package sweep
+```
+
+When `HEALTH_DB_TESTS=1` is set, missing or unreachable Postgres is a test failure, not a skip. Tests create throwaway schemas with test prefixes and drop them during cleanup.
+Readiness monitoring and broad readiness writer families are intentionally outside the routine `test-db-readiness` lane until their fixtures are narrowed or runtime is measured separately. Full UI, full Energy, and full Storage lanes are manual/domain sweeps, not the normal edit-loop.
 
 See `docs/TEST_COVERAGE.md` for the current focused coverage roadmap and fixture rules.
 

Makefile

@@ -1,4 +1,4 @@
-.PHONY: dev build backfill backfill-force energy-backfill energy-backfill-dry import docker-up docker-down test
+.PHONY: dev build backfill backfill-force energy-backfill energy-backfill-dry import docker-up docker-down test test-unit test-db-storage test-db-ui test-db-ui-fast test-db-energy test-db-energy-smoke test-db-readiness test-db smoke-health-post
 
 ADDR ?= :8080
 
@@ -40,7 +40,33 @@ docker-up:
 docker-down:
 	docker compose down
 
+test-unit:
+	HEALTH_DB_TESTS= CGO_ENABLED=0 go test ./...
+
+test-db-storage:
+	HEALTH_DB_TESTS=1 go test ./internal/storage -count=1 -timeout=120s
+
+test-db-ui:
+	HEALTH_DB_TESTS=1 go test ./internal/ui -count=1 -timeout=120s
+
+test-db-ui-fast:
+	HEALTH_DB_TESTS=1 go test ./internal/ui -run "^(TestAdminCheckinCoverage_JSONShape|TestOnboardingWizard_RejectsSchemaAll|TestFragmentAdminReadinessMonitoring_Renders)$$" -count=1 -timeout=60s
+
+test-db-energy:
+	HEALTH_DB_TESTS=1 go test ./internal/storage -run "TestComputeUserVerdictBands" -count=1 -timeout=90s
+
+test-db-energy-smoke:
+	HEALTH_DB_TESTS=1 go test ./internal/storage -run "^TestComputeUserVerdictBands_UsesCompatibleFormulaWarmup$$" -count=1 -timeout=30s
+
+test-db-readiness:
+	HEALTH_DB_TESTS=1 go test ./internal/storage -run '^(TestSaveNaiveBaseline_NilValueWithValidReasonPersists|TestVerifyReadinessRedesignSchema_DetectsReasonColumnDrift|TestRecomputeChipCalibrations_Integration_(RejectsCrossEpochLabels|PercentileP80|InsufficientData))$$' -count=1 -timeout=90s
+
+test-db: test-db-ui-fast test-db-energy-smoke test-db-readiness
+
 test:
+	$(MAKE) smoke-health-post
+
+smoke-health-post:
 	curl -s -X POST http://localhost$(ADDR)/health \
 		-H "Content-Type: application/json" \
 		-H "automation-name: Test" \

docs/TEST_COVERAGE.md

@@ -4,11 +4,24 @@ This roadmap tracks high-value Health Dashboard test coverage without turning th
 
 ## Constraints
 
-- Default CI must stay pure and fast under `go test ./...`.
+- Default CI must stay pure and fast under `make test-unit` / `go test ./...`.
 - Fixtures must be synthetic or anonymized. Do not commit personal health exports, screenshots, logs, or raw metric dumps.
-- DB-backed tests should skip cleanly unless a Postgres connection is configured.
+- DB-backed tests should skip cleanly unless `HEALTH_DB_TESTS=1` is set. When that flag is set, missing or unreachable Postgres is a failure.
 - Coverage thresholds are intentionally deferred until the active product contracts have a useful baseline.
 
+## Test Lanes
+
+| Lane | Command | Contract |
+|---|---|---|
+| Unit/default | `make test-unit` | Fast pure suite. DB tests skip even if libpq env vars are present. |
+| Routine DB | `HEALTH_DB_TESTS=1 make test-db` | Fast sequential DB contract aggregate: UI smoke, Energy smoke, and targeted Readiness DB checks. This is the normal DB edit-loop. |
+| UI DB smoke | `HEALTH_DB_TESTS=1 make test-db-ui-fast` | Representative UI/admin DB handler checks. |
+| Energy DB smoke | `HEALTH_DB_TESTS=1 make test-db-energy-smoke` | One EnergyBank verdict-band DB contract check. |
+| Readiness DB | `HEALTH_DB_TESTS=1 make test-db-readiness` | Runs an explicit readiness storage regex covering baseline persistence/schema drift and chip calibration recompute. Monitoring and broad readiness-adjacent writer families stay out until measured or migrated. |
+| UI DB full | `HEALTH_DB_TESTS=1 make test-db-ui` | Full `./internal/ui` DB package sweep. Manual/domain verification; currently around 41s on the remote Postgres path. |
+| Energy DB full | `HEALTH_DB_TESTS=1 make test-db-energy` | Full EnergyBank verdict-band DB group: `go test ./internal/storage -run "TestComputeUserVerdictBands" -count=1 -timeout=90s`. Manual/domain verification; currently around 56s after fixture narrowing. |
+| Full Storage DB | `HEALTH_DB_TESTS=1 make test-db-storage` | Full `./internal/storage` DB package run. Manual/pre-merge only; not part of `make test-db`. |
+
 ## Current Coverage Map
 
 | Area | Current state | Next useful coverage |
@@ -18,7 +31,7 @@ This roadmap tracks high-value Health Dashboard test coverage without turning th
 | UI and admin APIs | Contract tests cover admin pages, auth/session behavior, webhook dispatch, dashboard sections, and tenant scope. | Pin response-shape changes before frontend code starts depending on them. |
 | Storage writers | Readiness redesign, EnergyBank, sleep gates, freshness, calibration, and tenant helpers have focused tests, with DB-backed tests gated. | Prefer bug-driven storage contract tests over broad repository-level sweeps. |
 | Notifications | Morning/evening report, freshness banners, smart retry, Telegram webhook, and proactive framework tests cover key behavior. | Add regression tests when notification timing or skip conditions change. |
-| CI policy | Default CI runs build, vet, and pure tests; race detector is manual and documented. | Keep race detector separate from default PR checks unless the runtime cost becomes acceptable. |
+| CI policy | Default CI runs build, vet, and pure tests; targeted DB lanes are explicit local/manual checks; race detector is manual and documented. | Keep race detector and DB service-container CI separate from default PR checks unless the runtime cost becomes acceptable. |
 
 ## Delivered First Batch