phoebus_os/installer/doc/TESTING.md
Phoebus 38214ea9e7 chore: import Phoebus OS installer and Rust migration
Initial public import of the proven Bash installer (installer/) and the production Rust workspace (installer-rs/). The reference ISO, build output and local agent transcripts are gitignored.

Verified: installer/tests/run_tests.sh and cargo test --workspace both pass.
2026-09-20 02:07:33 -07:00

2.3 KiB

Testing the installer safely

Never test destructive paths on a real machine. There are three levels, from cheapest to most realistic.

1. Unit tests (no root, no disks)

installer/tests/run_tests.sh

These cover configuration state, validation, plan generation, package policy, OpenCode checksum verification, AI proposal parsing/whitelisting, the destructive authorization gate, and the dry-run storage/sandbox behaviour. They run on any Linux machine with Bash 4+; the development host has neither dialog nor any Portage tooling, which is exactly the point.

2. Dry-run

installer/bin/ai-installer --dry-run --config my.conf
# or, without the TUI:
installer/bin/ai-installer --dry-run --config my.conf --plan

In dry-run mode:

  • run_cmd logs every command as [dry-run] and executes nothing;
  • the target root becomes $STATE_DIR/dry-run-root, so even file generation cannot touch the host;
  • install_preflight still refuses incomplete or unsafe configurations.

tests/vm/run-vm.sh boots the reference ISO with a disposable qcow2 disk:

# defaults: 32 GiB disk, 4 GiB RAM, 4 CPUs, UEFI (OVMF)
installer/tests/vm/run-vm.sh --iso /path/to/livegui-amd64.iso

# see all options
installer/tests/vm/run-vm.sh --help

Inside the VM:

  1. Boot the live medium and get a shell.
  2. Copy or mount the installer/ tree into the VM.
  3. Run bin/ai-installer.
  4. Select the virtio disk (/dev/vda) as the target. The ISO device is protected and will not be offered.
  5. Complete the review, type ERASE, and install.
  6. Reboot the VM from the disk (-boot c) to verify UEFI boot, LUKS unlock and the login.

The script keeps the disk image in a working directory you choose, so a test can be discarded by deleting that directory. It never touches host disks and uses QEMU user-mode networking by default.

Additional checks

  • bash -n over every script is part of the unit suite (test_syntax.sh).
  • shellcheck is optional and not required; several modules use constructs that trip naive shellcheck rules, so treat its output as advisory.
  • To exercise the backend without a VM, point --config at a file with TARGET_DISK unset and use --plan; the safety tests already cover the sandbox and authorization logic.