Stabilize DB-backed test lanes

Author: dzarlax

.github/workflows/ci.yml

@@ -19,11 +19,29 @@ on:
         description: "Run Go race detector tests"
         type: boolean
         default: false
+      run_db_tests:
+        description: "Run DB-backed test lanes with a Postgres service"
+        type: boolean
+        default: false
+      db_test_lane:
+        description: "DB lane to run when run_db_tests is true"
+        type: choice
+        default: stable
+        options:
+          - stable
+          - routine
+          - ui
+          - energy
+          - readiness
+          - storage
 
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
+permissions:
+  contents: read
+
 jobs:
   build:
     name: Build, Vet & Test
@@ -42,18 +60,70 @@ 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 job even if libpq environment
+      # variables happen to exist. The separate DB Tests job runs the
+      # stable DB lanes with an isolated Postgres service on PR/push.
       #
       # 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
+
+  db-tests:
+    name: DB Tests
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'workflow_dispatch' || inputs.run_db_tests }}
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: health_test
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d health_test"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 12
+    env:
+      HEALTH_DB_TESTS: "1"
+      PGHOST: localhost
+      PGPORT: "5432"
+      PGDATABASE: health_test
+      PGUSER: postgres
+      PGPASSWORD: postgres
+      GOCACHE: /tmp/health-go-build-cache
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Run routine DB lane
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.db_test_lane == 'stable' || inputs.db_test_lane == 'routine' }}
+        run: make test-db
+
+      - name: Run full UI DB lane
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.db_test_lane == 'stable' || inputs.db_test_lane == 'ui' }}
+        run: make test-db-ui
+
+      - name: Run full Energy DB lane
+        if: ${{ github.event_name != 'workflow_dispatch' || inputs.db_test_lane == 'stable' || inputs.db_test_lane == 'energy' }}
+        run: make test-db-energy
+
+      - name: Run Readiness DB lane
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.db_test_lane == 'readiness' }}
+        run: make test-db-readiness
+
+      - name: Run full Storage DB lane
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.db_test_lane == 'storage' }}
+        run: make test-db-storage
 
   race:
     name: Race Detector
@@ -78,7 +148,7 @@ jobs:
     name: Docker Build & Push (amd64)
     needs: build
     runs-on: ubuntu-latest
-    if: ${{ github.ref == 'refs/heads/main' && (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.build_amd64 && !inputs.run_race)) }}
+    if: ${{ github.ref == 'refs/heads/main' && (github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && inputs.build_amd64 && !inputs.run_race && !inputs.run_db_tests)) }}
     permissions:
       contents: read
       packages: write
@@ -119,7 +189,7 @@ jobs:
     name: Docker Build & Push (arm64)
     needs: build
     runs-on: ubuntu-latest
-    if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'workflow_dispatch' && inputs.build_arm64 && !inputs.run_race }}
+    if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'workflow_dispatch' && inputs.build_arm64 && !inputs.run_race && !inputs.run_db_tests }}
     permissions:
       contents: read
       packages: write

CONTRIBUTING.md

@@ -17,21 +17,52 @@ 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.
 
 ### CI and race detector policy
 
 The default required-looking CI job is `Build, Vet & Test`. Keep that job name stable unless repository branch protection is updated at the same time.
 
-Default PR and push CI uses `CGO_ENABLED=0` for build, vet, and tests, matching the production binary. Race detector tests are available as a manual GitHub Actions run: start the `CI` workflow with `run_race=true`. Race-only dispatches do not publish Docker images, even when the image build inputs are left at their defaults. Use this before merging changes that touch tenant management, scheduler goroutines, async AI generation, recompute coordination, Telegram webhook dispatch, or notification loops.
+Default PR and push CI uses `CGO_ENABLED=0` for build, vet, and unit tests, matching the production binary, and also runs the stable DB lanes against an isolated Postgres service container: routine `make test-db`, full UI DB, and full Energy DB. Full Storage DB is still manual because the current full storage package exceeds the 120s lane timeout in chronic-load writer tests.
+
+Manual DB runs are available through the `CI` workflow: set `run_db_tests=true` and choose `stable`, `routine`, `ui`, `energy`, `readiness`, or `storage`.
+
+Race detector tests are also manual: start the `CI` workflow with `run_race=true`. Race-only and DB-only dispatches do not publish Docker images, even when the image build inputs are left at their defaults. Use the race detector before merging changes that touch tenant management, scheduler goroutines, async AI generation, recompute coordination, Telegram webhook dispatch, or notification loops.
 
 For local checks on a machine with a CGO toolchain:
 

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`. Domain verification; currently around 22s after fixture narrowing and batched seed inserts. |
+| 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, pure tests, routine DB, full UI DB, and full Energy DB against an isolated Postgres service. Full Storage DB and race detector remain manual. | Move full storage into default CI only after the chronic/acute writer families fit a bounded timeout. |
 
 ## Delivered First Batch