rvbox/docs/testing.md

RVBox implementation test workflow

All Go, protobuf, and harness work runs in the pinned toolchain container. No host Go installation is used.

Run the normal pre-commit gate with:

make verify

Run focused unit tests with:

scripts/test-unit --package ./internal/domain --run UUIDv7 --race

The integration harness provides the Phase 0 sample suite and the incremental Phase 2 store suite. The latter uses a real temporary SQLite database in WAL mode and a real segment/audit filesystem; it does not mock the persistence boundary:

scripts/test-env doctor
scripts/test-integration --suite sample --run-id my-sample
scripts/test-env status --run-id my-sample
scripts/test-env collect --run-id my-sample
scripts/test-env reset --run-id my-sample
scripts/test-env reuse --run-id my-sample
scripts/test-integration --suite sample --run-id my-sample --resume
scripts/test-env reset --run-id my-sample
scripts/test-env purge --run-id my-sample

scripts/test-integration --suite store --run-id store-smoke
scripts/test-env logs --run-id store-smoke
scripts/test-env collect --run-id store-smoke
scripts/test-env reset --run-id store-smoke
scripts/test-env purge --run-id store-smoke

Suite output is capped at 1 MiB and stored as artifacts/suite.log. A failed run remains inspectable and can be moved back to ready with recover, then resumed with the same run ID and deterministic shuffle seed. Test-run cleanup never removes the shared Go module or build-cache volumes.

Each run owns only .test-runs/<run-id> and resources explicitly recorded in that run's versioned manifest. The journal is append-only and fsynced. purge validates the run ID and manifest identity, refuses symlink targets or manifests that still list runtime resources, and then removes only that exact run. Purged artifacts are not recoverable. Dependency cache volumes are never part of run cleanup.

test/coverage.toml is the incremental requirement-to-test inventory. The make verify lint stage checks unique stable IDs and verifies every implemented test reference against source. Native Windows integration/E2E entries remain explicitly blocked until the resettable Windows host is available; Wine or a protocol stub is not treated as equivalent coverage.