box-box/docs/testing.md

Testing

Go

Targeted offline-ish packages:

go test ./internal/live ./internal/models ./internal/store ./internal/ingest ./internal/query ./internal/web

All packages:

go test ./...

OpenF1 integration tests require network access and are rate-limit aware:

go test -v ./internal/api

Frontend Unit Tests and Build

npm --prefix frontend test -- --run
npm --prefix frontend run build

E2E

The default Playwright config starts a seeded Go server on port 18080 and Vite on 15173.

npx playwright install   # first time only
npm run test:e2e

Production serving mode builds around Go serving frontend/dist:

npm run test:e2e:prod

Visual Regression

npm run test:visual
npm run test:visual:prod

After intentional UI changes:

npm run test:visual:update
npm run test:visual:prod:update

Snapshots live under tests/visual/__snapshots__/.

Release Fidelity and Owner Review

Visual regression and mockup fidelity are deliberately separate gates. npm run test:visual:prod verifies the candidate against committed regression snapshots; it does not establish that the current UI matches the approved product design.

After the approved references are available at docs/product/<version>/mockups/, make an offline review packet. For v0.4.0 the packet pairs weekend-between-races and weekend-live at the 1280×800 desktop reference viewport, plus weekend-between-sessions-mobile at the 390×844 mobile reference viewport. The capture configuration uses the same seeded SQLite data and unreachable OpenF1 endpoint as the visual suite.

export RELEASE_FIDELITY_VERSION=v0.4.0
npm run release:fidelity:capture
npm run release:fidelity:packet

Open release-fidelity/v0.4.0/index.html and review every approved-mockup/candidate pair. The owner, not an automated tool, records a decision in the committed file docs/release/owner-reviews/v0.4.0.md:

# Owner Fidelity Sign-off: v0.4.0

- Version: v0.4.0
- Candidate commit: <full commit SHA>
- Reviewed by: <owner name>
- Reviewed on: YYYY-MM-DD
- Decision: approved

Do not create the file or use approved until the owner has reviewed the packet. Once it is committed, the release gate can verify the evidence and decision:

npm run release:fidelity:verify

The verifier checks that the packet exists and the sign-off exists in HEAD, names the current candidate commit, and has the required owner fields. It intentionally cannot assess visual fidelity or create approval.

For a release candidate, npm run release:fidelity:gate runs production visual regression first, then capture, packet generation, and owner-evidence verification in that order. It will remain red until the owner has committed the sign-off.

Deployment and Rollback

Build and preserve a SHA-256 record with the deployable binary. Verify the staged binary before replacing the running one:

mkdir -p dist
go build -trimpath -o dist/box-box ./cmd/main.go
sha256sum dist/box-box | tee dist/box-box.sha256
sha256sum -c dist/box-box.sha256

Record the current production binary and its SHA before deployment. If owner review rejects the release or deployment fails, restore that saved binary, then verify the restored SHA is byte-identical to the pre-deployment record:

sha256sum /srv/box-box/box-box
install -m 0755 /srv/box-box/backups/box-box.previous /srv/box-box/box-box
sha256sum -c /srv/box-box/backups/box-box.previous.sha256

Restart and health-check the service using the deployment environment's normal procedure. Keep the candidate SHA, prior SHA, fidelity packet path, and owner sign-off path with the release record.