# Test strategy and gates

P01 platform and API-contract tests now exist; prior local runs are recorded in the [P01 evidence archive](docs-planning-history-P01_FOUNDATION_EVIDENCE.md) and [baseline validation](docs-planning-BASELINE_VALIDATION.md). 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](docs-planning-CI_PLAN.md) 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:

```sh
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](https://github.com/AlexandreZanata/brazil-fuel-prices/blob/08a54dc49c2e43a85aba56a7b56ae96d692cec61/backend/README.md). The commands below are verification building blocks, **not a checklist to repeat after every task**. Examples run from `backend/` unless noted:

```sh
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.