phoebus_os/installer/tests/vm
Phoebus 34c12d3dd8 feat(installer): rebuild the graphical journey and fix interaction defects
Rework the graphical installer into a fixed first-time-user sequence
(Welcome, Language and keyboard, Internet and readiness, AI connection,
Destination disk, Account and encryption, Review and confirmation,
Installation, Completion) with configuration, validation, plans, approval
and execution still authoritative in Rust.

Fix the audited interaction defects: readiness `Re-check` is a read-only
probe that no longer resets the step or clears the disk; model catalogs are
fetched after syncing the edited settings and credentials and stale replies
are ignored; editing a connection field invalidates the validated state;
suggestion lists support arrow/Enter/Escape with a visible highlight and
accessibility; the keyboard step labels the live-session limitation
truthfully; readiness separates the local link from reachable install
services; and busy states always clear, with the bridge failing outstanding
requests when the backend exits.

Add human-readable language/keyboard names, an explicit AI change review
(Accept/Discard), backend-fact review with edit links, real stage progress
with elapsed time and activity, and clearer failure and completion guidance.

Extend the VM harness with a `gui-install` mode that drives the whole
journey through the visible controls, plus regressions for readiness
refresh, disk survival, keyboard suggestion selection and AI invalidation.
Add Rust tests for readiness, the network probe, error kinds and labels.
2026-09-22 08:17:03 -07:00
..
appliance-driver.py test(vm): enforce harness disk safety and structured results 2026-09-21 20:01:50 -07:00
appliance-guest-gui.sh feat(installer): graphical welcome and install wizard over a typed bridge 2026-09-21 13:13:40 -07:00
appliance-guest.sh feat(desktop): add Mango + DankMaterialShell profile with rollback, assistant and release foundations 2026-09-21 03:46:52 -07:00
appliance-test.conf.example feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
gui-driver.py feat(installer): rebuild the graphical journey and fix interaction defects 2026-09-22 08:17:03 -07:00
install.sh test(vm): drive the static Rust installer from the VM harness 2026-09-20 03:02:37 -07:00
live-driver.py feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
oc-forward.py test(gui): drive the OpenCode AI step through the real UI 2026-09-22 03:32:07 -07:00
README.md test(vm): enforce harness disk safety and structured results 2026-09-21 20:01:50 -07:00
report.py test(vm): enforce harness disk safety and structured results 2026-09-21 20:01:50 -07:00
run-vm.sh test(vm): drive the static Rust installer from the VM harness 2026-09-20 03:02:37 -07:00
serial-driver.py test(vm): enforce harness disk safety and structured results 2026-09-21 20:01:50 -07:00
test.conf.example feat(desktop): make Mango + DankMaterialShell the default and build a live desktop ISO 2026-09-21 06:47:22 -07:00
test_vmsafety.py test(vm): enforce harness disk safety and structured results 2026-09-21 20:01:50 -07:00
vmsafety.py test(vm): enforce harness disk safety and structured results 2026-09-21 20:01:50 -07:00

Disposable UEFI VM harness

Proves that the installer produces a bootable encrypted system without ever touching a physical disk. The target is always a qcow2 file.

Files

  • run-vm.sh interactive QEMU launcher (manual testing).
  • install.sh guest-side, non-interactive installation (run in the VM).
  • serial-driver.py host-side pexpect driver (install and boot modes).
  • test.conf.example installer configuration used by the driver.

Host prerequisites

  • qemu-system-x86_64, qemu-img, OVMF firmware, Python pexpect.
  • The reference Gentoo ISO.
  • The static Rust installer (the guest never runs the Bash tree):
cd installer-rs
RUSTFLAGS="-C target-feature=+crt-static" \
  cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu

Procedure

Serve the static installer, the stage3 and the config to the guest:

cd /path/to/serve
cp /path/to/phoebus_os/installer-rs/target/x86_64-unknown-linux-gnu/release/phoebus-installer .
cp /path/to/phoebus_os/installer/tests/vm/install.sh .
cp /path/to/phoebus_os/installer/tests/vm/test.conf.example test.conf  # edit TARGET_DISK etc.
sha256sum stage3.tar.xz                               # set STAGE3_SHA256
python3 -m http.server 8000 --bind 127.0.0.1

Run the installation (driver boots the ISO kernel/initrd directly and drives the serial console):

QEMU_BIN=/path/to/qemu-system-x86_64 \
QEMU_LIBDIR=/path/to/qemu/libs \
QEMU_DATADIR=/path/to/qemu/share \
OVMF_CODE=/path/to/OVMF_CODE_4M.fd \
OVMF_VARS=/path/to/OVMF_VARS.fd \
DISK=/tmp/phoebus/target.qcow2 \
ISO=/path/to/livegui-amd64.iso \
KERNEL=/tmp/live/boot/gentoo INITRD=/tmp/live/boot/gentoo.igz \
INSTALL_URL=http://10.0.2.2:8000/install.sh \
python3 installer/tests/vm/serial-driver.py install

Then boot the disk alone (ISO detached) and verify:

DISK=/tmp/phoebus/target.qcow2 OVMF_CODE=... OVMF_VARS=... \
python3 installer/tests/vm/serial-driver.py boot

To patch a console into an existing entry for observation, the BLS entry in /efi/loader/entries/*.conf takes an options line; the installer can also embed a console via KERNEL_CONSOLE (GENTOO_KERNEL_CONSOLE equivalent).

Safety (enforced, not just documented)

vmsafety.py validates every writable drive before QEMU starts:

  • DISK/DISKS must name qcow2 files inside the disposable directory PHOEBUS_VM_DISKS (default $PHOEBUS_VM_STATE/disks).
  • /dev/* paths, block and character devices, non-regular files, raw images, symlinks that resolve outside the directory, and disks whose backing chain reaches outside it are refused with a nonzero exit.
  • Each run gets a private state directory (mode 0700), its own writable OVMF variable file and a unique QMP monitor socket.
  • Screenshots use structured QMP and argument arrays; there is no shell interpolation (os.system) in the harness.
  • Secrets are passed through 0600 files and checked for leakage in the installer log by the guest script.

Results

Every driver writes results.json (and a screenshot-manifest.json for the GUI driver) under its run directory and exits nonzero on any FAIL (and, with PHOEBUS_VM_STRICT=1, on BLOCKED/NOT RUN). Statuses are PASS, FAIL, BLOCKED, SKIPPED and NOT RUN; a timeout is always a FAIL, never a pass.

make test-vm          # unit-test the safety and result logic (no VM needed)
PHOEBUS_VM_DISKS=/var/tmp/phoebus-vm/disks \
OVMF_CODE=/usr/share/OVMF/OVMF_CODE_4M.fd \
OVMF_VARS=/usr/share/OVMF/OVMF_VARS_4M.fd \
DISK=/var/tmp/phoebus-vm/disks/target.qcow2 \
ISO=installer/live/phoebus-installer-amd64.iso \
python3 installer/tests/vm/gui-driver.py gui