Testing Guide

Step-by-step walkthrough for testing libsavesync, based on the spec's suggested first test plan.

Current Test Suites

The project has 4 test suites totaling 169 tests:

Suite	File	Covers	Count
Basic	`test/test_basic.c`	DEFAULT mode: register, save, dedup, pull, retention, orphaning	53
Strategy	`test/test_strategy.c`	STRATEGY mode: manifest lifecycle, identity resolution (Tier 1/2/3), fallback chain, integration	48
Regressions	`test/test_regressions.c`	Historical bug regressions (serialize pointer, opaque accessor, dangling pointer, tiebreak)	34
Phase 3 Regressions	`test/test_phase3_regressions.c`	Phase 3 risk surfaces (coexistence, dedup after identity failure, shape mismatch, retention + game_id, metadata round-trip, hash-DB callback)	34

make test       # builds and runs all four suites

Individual suites can be built and run manually from build/:

./build/test_basic
./build/test_strategy
./build/test_regressions
./build/test_phase3_regressions

Every test is classified as either:

INVARIANT — asserts a rule that must always hold regardless of implementation details (e.g., "dedup must skip when hash matches most recent entry")
SNAPSHOT — checks today's specific output/return value (e.g., "sv_save returns SV_OK")

Invariant tests are more valuable because they survive refactors. The full classification is in docs/test-audit.md (engineering working note).

Current counts:

File	Invariant	Snapshot	Total
test_basic.c	32	21	53
test_strategy.c	28	20	48
test_regressions.c	34	0	34
test_phase3_regressions.c	34	0	34
Total	128	41	169

The regression test files are 100% invariant — every test asserts a structural rule.

The original test plan (from the spec) validated the hardest-to-get-right parts first:

...all against zero-risk fake data, deferring emulator-specific complexity to last.

See CONTRIBUTING.md for the full regression test convention and guidelines on where to add new tests.

libsavesync Wiki