mergerfs/tests/OPTIONS_TEST_PLAN.md

# Options Test Plan

Possible integration and unit tests for options listed in `mkdocs/docs/config/options.md`.

Legend:
- **Integration**: mount-level behavior test (black-box, syscall parity / side effects)
- **Unit**: focused parser/config/logic test (white-box or low-level component)

## Core mount and branch options

| Option | Integration tests | Unit tests |
|---|---|---|
| `config` | Load same settings via CLI vs config file and compare behavior | Parse comments, `key`, `key=val`, unknown keys, duplicate keys ordering |
| `branches` | Multi-branch create/search/action behavior; glob expansion; dynamic branch updates | Branch string parser ops (`+`, `+<`, `+>`, `-`, `->`, `-<`, `=`), mode parse, minfreespace parse |
| `mountpoint` | Verify mount succeeds/fails with valid/invalid mountpoint | Config validation for mountpoint path |
| `branches-mount-timeout` | Delayed branch mount appears before timeout -> starts; after timeout -> continue/fail based on flag | Timeout arithmetic and mount-detection helper logic |
| `branches-mount-timeout-fail` | Timeout expiration returns non-zero when true | Boolean parse and gating of startup continuation |
| `minfreespace` | Create policy excludes near-full branches | Size parser (`B/K/M/G/T`, overflow, bad suffix) |
| `moveonenospc` | ENOSPC write triggers move+retry and preserves metadata | Policy dispatch and error mapping (`ENOSPC`/`EDQUOT`) |
| `inodecalc` | Stable inode expectations per mode on files/dirs/hardlinks | Hash function determinism and 32-bit/64-bit variants |

## IO behavior options

| Option | Integration tests | Unit tests |
|---|---|---|
| `dropcacheonclose` | Close after write/read and confirm no correctness regression | `posix_fadvise` call path invoked only when enabled |
| `direct-io-allow-mmap` | `O_DIRECT` + `mmap` behavior on supported kernels | Feature flag gating by kernel capability |
| `nullrw` | Writes report success but data unchanged; reads become no-op behavior | Read/write null path selection |
| `readahead` | Sequential read throughput/request size changes with non-zero setting | Parser and branch-level readahead setter behavior |
| `async-read` | Concurrent read ordering/parallelism differs when toggled | FUSE config flag toggling |
| `fuse-msg-size` | Large IO request chunking and throughput with different values | Pagesize conversion parser and min/max clamping |
| `flush-on-close` | `never/always/opened-for-write` close semantics | Mode enum parse and branching logic |
| `proxy-ioprio` | Different caller ioprio reflected in IO scheduling side-effects | ioprio fetch/apply path and fallback behavior |
| `parallel-direct-writes` | Parallel non-extending writes behavior with/without option | Kernel capability gating |
| `passthrough.io` | `off/ro/wo/rw` path selection for reads/writes and incompatibility checks | Enum parse, compatibility checks (`cache.writeback`, `nullrw`, etc.) |
| `passthrough.max-stack-depth` | Stacked FS scenarios with depth 1 vs 2 | Range validation and config propagation |

## Path transformation and cross-device options

| Option | Integration tests | Unit tests |
|---|---|---|
| `symlinkify` | Old non-writable files appear as symlinks after timeout | Eligibility predicate (mode, age, type) |
| `symlinkify-timeout` | Boundary test around exact timeout second | Timeout comparison helper |
| `ignorepponrename` | Rename behavior with and without path preservation | Rename policy selection logic |
| `follow-symlinks` | `never/directory/regular/all` on symlink to file/dir/broken link | Enum parse and target-type dispatch |
| `link-exdev` | EXDEV hardlink fallback modes: passthrough/rel/abs-base/abs-pool | Strategy selection and symlink target synthesis |
| `rename-exdev` | EXDEV rename fallback modes: passthrough/rel/abs | Fallback path generation and state machine |
| `link-cow` | Hardlinked file opened for write breaks link and writes private copy | Link-count check and copy-on-write trigger logic |

## Permission and metadata options

