Codify the testing playbook + tools inventory

Centralizes the decisions we made during the Step 1-6 speedup and the Step 7
+ mutation/state-machine/property/IPC investigations into two canonical docs:

- docs/testing.md: the playbook. Test pyramid, decision table (when to use
  which layer), anti-patterns with rationale (no `await sleep`, no synthetic
  F-key for dialog tests, no direct atomic mutation in state-machine tests,
  no `retries: 1` masking), and a per-feature checklist ("when you add X,
  also add Y").
- docs/tooling/testing.md: the tools inventory. One paragraph per tool —
  proptest, cargo-mutants, stryker, vitest mockIPC, pollUntil,
  dispatchMenuCommand, virtual-mtp, the Docker SMB containers, the
  checker, and the custom ESLint rules.

Plus per-module CLAUDE.md updates calling out the testing bar where it
matters most:

- write_operations/: state machine has 30+ tests, drive transitions via
  public interface, run cargo-mutants after substantial changes
- indexing/: IndexPhase lifecycle tests need a dedicated mutex + tempdir
  IndexStore; `Initializing` carries non-Clone owned state
- src/lib/ipc/: when to write an IPC contract test (destructive,
  cross-window, many-arg surfaces) and when to skip (thin getters)

And process integration:

- AGENTS.md: link to docs/testing.md from the Testing section
- docs/maintenance.md: quarterly mutation sweep, per-release E2E health
  check, per-release scan for new fixed sleeps in E2E specs, periodic
  triage of the legacy `eslint-disable cmdr/no-arbitrary-sleep-in-e2e`
  annotations

Author: vdavid

AGENTS.md

@@ -92,6 +92,10 @@ Core structure:
 
 ## Testing and checking
 
+**Before adding or modifying tests**, read [docs/testing.md](docs/testing.md) — the testing playbook (decision table,
+anti-patterns, per-feature checklist). The companion file [docs/tooling/testing.md](docs/tooling/testing.md) is the
+tools inventory.
+
 Always use the checker script for compilation, linting, formatting, and tests. Its output is concise and focused — no
 `2>&1`, `head`, or `tail` needed. Don't run raw `cargo check`, `cargo clippy`, `cargo fmt`, `cargo nextest run`, etc.
 

apps/desktop/src-tauri/src/file_system/write_operations/CLAUDE.md

@@ -255,3 +255,20 @@ and `statfs.f_fstypename` for APFS. See `copy_strategy.rs` for the implementatio
 - `crate::file_system::volume` — `Volume` trait, `SpaceInfo`, `ScanConflict` (used by `volume_copy`)
 - `crate::ignore_poison` — `IgnorePoison` extension for `RwLock`/`Mutex` to not panic on poisoned locks
 - External: `tauri` (emit, AppHandle), `uuid` (operation IDs, temp names), `libc` (access, statvfs, sync), `xattr`, `exacl`, `filetime` (metadata preservation in `chunked_copy`)
+
+## Testing bar
+
+This module's state machine (`state.rs`) is the spine of the cancel UX. Past investigations found one real production
+bug here ([commit `1de4255d`](../../../../../../docs/notes/speed-up-e2e-tests.md) — lost-rollback on `Ok(())` arm) plus
+30+ mutation-testing gaps that have since been pinned. New transitions or new cancel paths must:
+
+1. **Drive the state machine through the public interface in tests.** Direct `state.intent.store(...)` mutation bypasses
+   the validation guard and effectively dead-tests it. Pattern to copy: `state.rs::tests::test_cancel_via_public_path`.
+2. **Cover both the happy path and the cancel-during-X race** for any new write-side operation. The Cancel-copy bug
+   was specifically the `Ok(())` arm of the loop not re-checking intent.
+3. **Add at least one E2E test** for user-visible flows (transfer dialogs, conflict policies) — use
+   `dispatchMenuCommand` for keyboard-shortcut triggers, see `docs/testing.md` § "❌ Synthesized F-key dispatches".
+4. **Run `cargo mutants --file src/file_system/write_operations/<file>.rs`** after substantial changes — this module has
+   ~85-90% mutation score per file and shouldn't regress. See `docs/testing.md` § "Process".
+
+See also: [docs/testing.md](../../../../../../docs/testing.md) for the project-wide testing playbook.

apps/desktop/src-tauri/src/indexing/CLAUDE.md

@@ -124,6 +124,25 @@ Key test files are alongside each module (test functions within `#[cfg(test)]` b
 - stress_tests_lifecycle.rs: lifecycle stress tests — start/stop/restart under load, clean lifecycle, double-start guard, early shutdown, rapid cycles, mixed queued work shutdown
 - stress_test_helpers.rs: shared helpers for stress tests — `setup_writer`, `build_synthetic_tree`, `check_db_consistency`, `make_file_entry`
 
+### Testing bar — state machine + IndexPhase lifecycle
+
+The `IndexPhase` lifecycle (`Disabled → Initializing → Running`, plus the `Initializing → Disabled` race during cancel)
+is the trickiest backend state machine to test cleanly. Three rules for tests in this area:
+
+1. **Tests must serialize on a dedicated mutex.** `INDEXING` is a global; concurrent tests will corrupt each other.
+   Pattern in `mod.rs::tests`: dedicated mutex + `IndexStore` fixtured via `tempdir`.
+2. **`Initializing { store: IndexStore }` carries non-`Clone` owned state.** Building fixtures is verbose. Where you'd
+   like to test a pure transition without the owned data, extract a pure classifier (e.g. `is_initializing_phase`) and
+   test that in isolation. Don't pretend to mock `IndexStore`.
+3. **`start_indexing`'s `Disabled → Initializing → Running` happy path needs `tauri::AppHandle`** — currently not
+   feasible in unit tests without enabling the `tauri/test` feature (meaningful compile cost). The classifier-extraction
+   approach covers the race-decision logic; the rest stays under integration / E2E coverage.
+
+For `platform_case_compare` in `store.rs`: proptests cover the comparator algebra (reflexive / antisymmetric /
+transitive) and NFC≡NFD equivalence on macOS. Don't regress those — see `store.rs::tests` for the property statements.
+
+See also: [docs/testing.md](../../../../../../docs/testing.md) for the project-wide testing playbook.
+
 ## Key decisions
 
 **Defer indexer auto-start until the user decides about Full Disk Access**: At first launch on macOS, recursively

apps/desktop/src/lib/ipc/CLAUDE.md

@@ -167,3 +167,38 @@ Why two parallel command lists? `specta::function::collect_functions![]` doesn't
 (it only takes path expressions). The `tauri::generate_handler![]` macro does. So we use `generate_handler![]` for
 runtime dispatch (handles platform gating cleanly) and `collect_functions![]` for type collection (split by platform
 into separate fns). They're kept in sync by convention.
+
+## IPC contract testing
+
+For destructive / cross-window / multi-positional-arg commands, write a vitest IPC contract test that pins the wire
+shape. The harness is `installIpcMock()` in `test-helpers.ts`:
+
+```ts
+import { installIpcMock } from './test-helpers'
+import { commands } from './bindings'
+
+const ipc = installIpcMock()
+ipc.mock('copy_files', () => null)
+await commands.copyFiles({ sources, destination, volumeId, itemSizes, config })
+const call = ipc.lastCall('copy_files')
+expect(call?.payload).toMatchObject({ sources, destination /* ... */ })
+```
+
+What IPC tests catch:
+
+- Serde-shape drift between Rust and the typed bindings (renamed field in the Rust struct)
+- Multi-positional-arg ordering bugs (`mount_network_share` has 6 positional args — easy to swap two by accident)
+- Typed-error discriminator shape (`{ type: 'auth_required' }` vs `{ code: 'auth_required' }` etc.)
+- Whether the FE actually calls the binding (TS compiles ≠ runtime invokes)
+
+What IPC tests do **not** catch:
+
+- The Tauri permission gate (mockIPC patches `__TAURI_INTERNALS__.invoke` upstream of the gate)
+- Business-logic bugs in `*_core` / `ops_*` helpers (those should have Rust unit tests)
+- UI integration (Playwright E2E covers those)
+
+When to skip an IPC test: thin getters (`get_default_volume_id`, `has_font_metrics`) — their shape is trivial and
+already enforced by the TS bindings. **Don't write IPC tests for every command** — focus on destructive, cross-window,
+and many-arg surfaces.
+
+See `docs/testing.md` § "Decision table" for the broader picture.

docs/maintenance.md

@@ -66,6 +66,23 @@ automate it, and survives `oxfmt` (which collapses whitespace in regular markdow
 - **Pin GitHub Actions to commit SHAs**: Re-pin Actions to fresh commit SHAs when their tagged versions move.
   Supply-chain safety. Frequency: every 6 months alongside the Actions version bump.
 
+### Test-suite health
+
+- **Quarterly: mutation-testing sweep on hot-spot modules**. Run `cargo mutants` on each module listed in
+  `docs/testing.md` § "Hot spots" (write_operations, indexing, file_viewer, file_system/index/store). Triage survivors.
+  If mutation score drops below 80% on any of them, add tests to bring it back. The pass is slow (~10–15 min per file on
+  this hardware) — budget half a day. Document the run + score in the log below.
+- **Per release: E2E suite health check**. Three back-to-back `./scripts/check.sh --check desktop-e2e-playwright` runs.
+  All three must be green (no flakes). Look at the slowest 5 tests — if any have crept back to `sleep()`-based waits
+  (the lint catches new ones, but existing `eslint-disable` annotations may need re-triaging), replace with `pollUntil`.
+  Document the run + flake rate + slowest tests in the log.
+- **Per release: scan for new fixed sleeps in E2E specs**. Run
+  `grep -rE "await sleep\(" apps/desktop/test/e2e-playwright/*.spec.ts | grep -v "eslint-disable"` — should return
+  empty. If not, the new sleeps got past the lint somehow and need attention.
+- **As needed: surviving `eslint-disable cmdr/no-arbitrary-sleep-in-e2e` annotations**. ~66 of these were added during
+  the Step 6 speedup as a legacy migration tool. Each is a candidate for replacement with `pollUntil`. Picking off a few
+  per quarter shrinks the technical-debt surface without forcing a single huge cleanup.
+
 ## Log
 
 Newest-first. Tab-separated columns: `date`, `hash(es)`, `task`, `comment`.

docs/notes/extend-e2e-tests.md

@@ -603,14 +603,14 @@ Branch `e2e-speedup`, 47 commits, ready for fast-forward to `main`.
 
 ### Tests added across the push
 
-| Category                       | Tests | Bugs surfaced                                                            |
-| ------------------------------ | ----- | ------------------------------------------------------------------------ |
-| E2E coverage extension         | 9     | 1 — Cancel-copy rollback (Rust `Ok(())` arm + Svelte settle-window race) |
-| Mutation testing (Rust+Svelte) | 55    | 0                                                                        |
-| State-machine transitions      | 17    | 1 — `file_viewer` `SearchStatus::Cancelled` unobservable to FE           |
-| Property-based (proptest)      | 12    | 0                                                                        |
-| IPC contract (mockIPC)         | 23    | 0                                                                        |
-| **Total new unit / IPC tests** | **107**   |                                                                      |
+| Category                       | Tests   | Bugs surfaced                                                            |
+| ------------------------------ | ------- | ------------------------------------------------------------------------ |
+| E2E coverage extension         | 9       | 1 — Cancel-copy rollback (Rust `Ok(())` arm + Svelte settle-window race) |
+| Mutation testing (Rust+Svelte) | 55      | 0                                                                        |
+| State-machine transitions      | 17      | 1 — `file_viewer` `SearchStatus::Cancelled` unobservable to FE           |
+| Property-based (proptest)      | 12      | 0                                                                        |
+| IPC contract (mockIPC)         | 23      | 0                                                                        |
+| **Total new unit / IPC tests** | **107** |                                                                          |
 
 Plus dead code removal: `SmbVolume::ConnectionState::OsMount` variant dropped (state machine collapsed to its real
 binary `Direct ⇄ Disconnected` shape).
@@ -625,52 +625,53 @@ binary `Direct ⇄ Disconnected` shape).
 
 - **E2E checker total**: 13m 12s baseline → **4m 18s** in the final slow pass (−67%).
 - **E2E Playwright wall-clock**: 10m 12s baseline → ~1m 48s longest shard (−82%).
-- **Fast checker total**: ~2m 30s baseline → **3m 13s** (+43s) — the regression is the new IPC contract tests
-  (+30s of Svelte vitest) and the +79 Rust tests (+1s). Net cost is well below what an equivalent E2E spec would add.
+- **Fast checker total**: ~2m 30s baseline → **3m 13s** (+43s) — the regression is the new IPC contract tests (+30s of
+  Svelte vitest) and the +79 Rust tests (+1s). Net cost is well below what an equivalent E2E spec would add.
 
 ### Real bugs fixed
 
-1. **file_viewer search-cancel was unobservable to the FE.** `search_cancel` nulled `session.search` immediately,
-   so the spawned thread's `SearchStatus::Cancelled` write was clobbered before the FE could see it. The FE
-   couldn't distinguish "search completed naturally with zero matches" from "search was cancelled mid-flight."
-   Fix: stop nulling on cancel; let the thread write `Cancelled` and the next `search_start` replaces it.
+1. **file_viewer search-cancel was unobservable to the FE.** `search_cancel` nulled `session.search` immediately, so the
+   spawned thread's `SearchStatus::Cancelled` write was clobbered before the FE could see it. The FE couldn't
+   distinguish "search completed naturally with zero matches" from "search was cancelled mid-flight." Fix: stop nulling
+   on cancel; let the thread write `Cancelled` and the next `search_start` replaces it.
 2. **Cancel-copy mid-operation rollback was lost on fast filesystems.** The Rust `Ok(())` arm in
-   `copy_files_with_progress` didn't check `OperationIntent` before committing the transaction, so a click during
-   the < 1 µs window between the last `is_cancelled` poll and loop exit landed as a no-op. Plus the Svelte
-   `TransferProgressDialog` left the Rollback button enabled during the `MIN_DISPLAY_MS = 400 ms` settle window
-   after `write-complete`, so clicks during settle were silent no-ops. Both fixed in Step 6d.
+   `copy_files_with_progress` didn't check `OperationIntent` before committing the transaction, so a click during the <
+   1 µs window between the last `is_cancelled` poll and loop exit landed as a no-op. Plus the Svelte
+   `TransferProgressDialog` left the Rollback button enabled during the `MIN_DISPLAY_MS = 400 ms` settle window after
+   `write-complete`, so clicks during settle were silent no-ops. Both fixed in Step 6d.
 
 ### Dead code removed
 
-- `SmbVolume::ConnectionState::OsMount` variant — never written to the atomic, two unreachable `match` arms gone.
-  The OS-mount fallback the UI renders lives at the outer `SmbConnectionState` enriched by `enrich_smb_connection_state`
-  in `commands/volumes.rs`, not on this internal atomic.
+- `SmbVolume::ConnectionState::OsMount` variant — never written to the atomic, two unreachable `match` arms gone. The
+  OS-mount fallback the UI renders lives at the outer `SmbConnectionState` enriched by `enrich_smb_connection_state` in
+  `commands/volumes.rs`, not on this internal atomic.
 
 ### Honest verdict per technique
 
-- **Mutation testing (cargo-mutants + stryker)**: zero bugs, 55 tests added. Tools work but are too slow / noisy for
-  CI gating. Worth ad-hoc runs on numeric / state-machine modules. Don't wire into `check.sh`.
-- **State-machine coverage**: 17 tests, 1 real bug (file_viewer search-cancel). Highest signal-to-noise of the test-quality push — the bug was a real silent UX failure, surfaced by writing the transition test.
+- **Mutation testing (cargo-mutants + stryker)**: zero bugs, 55 tests added. Tools work but are too slow / noisy for CI
+  gating. Worth ad-hoc runs on numeric / state-machine modules. Don't wire into `check.sh`.
+- **State-machine coverage**: 17 tests, 1 real bug (file_viewer search-cancel). Highest signal-to-noise of the
+  test-quality push — the bug was a real silent UX failure, surfaced by writing the transition test.
 - **Property-based (proptest)**: 12 tests, 0 bugs. `proptest` added as a dev-dep, scoped to four targets
-  (`topological_sort_bottom_up`, `glob_to_regex`, `split_scope_segments`, `platform_case_compare`). Worth keeping
-  for those specific algorithmic spots; not worth a project-wide convention.
+  (`topological_sort_bottom_up`, `glob_to_regex`, `split_scope_segments`, `platform_case_compare`). Worth keeping for
+  those specific algorithmic spots; not worth a project-wide convention.
 - **IPC contract tests (vitest mockIPC)**: 23 tests, 0 bugs. Modest value — `bindings-fresh` + `no-raw-tauri-invoke`
   already cover most drift. Worth doing for destructive / cross-window surfaces (write ops, viewer, SMB); diminishing
   returns past that.
-- **E2E coverage extension**: 9 tests, 1 real bug (cancel-copy rollback). Surfaced by walking the slowest test
-  (32.7 s) in the post-Step-1 report.
+- **E2E coverage extension**: 9 tests, 1 real bug (cancel-copy rollback). Surfaced by walking the slowest test (32.7 s)
+  in the post-Step-1 report.
 
 ### Outstanding items
 
 - **Linux SMB flakes**: `50-share host shows correct share count` and `unicode shares render correctly` — flake under
   GVFS race in Docker. Pre-existing, David is aware. Not addressed in this branch.
 - **Step 6a parallel-load keystroke-dispatch flakes**: rarely surface on warm runs; Step 6e converted the worst
   offenders to `dispatchMenuCommand`. Three remaining keyboard-pathway tests can flake under heavy parallel load
-  (~1-in-N runs). The Step 6a fix-suggestions list (data-app-ready route-change reset, focus re-issue after click)
-  is a candidate for a follow-up but wasn't load-bearing here.
+  (~1-in-N runs). The Step 6a fix-suggestions list (data-app-ready route-change reset, focus re-issue after click) is a
+  candidate for a follow-up but wasn't load-bearing here.
 
 ### Final validation
 
 - `./scripts/check.sh` (fast pass): **green in 3m 13s**, 1728 Rust + 1812 Svelte tests pass.
-- `./scripts/check.sh --only-slow`: **green except the two pre-existing Linux SMB flakes**. E2E Playwright
-  131/131 in 4m 18s across 3 shards; rust-tests-linux 1699/1699; eslint-typecheck 453/453.
+- `./scripts/check.sh --only-slow`: **green except the two pre-existing Linux SMB flakes**. E2E Playwright 131/131 in 4m
+  18s across 3 shards; rust-tests-linux 1699/1699; eslint-typecheck 453/453.