From 2172c904e34e044ba938d5a4948182d9fd878816 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Wed, 20 May 2026 12:02:47 -0500
Subject: 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.
---
 Makefile  | 15 ++++++++++++++-
 README.md | 24 +++++++++++++++++++++++-
 2 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/Makefile b/Makefile
index 31c258e..9945126 100644
--- a/Makefile
+++ b/Makefile
@@ -10,7 +10,7 @@ DE := $(filter dwm hyprland,$(MAKECMDGOALS))
 # Extract DEST from command line for import (e.g., 'make import common' -> DEST=common)
 DEST := $(filter common dwm hyprland,$(MAKECMDGOALS))
 
-.PHONY: help deps stow restow reset unstow import test test-keep test-vm-base common dwm hyprland
+.PHONY: help deps stow restow reset unstow import test-unit test test-keep test-vm-base common dwm hyprland
 
 # Default target - show help
 help:
@@ -30,6 +30,7 @@ help:
 	@echo "  reset      Resolve conflicts, keep repo version - requires DE"
 	@echo "  unstow     Remove all symlinks - requires DE"
 	@echo "  import     Import new app configs into repo (fzf) - requires dest"
+	@echo "  test-unit  Run fast unit tests for scripts (no VM needed)"
 	@echo "  test       Run full VM test suite (creates base VM if needed)"
 	@echo "  test-keep  Run test and keep VM running for manual testing"
 	@echo "  test-vm-base  Create base VM only (runs archangel)"
@@ -161,6 +162,18 @@ import: check-dest
 	echo ""; \
 	echo "Done. Don't forget to: git add -A && git commit"
 
+# Run the fast unit-test suites for individual scripts (no VM needed).
+# One suite per tests/<script>/ dir; `unittest discover` can't find them
+# because the dir names are hyphenated, so each suite is run explicitly.
+test-unit:
+	@fail=0; \
+	for t in tests/*/test_*.py; do \
+		mod=$$(echo "$$t" | sed 's|/|.|g; s|\.py$$||'); \
+		echo "==> $$mod"; \
+		python3 -m unittest "$$mod" || fail=1; \
+	done; \
+	exit $$fail
+
 # Create base VM for testing (runs archangel only, no archsetup)
 test-vm-base:
 	@bash scripts/testing/create-base-vm.sh
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
 
-- 
cgit v1.2.3