commit 9ab9fcdd09a58c8ab456297248205a6057c0e064
parent 17f56429aeb5c07172994fb0196291b626d462d5
Author: Matthew Gantenbein <ganten1998@gmail.com>
Date: Sun, 31 May 2026 17:20:58 -0500
docs: TESTING.md — verified-vs-user-gated test guide
Lays out the three test stages (tap→speakers needs only TCC; driver install
needs sudo; agent/widget optional) with exact commands, and what's already
verified headlessly vs. what needs a GUI prompt / sudo / coreaudiod restart.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Diffstat:
| A | TESTING.md | | | 72 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 72 insertions(+), 0 deletions(-)
diff --git a/TESTING.md b/TESTING.md
@@ -0,0 +1,72 @@
+# Testing Hydra
+
+What's been built and verified vs. what needs you (the parts requiring a GUI permission
+dialog, `sudo`, or a `coreaudiod` restart can't be done headlessly).
+
+## Already verified (no action needed)
+
+- `cargo build --workspace` — clean, 0 warnings
+- `cargo test --workspace` — 19 tests green (wire round-trips, model, theme, manifest, config)
+- Device + audio-process **enumeration** against your real hardware (Scarlett 18i20,
+ built-ins, even the running Loopback Virtual Mic)
+- `hydra query --sketchybar|--json|plain` over the live socket
+- Config **persistence** round-trip (daemon restores saved routes on startup)
+- `Hydra.driver` **builds + signs** (universal, factory symbol exported)
+- `Hydra.app` **builds + signs** with the audio-input entitlement
+
+## 1. Per-app capture → speakers (no driver, no sudo — start here)
+
+This is the lowest-risk check: confirms the tap engine + TCC actually work.
+
+```sh
+cd ~/Dropbox/Projects/Apps/hydra
+./scripts/bundle.sh debug # build + ad-hoc-sign Hydra.app
+open -a Music # or any app; start playback
+"./dist/Hydra.app/Contents/MacOS/hydrad" & # run the SIGNED daemon (not `cargo run` — TCC needs the bundle)
+cargo run -p hydra # TUI: pick the app, ensure target = "MacBook Pro Speakers" (press o), ⏎
+```
+
+- macOS should prompt for **Audio Recording** access the first time — approve it.
+- Expect: you hear the app through speakers, and the route's peak meter moves.
+- If no prompt appears or the meter stays flat: that's the signing/TCC gate — tell me and
+ I'll dig in (likely needs a free Apple Development cert instead of ad-hoc).
+
+Stop the daemon when done: `pkill -f Hydra.app`.
+
+## 2. The virtual device (driver install — sudo + ~1s audio glitch)
+
+Makes "Hydra" selectable as an input in other apps (Zoom/OBS/etc). Loopback can stay
+installed — no conflict.
+
+```sh
+./scripts/build-driver.sh # → driver/build/Hydra.driver (already verified to build)
+./scripts/install-driver.sh # prompts for sudo; restarts coreaudiod
+system_profiler SPAudioDataType | grep -i hydra # confirm "Hydra" appears
+```
+
+Then in the TUI: pick an app, press `o` until the target is **Hydra**, `⏎`. In another app,
+choose **Hydra** as the microphone — it should receive the routed audio.
+
+Uninstall any time:
+```sh
+sudo rm -rf "/Library/Audio/Plug-Ins/HAL/Hydra.driver" && sudo launchctl kickstart -k system/com.apple.audio.coreaudiod
+```
+
+## 3. Run as a background agent (optional)
+
+```sh
+./scripts/install-agent.sh # KeepAlive LaunchAgent; routing persists across logins
+tail -f /tmp/hydrad.err.log
+```
+
+## 4. SketchyBar widget (optional)
+
+See `scripts/sketchybar/README.md` — add the item to your `sketchybarrc` (remember:
+first-added = rightmost).
+
+## What I still owe, once the driver's installed
+
+- **P3**: runtime-dynamic devices (rename, arbitrary channel counts, multiple devices) via
+ the `devices.json` manifest reader in the driver. Needs the driver installed to test, so
+ it was deferred to after step 2.
+- **P6**: live driver reload without a coreaudiod restart; long-session tap stability.
