docs: document the unit-test layer and add a make test-unit target

The README only covered the VM integration harness. The unit suites under tests/ (one directory per script, fake binaries on PATH) went unmentioned, so a contributor adding a .local/bin script had no way to know they existed or how to run them.

I added a make test-unit target that runs every tests/*/test_*.py suite explicitly. unittest discover can't find them because the per-script directory names are hyphenated and aren't valid package paths. Then I split the README Testing section into Unit and VM-integration layers, added a guide for adding a suite, and pointed Contributing at test-unit for script changes.

1 files changed, 23 insertions, 1 deletions

diff --git a/README.md b/README.md
index 80f80cb..18b2b86 100644
--- a/README.md
+++ b/README.md
@@ -143,6 +143,28 @@ Pick the desktop env at install time with `DESKTOP_ENV` in the config file (or a
 
 ## Testing
 
+archsetup has two test layers: fast unit tests for the standalone helper scripts, and a full VM-based integration test for the installer itself.
+
+### Unit tests
+
+The helper scripts under `dotfiles/*/.local/bin/` that shell out to other tools (`tmux`, `hyprctl`) have Python `unittest` suites under `tests/`, one directory per script. Each suite runs the real script with fake binaries placed on `PATH` — the fakes serve canned state and log every call, so the tests assert on behavior (what the script tells `tmux`/`hyprctl` to do) rather than implementation. No VM, root, or network needed; the whole set runs in under a second.
+
+```sh
+make test-unit         # Run every unit suite
+```
+
+To run a single suite directly:
+
+```sh
+python3 -m unittest tests.tmux-util.test_tmux_util
+```
+
+(`unittest discover` skips these because the per-script directory names are hyphenated, so `make test-unit` runs each suite explicitly.)
+
+**Adding a suite for a new script.** Create `tests/<script-name>/`, add a `fake-<tool>` executable for each external command the script calls (have it read canned state and append a line to a call log), then write `test_<script_name>.py` driving the real script with those fakes on `PATH`. Mirror the existing `tests/tmux-util/` layout. `make test-unit` picks up any `tests/*/test_*.py` automatically.
+
+### Integration tests (VM harness)
+
 archsetup ships a VM-based integration test harness under `scripts/testing/`. It uses QEMU/KVM directly (no libvirt) to install Arch into a throwaway VM, run `archsetup` inside it, and validate the result: user creation, stowed dotfiles, AUR helper, desktop environment, services, firewall, and package set.
 
 ```sh
@@ -156,7 +178,7 @@ Results land in `test-results/<timestamp>/` (logs, a summary report, and package
 
 ## Contributing
 
-This is a personal setup, but bug reports and pull requests are welcome, especially fixes that make it easier to fork. If you're sending a change, keep the `common` / `dwm` / `hyprland` dotfile split intact and run `make test` (or at least `bash -n archsetup`) before opening a PR.
+This is a personal setup, but bug reports and pull requests are welcome, especially fixes that make it easier to fork. If you're sending a change, keep the `common` / `dwm` / `hyprland` dotfile split intact. Run `make test-unit` for any script change (it's fast and needs no VM), and `make test` for installer changes (or at least `bash -n archsetup`) before opening a PR.
 
 ## License