| Option | Integration tests | Unit tests |
|---|---|---|
| `export-support` | NFS-export style behavior sanity and mount flags exposure | Init-time flag propagation |
| `kernel-permissions-check` | Access/permission checks handled by kernel vs userspace path | Mount option mapping (`default_permissions`) |
| `security-capability` | `security.capability` xattr returns ENOATTR when disabled | Name filter helper |
| `xattr` | `passthrough/noattr/nosys` behavior for set/get/list/remove xattr | Enum parse and short-circuit return paths |
| `statfs` | `base` vs `full` branch inclusion by path | Mode parse and branch-filter helper |
| `statfs-ignore` | `none/ro/nc` effect on available space accounting | Ignore predicate and accumulator logic |
| `nfsopenhack` | File create/open mode behavior under NFS-like patterns | Enum parse and hook decision logic |
| `posix-acl` | ACL xattr roundtrip and chmod/chown interaction when enabled | Mount/init flag propagation |

## Threading and scheduling options

| Option | Integration tests | Unit tests |
|---|---|---|
| `read-thread-count` | Throughput/latency and correctness under different values | Value normalization (`0`, negatives, min=1) |
| `process-thread-count` | Separation of read/process pools and queue pressure behavior | Pool enable/disable logic |
| `process-thread-queue-depth` | Backpressure behavior with depth changes | Queue sizing and timeout/try-enqueue semantics |
| `pin-threads` | Thread CPU affinity placement for each strategy | Strategy parser and CPU selection algorithm |
| `scheduling-priority` | Process nice value set at startup and effective scheduling | Range validation and setpriority wrapper |

## Function/category policy options

| Option | Integration tests | Unit tests |
|---|---|---|
| `func.FUNC` | Override a single function policy and verify only that op changes | Parser mapping from key to policy holder |
| `func.readdir` | `seq/cosr/cor` ordering, latency, duplicate suppression, thread count parsing | Mode parser (`cosr:N:M`, `cor:N:M`) |
| `category.action` | Bulk action policy changes for chmod/chown/rename/unlink | Category-to-function propagation |
| `category.create` | Create policy effects on create/mkdir/mknod/link/symlink | Category propagation and precedence |
| `category.search` | Search policy effects on getattr/open/readlink/getxattr | Category propagation and precedence |
| Option ordering note | Later options override earlier (`func.*` then `category.*` etc.) | Deterministic application order test |

## Cache options

| Option | Integration tests | Unit tests |
|---|---|---|
| `cache.statfs` | Repeated statfs calls use cache within timeout | Timeout cache invalidation behavior |
| `cache.attr` | Repeated getattr freshness across timeout boundaries | Attr cache key and expiry logic |
| `cache.entry` | Name lookup caching for existing entries | Entry cache insertion/expiry |
| `cache.negative-entry` | Missing entry lookup caching and stale-negative behavior | Negative cache behavior |
| `cache.files` | `off/partial/full/auto-full/per-process` correctness and coherence | Enum parse and mode decision helper |
| `cache.files.process-names` | Per-process cache activation by comm name | List parser and matcher |
| `cache.writeback` | Coalesced write behavior; incompatibility handling with passthrough | Flag validation and FUSE config setup |
| `cache.symlinks` | Readlink repeated calls reflect cache policy | Feature gating by kernel support |
| `cache.readdir` | Readdir repeated calls and invalidation behavior | Feature gating and config wiring |

## Misc options

| Option | Integration tests | Unit tests |
|---|---|---|
| `lazy-umount-mountpoint` | Live-upgrade remount scenario with stale previous mount | Startup control flow and error handling |
| `remember-nodes` | NFS-like lookup stability over configured retention interval | Node cache retention/expiry logic |
| `noforget` | No node expiry over extended period | Infinite retention mode mapping |
| `allow-idmap` | UID/GID mapping behavior in idmapped mounts | Init flag propagation and compatibility checks |
| `debug` | FUSE trace generation enabled/disabled | Debug option parse and logger toggling |
| `log.file` | Trace output to stderr vs file path | Path parser and file sink setup |
| `fsname` | Filesystem name shown in mount/df matches config | fsname default derivation and override |

## Prioritized backlog (recommended first)

1. `xattr` mode tests (`passthrough/noattr/nosys`) + regression for current xattr mismatch
2. `statfs` / `statfs-ignore` mode matrix
3. EXDEV fallbacks (`link-exdev`, `rename-exdev`)
4. `follow-symlinks` + `symlinkify` behavior matrix
5. Policy precedence (`func.*`, `category.*`, ordering)
6. Cache timeout behavior (`cache.attr`, `cache.entry`, `cache.negative-entry`, `cache.statfs`)