From 2172c904e34e044ba938d5a4948182d9fd878816 Mon Sep 17 00:00:00 2001 From: Craig Jennings 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. --- README.md | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) (limited to 'README.md') 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//`, add a `fake-` executable for each external command the script calls (have it read canned state and append a line to a call log), then write `test_.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//` (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