docs backend TEST_STRATEGY

Test strategy and gates

P01 platform and API-contract tests now exist; prior local runs are recorded in the P01 evidence archive and baseline validation. Business, end-to-end and deployed-infrastructure coverage below remains planned where its feature does not exist. Never infer a new successful run from historical evidence.

CI_PLAN owns cadence: focused local checks per task, specialized exit checks plus short CI per phase integration, and the complete matrix on the P09/G09 candidate. G01-FLOW and required Quick verification are active; G09-LOCAL permits app development and real G09 certification waits until G18. Targeted critical checks are never deferred to the end of the project.

Risk-based checks

• Documentation-only: link/path/roadmap consistency, validateRepoBaseline where relevant, git diff --check; inspect untracked new files separately because ordinary diff cannot cover them.
• Domain: document B-BR and GIVEN/WHEN/THEN → a focused failing test → minimum implementation → refactor. Pure deterministic unit tests, injected clock/IDs, no real DB/network/files. Aim for meaningful ≥90% domain coverage, including boundary/invalid cases; percentage does not replace behavior review.
• Application: fake ports test authorization, atomic intent, error mapping and orchestration; no mocked assertion that merely mirrors implementation.
• Persistence/geo/jobs: real PostgreSQL/PostGIS, production migrations/SQL, concurrent transactions, lease expiry/fencing, uniqueness and dead-job recovery. Use a dedicated disposable Compose service initially; Testcontainers only if it solves a concrete CI need.
• HTTP/security: real handlers with httptest; request/response contract validation, body/time limits, auth, replay, quota, IDOR, owner-only status, no-store and error redaction. Proxy/staging tests cover authority/signature forwarding and actual CDN behavior.
• Evidence: malformed/oversize/decompression inputs, MIME spoof, overwrite-after-HEAD race, orphan lifecycle, repeated finalize, owner mismatch, EXIF removal and deletion. Local S3-compatible tests plus one staging R2 suite, because emulator compatibility is insufficient evidence.
• ANP/golden: immutable public samples, source checksums, exact money/units, all labels/dates/CNPJ forms, header change/quarantine, correction revisions and Kotlin legacy compatibility cases. Live source discovery is a scheduled/manual smoke, not a flaky prerequisite for every unit test.
• Migration: apply all from empty, upgrade previous released schema with representative rows, migration checksum drift, concurrent migrator lock, incompatible binary refusal, expand/contract behavior and failed-migration recovery. A destructive down migration is not the default rollback.
• E2E: register → upload → finalize → observe → validate → independent confirm → read source-separated projection; dispute/moderate; rights deletion/restore. Synthetic protocol clients remain local backend fixtures; after G09-LOCAL, shared/native clients add Android/iOS contract/device evidence.
• Load/recovery: INFRASTRUCTURE_PLAN workload and latency budgets, full restore into new environment, DB/storage outage and worker crash. Store hardware/data/config/commit with results so runs can be compared.

Reproducible command contract

Existing Android commands from repository root:

bash scripts/validate-repo-baseline.sh
./gradlew :domain:test :application:test
./gradlew :data:testDebugUnitTest :app:testDebugUnitTest
./gradlew :domain:jacocoTestCoverageVerification :app:lintDebug :app:assembleDebug
./gradlew :data:connectedDebugAndroidTest :app:connectedDebugAndroidTest

Requires JDK 17, Android SDK 35 and emulator/device for instrumentation. P01 re-validation records a successful unit/build baseline after prerequisite setup; it does not imply instrumentation passed or every future environment has these prerequisites. Do not change toolchain versions merely to make a workstation pass.

Backend tools and initial gate scripts were introduced in P01; exact pins and disposable DB environment are in backend/README. The commands below are verification building blocks, not a checklist to repeat after every task. Examples run from backend/ unless noted:

go test ./...
go test -race ./...
go vet ./...
staticcheck ./...
govulncheck ./...
sqlc vet
sqlc generate
git diff --exit-code -- internal/
go test -tags=integration ./...

Use gofmt -l with an explicit fail-if-output check (gofmt listing alone can exit zero). sqlc generate runs only after config/SQL exist; generated diff check belongs in a clean CI checkout. Pin staticcheck/sqlc/govulncheck and OpenAPI validators. The integration job must set a documented disposable DATABASE_URL and apply migrations; it must fail, not skip, if PostGIS is unavailable. Follow the implemented invocation/env in backend/README; never point destructive integration fixtures at a persistent environment.

Target quick gate: format/build/vet, actual short critical/platform suites, reference/secret checks and applicable contract-generation checks, within a measured budget. A compile-only test command is not behavioral evidence. Migration/SQL/security changes require their relevant real DB/adversarial tests locally and at specialized phase exit; dependency changes require relevant vulnerability checks immediately. Do not turn the quick job into the whole release matrix.

Full gate before backend release: all unit/static/coverage/race tests, real PostGIS, empty/upgrade migrations, end-to-end/auth/evidence, dependency/image/security scans, deploy/restore/load evidence, existing Android regression baseline and frozen cross-language fixture expectations. Select the immutable candidate after phase integration and record the complete expected-result manifest. Reuse expensive evidence only for demonstrably matching artifacts/config/inputs under CI_PLAN. Full Kotlin↔Go↔Swift parity starts P12/P10 after G09-LOCAL; native/macOS evidence is mandatory where applicable.

Fixture boundaries and anti-flakiness

contracts/testdata/: ANP normalization, price/condition/unit/fuel compatibility, identity signed-byte vectors, invalid signatures/replay, API errors, enum forward compatibility and consensus examples. Each fixture has ID/version/provenance and intentional Android differences. Synthetic identities/images only; never export production photos, keys or contributor traces.

Use fixed clock and UUID sequences, stable sort/tie-breaks, barriers rather than sleeps for races, bounded retry on external test infrastructure only. No random-based flaky assertions or wall-clock domain checks. Verify nondeterministic job backoff separately with bounded injected jitter. Every production bug gets a regression test before/with the fix.

Gate evidence

For every task record commands, tested commit/tree, environment, pass/fail and limitation in the compact phase record linked from docs/planning/PROGRESS.md. Archive long histories; keep current state short. LOCAL_DONE, phase INTEGRATED and RELEASE_CERTIFIED are separate states. No disabled/deleted tests to create green CI. A failed prerequisite is BLOCKED, not PASS. G09 cannot be checked off while restore/security/runtime/backend requirements remain theoretical.

Local process validation (P09-T01 follow-up)

The public-process integration test in cmd/api starts the actual API with a fresh database, requires an explicit disposable ANPFUEL_TEST_DATABASE_URL, and checks schema readiness, challenge/enrollment, exact wire fuel/unit, idempotency, replay, owner isolation and rotation. Set all ANPFUEL_TEST_STORAGE_{ENDPOINT, BUCKET,REGION,ACCESS_KEY_ID,SECRET_ACCESS_KEY} values to enable the real worker and private S3-compatible photo flow (valid JPEG, malformed image, independent confirmation and dispute). Missing storage selects the deliberate 503 path; it does not count as successful S3 validation.

ANPFUEL_ANP_DISCOVERY_ENABLED=false suppresses the external-source scheduler for isolated process tests. Its default is true; disable it explicitly for local synthetic runs. Local S3 and local HTTP/TLS results do not certify real R2/CDN, production infrastructure or a public release. Private/no-store responses and mutations must never become 304 through If-None-Match. Storage transports must refuse redirects and omit signed URLs and remote response bodies from errors.