| name | hypeman-remote-linux-tests |
| description | Run Hypeman tests on a remote Linux host that supports the Linux hypervisors. Use when validating cloud-hypervisor, Firecracker, QEMU, embedded guest artifacts, or Linux-only integration behavior on a server over SSH. |
Hypeman Remote Linux Tests
Use this skill to run Hypeman tests on a remote Linux server in a way that is repeatable and low-friction for any developer.
Quick Start
- Pick a short remote working directory under the remote user's home directory.
- Ensure the remote test shell includes
/usr/sbin and /sbin on PATH.
- Bootstrap embedded artifacts and bundled binaries before running
go test.
- Run the smallest relevant test target first.
- Treat host-environment failures separately from product failures.
Remote Workspace
Prefer a short path such as ~/hm, ~/hypeman-test, or another short directory name.
Cloud Hypervisor uses UNIX sockets with strict path-length limits. Long paths from default test temp directories or deeply nested clones can make the VMM fail before the actual test starts.
If a new test creates temporary directories for guest data, prefer a short root like:
mktemp -d /tmp/hmcmp-XXXXXX
Remote Bootstrap
Before running Linux hypervisor tests, make sure the remote clone has the generated guest binaries and embedded VMM assets:
export PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH
make ensure-ch-binaries ensure-firecracker-binaries ensure-caddy-binaries build-embedded
Why:
go:embed patterns in the repo require the bundled binaries to exist at build time.mkfs.ext4 is commonly installed in /usr/sbin or /sbin, not always on the default non-login shell PATH.- Running
go test before this bootstrap often fails during package setup, not during test execution.
QEMU is usually provided by the host OS, so there is no matching bundled ensure-qemu-binaries target. If QEMU tests fail before boot, verify the system qemu-system-* binary separately.
Syncing Local Changes
If the main development is happening locally and the Linux host is only for execution, sync only the files you changed rather than recloning every time.
Typical pattern:
rsync -az lib/instances/... remote-host:~/hypeman-test/lib/instances/
After syncing, re-run the bootstrap command if the changes affect embedded binaries, generated assets, or files referenced by go:embed.
Common Host Failures
Classify failures quickly:
- Missing embedded assets:
- symptom: package setup fails with
pattern ... no matching files found
- fix: run
make ensure-ch-binaries ensure-firecracker-binaries ensure-caddy-binaries build-embedded
mkfs.ext4 not found:
- symptom: overlay or disk creation fails with
exec: "mkfs.ext4": executable file not found
- fix: add
/usr/sbin:/sbin to PATH, then retry
- Cloud Hypervisor socket path too long:
- symptom:
path must be shorter than SUN_LEN
- fix: shorten the remote repo path and any temp/data directories used by the test
/tmp or shared test-lock issues:
- symptom: test-specific lock or temp-file permission failures
- fix: prefer no-network test setup when the test does not require networking; avoid unnecessary shared lock files
