# 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

```sh
just e2e              # full suite (creates VM, runs tests, destroys VM)
KEEP=1 just e2e       # keep VM + DB alive after run for debugging
just e2e-resilience   # resilience suite (server stop/start, network partition, outage recovery)
```

## What it tests

### Functional suite (`just e2e`)

| 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)            |

### Resilience suite (`just e2e-resilience`)

| Scenario          | Disruption                          | What it verifies                                         |
| ----------------- | ----------------------------------- | -------------------------------------------------------- |
| server stop/start | `systemctl stop/start` in VM        | EIO on uncached reads, cached reads survive, watcher resubscribes within 10s |
| network partition | `incus pause/start` (silent drop)   | EIO within 10s (tonic 3s timeout × kernel readahead), watcher detects via HTTP/2 keepalive within 30s |
| cache resilience  | server stop, all files pre-cached   | All reads/writes from cache, no server contact needed    |
| long outage       | `incus pause` for 15s+              | Watcher detects via keepalive PING, resubscribes within 10s of recovery |

## 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

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

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