Testing Guide

Testing Guide

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

Phase 1: Core with Default Mode

Implement Layers 1, 3, 4, 5 fully; implement Layer 2 with SV_MODE_DEFAULT only (no identity resolution, no manifest).

Step 1: Basic Registration and Save

1. Register a plain text file as a fake "save" using sv_register() with SV_MODE_DEFAULT
2. Call sv_save() — verify a new magazine entry is created
3. Call sv_list_entries() — confirm entry count is 1
4. Call sv_read_entry() — verify metadata fields are populated correctly

Step 2: Dedup Verification

1. Call sv_save() again without modifying the file
2. Verify dedup skipped — no new entry created (hash matches most recent)
3. Modify the file content
4. Call sv_save() — verify a new entry is created (hash differs)

Step 3: Force Save

1. Call sv_save() with opts.force = true on unchanged content
2. Verify a new entry is created despite identical hash

Step 4: Pull Select

1. Call sv_pull_select() targeting an older entry
2. Verify atomic replace worked — file content matches the selected entry
3. Verify the pull was conflict-checked (live file had changed)

Step 5: Retention Eviction

1. Push retention count low (e.g. 2) via sv_update_register()
2. Call sv_save() to trigger eviction
3. Confirm oldest entry was evicted and evicted_ids in result is populated
4. Verify correct number of entries remain

Phase 2: Shape Variants

Repeat Phase 1 with different save shapes:

1. SAVE_SHAPE_DIRECTORY — create a fake directory with multiple files
2. Multi-file container — validate shape handling before any real emulator format

Phase 3: Strategy Mode

Only after Phases 1-2 are solid:

1. Implement one real SV_MODE_STRATEGY case (e.g. RetroArch single-file .srm)
2. Use Freegosy's existing logic as reference for path templates and identity methods
3. Verify identity resolution works against real save files

Phase 4: Transport

1. Implement a trivial "copy to another local folder" reference transport
2. Test sv_push_external() and sv_pull_external() with this transport
3. Verify the two-step model: pull_external → pull

Test Order Rationale

This order validates the hardest-to-get-right parts first:

• Atomicity (temp file + rename)
• Conflict handling (report vs override)
• Retention (FIFO eviction)
• ABI shape (opaque structs, zero-default fields)

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

---

See also: Architecture-Overview | Layer-4-Local-Save-and-Pull | Layer-5-Retention-and-Rotation