testing harness, coredesktop-dev

skills/coredesktop-dev-sibling.md

@@ -77,7 +77,8 @@ coredesktop-dev/
   update.sh             run on every `update`
   bin/coredesktop-dev   the command (symlinked into ~/.local/bin)
   hooks/pre-push        git hook for the working copy (opt-in)
-  lib/                  shared functions, if bin/ grows large
+  lib/                  one file per subcommand, plus common.sh and vm.sh
+  vm/                   provision.sh and cloud-init user-data for the smoketest VM
   tests/                bats tests for this project
   Makefile              `make check`: shellcheck + bats for this repo
   .shellcheckrc         copy CoreDesktop's
@@ -95,6 +96,8 @@ added later reach existing machines on their next `update`. All are in Arch's
 | `shellcheck` | `make lint` |
 | `bats` | `make test` (CoreDesktop's tests use plain bats, no helper libraries) |
 | `tea` | Gitea's CLI, for pull requests on gitea.federated.computer |
+| `qemu-base` | The smoketest's virtual machines |
+| `libisoburn` | `xorriso`, to make the smoketest VM's cloud-init disk |
 
 `make`, `git` and `jq` already come with CoreDesktop. Don't add `shfmt` until
 CoreDesktop decides on a formatting style; it has no config for it today.
@@ -134,7 +137,7 @@ default answer.
 
 No prompts. It prints what it does and exits non-zero only on real failure:
 
-1. `install_packages shellcheck bats tea`
+1. `install_packages shellcheck bats tea qemu-base libisoburn`
 2. Make `~/.local/bin/coredesktop-dev` a symlink to `bin/coredesktop-dev` in
    this repo, so each pull updates the command without copying.
 3. If the pre-push hook is installed in the working copy, refresh it from
@@ -222,6 +225,26 @@ Installs `hooks/pre-push` into the working copy's `.git/hooks/pre-push`. The
 overwrite a pre-push hook that this project didn't write: write a marker
 comment into the hook and check for it.
 
+#### `coredesktop-dev smoketest`
+
+Runs CoreDesktop's end-to-end scenarios on QEMU virtual machines. The
+scenarios, the fingerprint and health scripts, and the helpers they use live
+in CoreDesktop's `smoketest/` folder, because they change with the code they
+test; read its README for the contract between them and this driver. This
+project only provides the VMs: `vm_exec`, `vm_put`, `vm_reboot`, `VM_GIT_SSH`
+and `VM_GIT_URL`, then calls `smoketest_prepare` and the scenario.
+
+- `list`, `run [--tier pr|all] [--ref REF] [--keep] [scenario...]`,
+  `images [base|installed [REF]]`, `shell [base|installed]`, `clean [--all]`.
+- Images, the shared pacman cache, the SSH key and run logs live in
+  `~/.cache/coredesktop-dev/smoketest`, never in either copy of CoreDesktop.
+- **base** is Arch's cloud image plus archinstall's GNOME desktop profile
+  (`vm/provision.sh`), with automatic login and passwordless sudo for `tester`.
+  **installed** is base after `install.sh` at the commit the branch started
+  from. Each scenario runs on a throwaway qcow2 overlay of one of them.
+- Commands in the VM run in an interactive bash with the GNOME session's
+  environment, as they would in GNOME Terminal.
+
 ### What not to do
 
 - Don't copy hooks into CoreDesktop's `updates.d/`: use `update.sh`, as the
@@ -278,9 +301,10 @@ Cases worth a test each:
 - [ ] The repo's README says to install with `sibling add <url>`
 - [ ] `install.sh` asks for the working copy, refuses the deployed copy,
       saves `~/.config/coredesktop-dev/config`, and is safe to re-run
-- [ ] `update.sh` installs shellcheck, bats and tea, keeps the
+- [ ] `update.sh` installs shellcheck, bats, tea, QEMU and xorriso, keeps the
       `~/.local/bin/coredesktop-dev` symlink, and never prompts
-- [ ] `doctor`, `check`, `try`, `deployed` and `hooks` work and have `--help`
+- [ ] `doctor`, `check`, `try`, `deployed`, `hooks` and `smoketest` work and
+      have `--help`
 - [ ] `check` lints untracked scripts in the working copy
 - [ ] `try` isolates `HOME`, `XDG_*` and `XDG_RUNTIME_DIR`, unsets the
       display and session variables, uses `dbus-run-session`, and warns that