MusicFS/scripts/e2e/README.md

musicfs E2E Tests

Full distributed-path tests: server in Incus VM, local FUSE client, tests run against the mountpoint.

Prerequisites

• Inside devenv shell (provides ffmpeg, metaflac, id3v2, incus, grpcurl, Postgres)
• Postgres running (devenv up postgres)
• Incus installed and configured

Run

just e2e              # full suite (creates VM, runs tests, destroys VM)
KEEP=1 just e2e       # keep VM + DB alive after run for debugging

What it tests

Phase	Description
structural	Virtual directory tree matches fixture tags
cache	First read = cache miss, second read = cache hit
FLAC read	metaflac reads tags through FUSE reassembly
FLAC write	metaflac writes vorbis comment, write handler persists
MP3 read	id3v2 reads ID3v2 tags through FUSE reassembly
MP3 write	id3v2 writes tags, write handler persists
chunked write	Non-metadata writes don't corrupt tag structure
persistence	Tags survive client restart (DB restore path)

Fixtures

make-fixtures.sh generates a deterministic library under target/e2e/music/:

E2E Artist A/E2E Album X/01 - Alpha.flac  (with cover art)
E2E Artist A/E2E Album X/02 - Beta.flac
E2E Artist B/E2E Album Y/01 - Gamma.mp3   (with cover art)
E2E Artist B/E2E Album Y/02 - Delta.mp3

All tags are known at test time → exact assertions.

Profiles

just up e2e    # start client against e2e VM (manual testing)

Client uses musicfs_e2e database and ./logs/e2e for logs.