hypeman-remote-linux-tests

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 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

1. Pick a short remote working directory under the remote user's home directory.
2. Ensure the remote test shell includes `/usr/sbin` and `/sbin` on `PATH`.
3. Bootstrap embedded artifacts and bundled binaries before running `go test`.
4. Run the smallest relevant test target first.
5. 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:

```bash
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:

```bash
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:

```bash
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

From kernel/hypeman, MIT.

More from kernel/hypeman