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

67 lines
2.3 KiB
Bash

# 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)
```sh
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
```sh
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.
## 3. Full VM test (recommended before release)
`tests/vm/run-vm.sh` boots the reference ISO with a **disposable** qcow2 disk:
```sh
# 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.