phoebus_os/installer/tests/vm/gui-driver.py
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

1256 lines
54 KiB
Bash

#!/usr/bin/env python3
"""Headless driver for the Phoebus graphical live/installer ISO.
The live medium boots into Mango + DankMaterialShell and opens the branded
welcome window. This driver boots it with a graphical device and a serial
console, checks the launcher/branding payload, drives the graphical installer
over the live session, and captures QEMU framebuffer screenshots through QMP.
Modes:
gui : boot, log in on serial, verify the welcome/branding payload, open
the installer from the welcome action, prove duplicate prevention,
walk the wizard steps and capture screenshots.
opencode: drive the OpenCode AI step through the real graphical UI and
validate a model response and proposal.
gui-install: complete a full installation through the visible wizard (AI
connection, disk, account, ERASE, install) on a disposable disk.
install : boot, log in on serial, fetch a non-interactive config and 0600
secrets over QEMU user networking, run the deterministic install
with the static binary, scan the log for a secret leak, power off.
boot : boot the installed disk alone (no ISO), unlock LUKS, log in and run
verification commands.
Safety: every writable drive must be a qcow2 file inside the disposable
directory named by `PHOEBUS_VM_DISKS` (default
`$PHOEBUS_VM_STATE/disks`). The driver refuses block devices, `/dev/*`,
symlinks that escape the directory, raw images and images with an outside
backing chain. Each run gets its own private state directory, a fresh writable
OVMF variable file and a unique QMP monitor socket. Results are structured and
the process exits nonzero on any failed assertion, timeout, unexpected EOF or
missing result.
"""
from __future__ import annotations
import json
import os
import re
import shutil
import sys
import time
from pathlib import Path
import pexpect
import vmsafety
from vmsafety import BLOCKED, FAIL, PASS, Results, HarnessError
QEMU = os.environ.get("QEMU_BIN", "qemu-system-x86_64")
OVMF_CODE = os.environ["OVMF_CODE"]
OVMF_VARS_TEMPLATE = os.environ["OVMF_VARS"]
ISO = os.environ.get("ISO", "")
DISKS = os.environ.get("DISKS") or os.environ.get("DISK", "")
SERVE_URL = os.environ.get("SERVE_URL", "http://10.0.2.2:8000")
LIVE_USER = os.environ.get("LIVE_USER", "phoebus")
LIVE_PW = os.environ.get("LIVE_PASSWORD", "phoebus")
USER = os.environ.get("USERNAME", "phoebus")
USER_PW = os.environ.get("USER_PASSWORD", "phoebus-user-test")
LUKS_PW = os.environ.get("LUKS_PASSPHRASE", "phoebus-luks-test")
MEM = os.environ.get("VM_MEM", "8192")
SMP = os.environ.get("VM_SMP", "8")
BOOT_TIMEOUT = int(os.environ.get("BOOT_TIMEOUT", "900"))
INSTALL_TIMEOUT = int(os.environ.get("INSTALL_TIMEOUT", "10800"))
SESSION_SETTLE = int(os.environ.get("SESSION_SETTLE", "20"))
BACKEND_SETTLE = int(os.environ.get("BACKEND_SETTLE", "30"))
# OpenCode GUI-driving knobs (test-only). The wizard focuses the first AI
# provider chip when the AI step opens, so three Tabs reach the OpenCode chip.
# After selecting it, the field order is server, password (with a keyboard
# reveal control), provider, model, load, Test, Connect.
OC_PORT = int(os.environ.get("OC_PORT", "4096"))
OC_TARGET_PORT = int(os.environ.get("OC_TARGET_PORT", "41999"))
OC_TAB_TO_CHIP = int(os.environ.get("OC_TAB_TO_CHIP", "3"))
OC_PROVIDER = os.environ.get("OC_PROVIDER", "deepseek")
OC_MODEL = os.environ.get("OC_MODEL", "deepseek-v4-flash")
OC_USE_PASSWORD = os.environ.get("OC_USE_PASSWORD", "0") in ("1", "yes", "true")
def _template_dir() -> Path:
return Path(
os.environ.get("PHOEBUS_VM_STATE", "/var/tmp/phoebus-vm")
)
def _disposable_dir() -> Path:
return Path(os.environ.get("PHOEBUS_VM_DISKS", str(_template_dir() / "disks")))
class Driver:
def __init__(self, mode: str):
self.mode = mode
self.results = Results(f"gui-{mode}")
self.paths = vmsafety.make_run_paths(
f"gui-{mode}", base=_template_dir(), ovmf_vars_template=OVMF_VARS_TEMPLATE
)
self.manifest: list[dict] = []
self.seq = 0
self.child: pexpect.spawn | None = None
self.log = None
self.spawned = False
self.disks: list[Path] = []
self.boot_disk = False
self._prepare()
# -- setup -------------------------------------------------------------
def _prepare(self) -> None:
if not Path(QEMU).exists() and shutil.which(QEMU) is None:
raise HarnessError(f"QEMU binary not found: {QEMU}")
if DISKS:
try:
self.disks = vmsafety.validate_writable_drives(
DISKS.split(","), _disposable_dir()
)
except vmsafety.UnsafeDiskError as exc:
raise HarnessError(str(exc)) from exc
if ISO:
iso = Path(ISO)
if not iso.is_file():
raise HarnessError(f"ISO is not a regular file: {iso}")
if not Path(OVMF_CODE).is_file():
raise HarnessError(f"OVMF_CODE is not a file: {OVMF_CODE}")
if not Path(OVMF_VARS_TEMPLATE).is_file():
raise HarnessError(f"OVMF_VARS template is not a file: {OVMF_VARS_TEMPLATE}")
# -- qemu --------------------------------------------------------------
def qemu_args(self, attach_iso: bool, boot_disk: bool) -> list[str]:
args = [
"-machine", "q35,accel=kvm",
"-cpu", "host", "-smp", SMP, "-m", MEM,
"-drive", f"if=pflash,format=raw,readonly=on,file={OVMF_CODE}",
"-drive", f"if=pflash,format=raw,file={self.paths.ovmf_vars}",
]
for disk in self.disks:
args += ["-drive", f"file={disk},if=virtio,format=qcow2"]
args += [
# A real GPU device so the compositor gets a DRM node and a seat.
"-device", "virtio-gpu-pci",
"-netdev", "user,id=n0", "-device", "virtio-net-pci,netdev=n0,romfile=",
"-device", "virtio-rng-pci",
]
if attach_iso and ISO:
args += ["-drive", f"file={ISO},media=cdrom,readonly=on"]
args += [
"-boot", "order=c" if boot_disk else "order=d",
"-vga", "none", "-display", "none",
"-serial", "stdio",
"-qmp", f"unix:{self.paths.monitor_sock},server,nowait",
"-no-reboot",
]
return args
def spawn(self, attach_iso: bool = True, boot_disk: bool = False) -> None:
if self.paths.monitor_sock.exists():
self.paths.monitor_sock.unlink()
args = self.qemu_args(attach_iso, boot_disk)
print(f"[run {self.paths.run_id}] {QEMU} " + " ".join(args), flush=True)
self.child = pexpect.spawn(
QEMU, args, timeout=BOOT_TIMEOUT, encoding="utf-8",
codec_errors="replace", maxread=65536,
)
self.child.delaybeforesend = 0.4
self.log = open(self.paths.serial_log, "w")
self.child.logfile = self.log
self.spawned = True
self.results.pass_(
"qemu-spawned", f"{len(self.disks)} writable disk(s); iso={bool(ISO)}"
)
# -- assertions and screenshots ---------------------------------------
def run_id(self) -> str:
return self.paths.run_id
def shot(
self,
slug: str,
ui_state: str,
action: str,
expected: str,
observed: str | None = None,
) -> Path | None:
self.seq += 1
name = vmsafety.screenshot_name(self.seq, slug)
ppm = self.paths.shot_dir / (name + ".ppm")
png = self.paths.shot_dir / (name + ".png")
if not self.paths.monitor_sock.exists():
self.results.skip(f"screenshot-{name}", "no monitor socket (not spawned)")
return None
ok = False
try:
with vmsafety.QmpClient(self.paths.monitor_sock) as client:
client.screendump(ppm)
vmsafety.convert_ppm(ppm, png)
ok = ppm.exists() and ppm.stat().st_size > 0
except Exception as exc: # noqa: BLE001 - report, never crash the run
self.results.fail(f"screenshot-{name}", str(exc))
self.manifest.append({
"run_id": self.paths.run_id,
"scenario": self.mode,
"sequence": self.seq,
"timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
"ui_state": ui_state,
"action": action,
"expected": expected,
"observed": observed if observed is not None else ("captured" if ok else "capture failed"),
"ppm": str(ppm) if ppm.exists() else None,
"png": str(png) if png.exists() else None,
})
if ok:
self.results.pass_(f"screenshot-{name}", str(png if png.exists() else ppm))
return ppm if ok else None
def write_manifest(self) -> None:
path = self.paths.directory / "screenshot-manifest.json"
path.write_text(json.dumps(self.manifest, indent=2) + "\n")
# -- pexpect helpers ---------------------------------------------------
def expect(self, patterns, timeout: int, label: str):
assert self.child is not None
try:
index = self.child.expect(patterns, timeout=timeout)
except pexpect.TIMEOUT as exc:
self.results.fail(label, f"timeout after {timeout}s")
raise HarnessError(f"timeout: {label}") from exc
except pexpect.EOF as exc:
self.results.fail(label, "unexpected EOF from the VM")
raise HarnessError(f"unexpected EOF: {label}") from exc
self.last_match = self.child.match
return index
def last_group(self, index: int) -> str:
match = getattr(self, "last_match", None)
if match is None:
return ""
try:
return match.group(index)
except (IndexError, AttributeError):
return ""
def last_text(self) -> str:
match = getattr(self, "last_match", None)
return match.group(0) if match is not None else ""
def shell(self, command: str, end_marker: str, timeout: int = 180, label: str = "") -> str:
assert self.child is not None
self.child.sendline(command)
self.expect(end_marker, timeout=timeout, label=label or f"shell:{end_marker}")
return self.child.before or ""
def poll_shell(
self, command: str, pattern: str, timeout: int, label: str, record: bool = True
) -> str | None:
"""Send a command and retry until `pattern` matches or the deadline.
Bounded readiness polling instead of blind sleeps. `record=False` lets a
caller retry without recording an intermediate failure.
"""
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
assert self.child is not None
self.child.sendline(command)
try:
self.child.expect(pattern, timeout=15)
return self.child.match.group(0)
except (pexpect.TIMEOUT, pexpect.EOF):
time.sleep(2)
if record:
self.results.fail(label, f"readiness not reached within {timeout}s")
return None
def qmp(self, action: str, *args, **kwargs) -> None:
assert self.child is not None
try:
with vmsafety.QmpClient(self.paths.monitor_sock) as client:
getattr(client, action)(*args, **kwargs)
except Exception as exc: # noqa: BLE001
self.results.fail(f"qmp-{action}", str(exc))
raise
def sendkey(self, *keys: str) -> None:
for key in keys:
self.qmp("sendkey", key)
time.sleep(0.2)
# -- guest login -------------------------------------------------------
def login_live(self) -> None:
assert self.child is not None
idx = self.expect([r"login:", r"[$#] $"], timeout=BOOT_TIMEOUT, label="live-login-prompt")
if idx == 0:
self.child.sendline(LIVE_USER)
self.expect(r"[Pp]assword:", timeout=90, label="live-password-prompt")
self.child.sendline(LIVE_PW)
self.expect(r"[$#] $", timeout=180, label="live-shell")
self.results.pass_("live-login")
def set_wayland(self) -> None:
out = self.shell(
'export XDG_RUNTIME_DIR=/run/user/1000; '
'export WAYLAND_DISPLAY="$(basename "$(ls /run/user/1000/wayland-* 2>/dev/null | head -1)")"; '
'echo WAYLAND=$WAYLAND_DISPLAY',
r"WAYLAND=wayland-\d+",
timeout=60,
label="wayland-session",
)
self.results.pass_("wayland-session", out.strip()[-40:])
# -- modes -------------------------------------------------------------
def run(self) -> int:
try:
if self.mode == "gui":
self.do_gui()
elif self.mode == "opencode":
self.do_opencode()
elif self.mode == "gui-install":
self.do_gui_install()
elif self.mode == "install":
self.do_install()
elif self.mode == "boot":
self.do_boot()
else:
print(__doc__)
return 2
except HarnessError as exc:
self.results.fail("harness", str(exc))
except Exception as exc: # noqa: BLE001
self.results.fail("harness-exception", repr(exc))
finally:
if self.spawned:
try:
self.shot("final-state", "final", "end of run", "last observed state")
except Exception: # noqa: BLE001
pass
self.teardown()
self.write_manifest()
results_path = self.results.write(self.paths.results_json)
print(self.results.summary(), flush=True)
print(f"results: {results_path}", flush=True)
print(f"serial: {self.paths.serial_log}", flush=True)
print(f"shots: {self.paths.shot_dir}", flush=True)
return self.results.exit_code()
def teardown(self) -> None:
if self.child is not None:
try:
self.child.close(force=True)
except Exception: # noqa: BLE001
pass
if self.log is not None:
try:
self.log.close()
except Exception: # noqa: BLE001
pass
# Cleanup is limited to this run's own socket.
try:
if self.paths.monitor_sock.exists():
self.paths.monitor_sock.unlink()
except OSError:
pass
# -- GUI journey -------------------------------------------------------
def do_gui(self) -> None:
self.spawn(attach_iso=True, boot_disk=False)
self.login_live()
welcome = self.poll_shell(
"echo WELCOME=$(pgrep -fc 'quickshell.*phoebus-welcome' 2>/dev/null || echo 0)",
r"WELCOME=([1-9][0-9]*)",
timeout=int(os.environ.get("WELCOME_TIMEOUT", "180")),
label="welcome-window",
)
self.results.assert_true(
"welcome-autostarted", welcome is not None, "welcome window did not appear"
)
self.shot("01-welcome", "welcome window", "observe at startup",
"branded welcome window with a dominant Install action")
# Markers are built with command substitution so the shell's echo of the
# typed command cannot contain them; a match therefore proves output.
checks = (
"echo ===GUI-CHECKS-$(printf START)===; "
"test -e /etc/phoebus/live && echo LIVE-$(printf MARKER); "
"test -s /usr/share/phoebus/branding/wallpaper.svg && echo BRAND-$(printf WALLPAPER); "
"test -s /usr/share/icons/hicolor/scalable/apps/phoebus.svg && echo BRAND-$(printf ICON); "
"test -s /etc/xdg/quickshell/phoebus-install/shell.qml && echo INSTALL-$(printf QML); "
"test -s /usr/share/applications/phoebus-install.desktop && echo DESKTOP-$(printf ENTRY); "
"test -f /home/phoebus/.config/DankMaterialShell/.firstlaunch && echo ONBOARDING-$(printf SUPPRESSED); "
"echo ===GUI-CHECKS-$(printf END)==="
)
payload = self.shell(checks, "===GUI-CHECKS-END===", timeout=180, label="payload-checks")
for marker in (
"LIVE-MARKER", "BRAND-WALLPAPER", "BRAND-ICON", "INSTALL-QML", "DESKTOP-ENTRY",
):
self.results.assert_true(
f"payload-{marker.lower()}", marker in payload, f"{marker} not in command output"
)
if "ONBOARDING-SUPPRESSED" not in payload:
self.results.skip("onboarding-suppressed", "first-run marker not present")
self.set_wayland()
# Disk protection is a deterministic backend property. The bridge JSON
# is long and the serial console wraps it, so a small guest-side summary
# is emitted instead of parsing wrapped JSON. Every marker is built with
# command substitution so the echoed command cannot be mistaken for it.
self.shell(
"printf '%s\\n%s\\n' '{\"id\":1,\"op\":\"disks\"}' '{\"id\":2,\"op\":\"quit\"}' "
"> /tmp/req.json; echo REQ-$(printf DONE)",
"REQ-DONE",
timeout=30,
label="disk-probe-request",
)
summary = self.shell(
"sudo -n /usr/local/bin/phoebus-installer --gui-bridge < /tmp/req.json "
"2>/dev/null | head -1 > /tmp/disks.json; "
"echo DISKS-$(printf COUNT)=$(grep -o '{[^{}]*}' /tmp/disks.json | wc -l); "
"echo LIVE-$(printf COUNT)=$(grep -o '{[^{}]*\"live_medium\":true[^{}]*}' "
"/tmp/disks.json | wc -l); "
"echo LIVE-$(printf PROTECTED)=$(grep -o '{[^{}]*\"live_medium\":true[^{}]*}' "
"/tmp/disks.json | grep -c '\"protected\":true'); "
"echo PROBE-$(printf DONE)",
"PROBE-DONE",
timeout=120,
label="disk-probe",
)
self._assert_live_medium_protected(summary)
# Activate the focused welcome action with Return (the real launcher).
# Retry a few times; a transient focus race must not be recorded as a
# passing launcher test, and the fallback launch is recorded as a FAIL.
self.shot("01b-focus", "welcome focused", "before launcher key",
"primary Install action visibly focused")
installed = None
for _attempt in range(3):
self.sendkey("ret")
installed = self.poll_shell(
"echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)",
r"INST=([1-9][0-9]*)",
timeout=30,
label="launcher-opens-installer",
record=False,
)
if installed is not None:
break
if installed is None:
# Fallback launch for diagnostics only: the launcher test stays failed.
self.results.fail(
"launcher-opens-installer",
"Return did not open the installer; using a diagnostic fallback launch",
)
self.shell(
"setsid /usr/local/bin/phoebus-install >/tmp/install-gui.log 2>&1 & echo LAUNCHED",
"LAUNCHED",
timeout=30,
label="fallback-launch",
)
time.sleep(7)
else:
self.results.pass_("launcher-opens-installer", "welcome action opened the installer")
# The frontend log must not contain bridge errors or a crash.
logdump = self.shell(
"echo QMLLOG-$(printf START); "
"cat /run/user/1000/quickshell/by-id/*/log.qslog 2>/dev/null | "
"grep -aiE 'phoebus-bridge|error|failed|handshake' | tail -30; "
"echo QMLLOG-$(printf END)",
"QMLLOG-END",
timeout=60,
label="frontend-log",
)
hard = [ln for ln in logdump.splitlines()
if "phoebus-bridge:" in ln and "error" in ln.lower()]
self.results.assert_true("frontend-no-bridge-errors", not hard, "; ".join(hard[:3]))
self.shot("02-installer-start", "installer wizard", "opened from the welcome",
"language and region step with visible focus")
time.sleep(BACKEND_SETTLE)
# Close the welcome so the tiled installer holds the keyboard.
self.shell(
"pkill -f 'quickshell.*phoebus-wel[c]ome' || true; sleep 2; echo CLOSED",
"CLOSED",
timeout=30,
label="close-welcome",
)
# Duplicate prevention: a second launch must not create a second session.
self.shell(
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n1; "
"/usr/local/bin/phoebus-install >/tmp/install-gui2.log 2>&1; "
"pgrep -f 'quickshell.*phoebus-install' | wc -l > /tmp/n2; "
"echo DUP n1=$(cat /tmp/n1) n2=$(cat /tmp/n2)",
r"DUP n1=(\d+) n2=(\d+)",
timeout=60,
label="duplicate-launch",
)
n1, n2 = int(self.last_group(1)), int(self.last_group(2))
# Exactly one session before and after: two pre-existing sessions must
# not pass as "no duplicate".
self.results.assert_true(
"exactly-one-installer-session", n1 == 1 and n2 == 1,
f"n1={n1} n2={n2}",
)
# Keyboard-walk the wizard, capturing each step. The welcome step's
# primary action is focused, so Return starts the journey; Ctrl+Right
# then advances through the deterministic steps.
self.sendkey("ret")
time.sleep(2)
self.shot("03-language", "language and keyboard", "Return on Get started",
"the language and keyboard step is shown")
# Regression: the suggestion list supports arrow-key navigation and
# Enter selection, with the value stored being the identifier.
self.sendkey("ctrl-a")
time.sleep(0.3)
self.shell("wtype 'de_DE' >/dev/null 2>&1; echo TYPED", "TYPED",
timeout=30, label="type-locale")
time.sleep(1.0)
self.sendkey("down")
time.sleep(0.5)
self.sendkey("ret")
time.sleep(1.0)
picked = self._frontend_state()
self.results.assert_true(
"keyboard-suggestion-select",
picked is not None and picked["step"] == 1
and picked["locale"].startswith("de_DE"),
f"Down/Enter did not select the highlighted suggestion: {picked}",
)
self.shot("03b-locale-selected", "locale selected", "Down then Enter",
"the highlighted locale is selected")
for slug, state in [
("04-network", "network and prerequisites"),
("05-ai-model", "AI model connection"),
]:
self.sendkey("ctrl-right")
time.sleep(2)
self.shot(slug, state, "Ctrl+Right", "next wizard step")
if not self._installer_alive():
self.results.fail("installer-survived-navigation", f"crashed at {slug}")
return
# Advancing without a connected model must be refused: the process must
# still be alive and the backend must not have started an install.
self.sendkey("ctrl-right")
time.sleep(2)
self.shot("06-ai-blocked", "AI model blocked", "Ctrl+Right without a model",
"advance refused; no install started")
blocked = self._bridge_has_no_install_start()
self.results.assert_true(
"ai-step-blocks-install", blocked,
"the AI step allowed advancement without a connected model",
)
# Behavioral evidence from the frontend's own state lines: the wizard is
# still on the AI step (index 3) and has not reported a connection, and
# it shows an inline error. A surviving process or a screenshot would
# not prove any of this.
state = self._frontend_state()
if state is None:
self.results.fail("ai-page-remains", "no frontend state line found")
else:
self.results.assert_true(
"ai-page-remains", state["step"] == 3 and not state["aiConnected"],
f"last state: {state}",
)
self.results.assert_true(
"ai-error-shown", bool(state["aiError"]),
f"the AI step showed no inline error: {state}",
)
self.results.pass_("gui-walk-completed")
def _frontend_state(self) -> dict | None:
"""Read the frontend's last secret-free state line.
The pattern is built from a variable so the shell echo of the command
cannot be mistaken for a real state line.
"""
assert self.child is not None
self.child.sendline(
'P=phoebus-; grep -ah "${P}state " '
"/run/user/1000/quickshell/by-id/*/log.qslog 2>/dev/null | tail -1; "
"echo STATE-$(printf END)"
)
try:
self.child.expect("STATE-END", timeout=30)
except (pexpect.TIMEOUT, pexpect.EOF):
return None
step = ai = tested = review = None
applied = 0
disk = ""
locale = ""
keymap = ""
phase = ""
confirmed = False
focus = ""
err = ""
for line in (self.child.before or "").splitlines():
if "phoebus-state" not in line:
continue
match = re.search(r"step=(\d+)", line)
if match:
step = int(match.group(1))
match = re.search(r"phase=(\w+)", line)
if match:
phase = match.group(1)
match = re.search(r"aiConnected=(true|false)", line)
if match:
ai = match.group(1) == "true"
match = re.search(r"aiTested=(true|false)", line)
if match:
tested = match.group(1) == "true"
match = re.search(r"aiReview=(true|false)", line)
if match:
review = match.group(1) == "true"
match = re.search(r"aiApplied=(\d+)", line)
if match:
applied = int(match.group(1))
match = re.search(r"disk=(\S*)", line)
if match:
disk = match.group(1)
match = re.search(r"locale=(\S*)", line)
if match:
locale = match.group(1)
match = re.search(r"keymap=(\S*)", line)
if match:
keymap = match.group(1)
match = re.search(r"confirm=(true|false)", line)
if match:
confirmed = match.group(1) == "true"
match = re.search(r"focus=(\S*)", line)
if match:
focus = match.group(1)
match = re.search(r"aiError=(.*?) aiTest=", line)
if match:
err = match.group(1).strip()
if step is None:
return None
return {
"step": step,
"phase": phase,
"aiConnected": bool(ai),
"aiTested": bool(tested),
"aiApplied": applied,
"aiReview": bool(review),
"disk": disk,
"locale": locale,
"keymap": keymap,
"confirm": confirmed,
"focus": focus,
"aiError": err,
}
def wait_state(self, predicate, timeout: int):
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
state = self._frontend_state()
if state is not None and predicate(state):
return state
time.sleep(2)
return None
def do_opencode(self) -> None:
"""Drive the OpenCode AI step through the real graphical UI.
The model is reached from the guest through a loopback relay (the same
shape as an SSH tunnel), so the connection satisfies the transport
policy while staying host-local or host+LAN only.
"""
self.spawn(attach_iso=True, boot_disk=False)
self.login_live()
welcome = self.poll_shell(
"echo WELCOME=$(pgrep -fc 'quickshell.*phoebus-welcome' 2>/dev/null || echo 0)",
r"WELCOME=([1-9][0-9]*)", timeout=int(os.environ.get("WELCOME_TIMEOUT", "180")),
label="welcome-window",
)
self.results.assert_true("welcome-autostarted", welcome is not None, "welcome did not appear")
self.set_wayland()
# Start the guest-local relay to the host OpenCode server.
self.shell(
f"curl -fsSL {SERVE_URL}/oc-forward.py -o /tmp/oc-forward.py && "
f"chmod 755 /tmp/oc-forward.py && "
f"setsid python3 /tmp/oc-forward.py {OC_PORT} 10.0.2.2 {OC_TARGET_PORT} "
f">/tmp/oc-forward.log 2>&1 < /dev/null & echo FWD-$(printf START)",
"FWD-START", timeout=60, label="forwarder-start",
)
ready = self.poll_shell(
f"curl -s -m 5 -o /dev/null -w 'HEALTH=%{{http_code}}' "
f"http://127.0.0.1:{OC_PORT}/global/health",
r"HEALTH=(200|401)", timeout=60, label="forwarder-ready",
)
self.results.assert_true(
"opencode-reachable-from-guest", ready is not None,
"the guest relay could not reach the OpenCode server",
)
self.sendkey("ret")
opened = self.poll_shell(
"echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)",
r"INST=([1-9][0-9]*)", timeout=int(os.environ.get("INSTALLER_OPEN_TIMEOUT", "90")),
label="launcher-opens-installer", record=False,
)
if opened is None:
self.results.fail("launcher-opens-installer", "Return did not open the installer")
return
self.results.pass_("launcher-opens-installer", "welcome action opened the installer")
time.sleep(BACKEND_SETTLE)
self.shell(
"pkill -f 'quickshell.*phoebus-wel[c]ome' || true; sleep 2; echo CLOSED",
"CLOSED", timeout=30, label="close-welcome",
)
# Navigate to the AI step (welcome -> language -> network -> AI).
self.sendkey("ret")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(2)
state = self._frontend_state()
self.results.assert_true(
"ai-step-reached", state is not None and state["step"] == 3,
f"frontend state: {state}",
)
self.shot("oc-01-ai", "AI step", "Return + Ctrl+Right twice", "the AI model step is shown")
# Select the "OpenCode agent" chip with the keyboard. The AI step opens
# with the first provider chip focused.
for _ in range(OC_TAB_TO_CHIP):
self.sendkey("tab")
time.sleep(0.3)
self.sendkey("ret")
time.sleep(1)
self.shot("oc-02-selected", "OpenCode selected", "Tab to the chip and Return",
"server, password, provider and model fields appear")
# Enter the connection through the UI. Focus is on the chip after
# selection; Tab order is server, password (input + reveal), provider,
# model, load, Test. Ctrl+A selects the existing default before typing.
def type_field(tabs: int, value: str, secret_file: str | None = None) -> None:
# `wtype` (Wayland) and QEMU `sendkey` (hardware) are two input
# paths; settle between them or the next key can truncate the text.
for _ in range(tabs):
self.sendkey("tab")
time.sleep(0.4)
self.sendkey("ctrl-a")
time.sleep(0.5)
if secret_file:
# The serial echo carries `$(cat ...)`, never the value.
self.shell(
f'wtype "$(cat {secret_file})" >/dev/null 2>&1; echo TYPED',
"TYPED", timeout=30, label="type-secret",
)
else:
self.shell(
f"wtype '{value}' >/dev/null 2>&1; echo TYPED",
"TYPED", timeout=30, label="type-field",
)
time.sleep(1.4)
# Clear the selection highlight so a screenshot shows the value.
self.sendkey("end")
time.sleep(0.3)
type_field(1, f"http://127.0.0.1:{OC_PORT}")
if OC_USE_PASSWORD:
self.shell(
f"curl -fsSL {SERVE_URL}/oc.pw -o /tmp/oc.pw && chmod 600 /tmp/oc.pw "
"&& echo PW-$(printf LOADED)",
"PW-LOADED", timeout=30, label="fetch-password",
)
type_field(1, "", secret_file="/tmp/oc.pw")
self.sendkey("tab") # the keyboard reveal control
else:
self.sendkey("tab") # the empty password field
time.sleep(0.25)
self.sendkey("tab") # the keyboard reveal control
time.sleep(0.25)
type_field(1, OC_PROVIDER)
type_field(1, OC_MODEL)
self.shot("oc-02b-fields", "OpenCode fields", "typed server/provider/model",
"the fields hold the entered values")
self.sendkey("tab") # model -> load
time.sleep(0.3)
self.sendkey("tab") # load -> Test
time.sleep(0.3)
self.sendkey("ret")
time.sleep(3)
self.shot("oc-03-test", "Test connection", "Return on Test connection",
"a real model response is obtained and validated")
tested = self.wait_state(lambda s: s["aiTested"], timeout=180)
self.results.assert_true(
"opencode-test-connection", tested is not None,
"Test connection did not obtain a valid model response",
)
# The next focus is the "Connect and validate" button.
self.sendkey("tab")
time.sleep(0.3)
self.sendkey("ret")
self.shot("oc-04-connect", "Connect and validate", "Return on Connect and validate",
"a validated proposal is applied; Next is enabled")
connected = self.wait_state(lambda s: s["aiConnected"], timeout=240)
self.results.assert_true(
"opencode-validated-proposal",
connected is not None,
f"Connect and validate did not validate a proposal: {connected}",
)
if connected is not None:
# A validated proposal may legitimately contain zero changes.
self.results.pass_(
"opencode-proposal-applied",
f"applied={connected['aiApplied']} change(s)",
)
# Regression: editing the model must invalidate the green "validated"
# indicator, because the backend would require revalidation. Focus is
# on Connect; Shift+Tab walks back over Test and Load to the model.
for _ in range(3):
self.sendkey("shift-tab")
time.sleep(0.4)
self._gui_type(OC_MODEL + "-changed")
edited = self.wait_state(lambda s: not s["aiConnected"], timeout=30)
self.results.assert_true(
"ai-invalidated-on-model-edit", edited is not None,
"editing the model left the AI connection green",
)
self.results.pass_("opencode-gui-completed")
# -- full graphical installation --------------------------------------
_PLAIN_KEYS = {
" ": "spc", "-": "minus", "=": "equal", "[": "bracketleft",
"]": "bracketright", "\\": "backslash", ";": "semicolon",
"'": "apostrophe", ",": "comma", ".": "dot", "/": "slash", "`": "grave",
}
_SHIFT_KEYS = {
"_": "minus", "+": "equal", ":": "semicolon", '"': "apostrophe",
"<": "comma", ">": "dot", "?": "slash", "{": "bracketleft",
"}": "bracketright", "|": "backslash", "~": "grave",
}
def _tabs(self, count: int) -> None:
for _ in range(count):
self.sendkey("tab")
time.sleep(0.4)
def _send_chars(self, text: str) -> None:
"""Type text as hardware key events.
The QEMU/HMP `wtype` path used by `opencode` mode can leave the
compositor focus ambiguous. The full-install journey types every field
with real key events so focus is always exactly the focused control.
"""
for ch in text:
if ch.isalpha():
self.sendkey(ch if ch.islower() else "shift-" + ch.lower())
elif ch.isdigit():
self.sendkey(ch)
elif ch in self._PLAIN_KEYS:
self.sendkey(self._PLAIN_KEYS[ch])
elif ch in self._SHIFT_KEYS:
self.sendkey("shift-" + self._SHIFT_KEYS[ch])
else:
raise HarnessError(f"no QEMU key for character {ch!r}")
time.sleep(0.1)
def _gui_type(self, value: str) -> None:
self.sendkey("ctrl-a")
time.sleep(0.3)
self._send_chars(value)
time.sleep(1.0)
def _accept_ai_review(self, applied: int):
"""Accept a proposed-change review if one was applied.
The Accept button follows Connect (and possibly the conditional Retry
button), so try a few Tab/Return pairs and stop as soon as the review
is accepted.
"""
if applied <= 0:
return True
for _ in range(4):
self.sendkey("tab")
time.sleep(0.4)
self.sendkey("ret")
time.sleep(1.5)
state = self._frontend_state()
if state is not None and state["aiReview"]:
return True
return False
def do_gui_install(self) -> None:
"""Complete installation through the visible wizard.
`appliance-guest-gui.sh` installs non-interactively, which does not
prove the graphical journey. This mode presses the real controls: it
connects OpenCode through the UI, accepts the reviewed AI changes,
selects a disk, sets the account, types ERASE, installs, and checks the
frontend reports completion. The disk must be a disposable qcow2.
"""
if not self.disks:
self.results.blocked("gui-install-disk", "no writable disk configured")
return
self.spawn(attach_iso=True, boot_disk=False)
self.login_live()
welcome = self.poll_shell(
"echo WELCOME=$(pgrep -fc 'quickshell.*phoebus-welcome' 2>/dev/null || echo 0)",
r"WELCOME=([1-9][0-9]*)",
timeout=int(os.environ.get("WELCOME_TIMEOUT", "180")),
label="welcome-window",
)
self.results.assert_true("welcome-autostarted", welcome is not None, "welcome did not appear")
self.set_wayland()
# Preseed the wizard defaults so the run is bounded (safe kernel, no
# desktop) while the wizard, validation, AI gate and ERASE confirmation
# remain the real graphical path.
self.shell(
f"curl -fsSL {SERVE_URL}/test.conf -o /tmp/gui-install.conf && "
"sudo -n install -D -m 0644 /tmp/gui-install.conf /etc/phoebus/install.conf && "
"echo PRESEED-$(printf DONE)",
"PRESEED-DONE", timeout=60, label="preseed-config",
)
# Start the loopback relay to the host OpenCode server.
self.shell(
f"curl -fsSL {SERVE_URL}/oc-forward.py -o /tmp/oc-forward.py && "
f"chmod 755 /tmp/oc-forward.py && "
f"setsid python3 /tmp/oc-forward.py {OC_PORT} 10.0.2.2 {OC_TARGET_PORT} "
f">/tmp/oc-forward.log 2>&1 < /dev/null & echo FWD-$(printf START)",
"FWD-START", timeout=60, label="forwarder-start",
)
ready = self.poll_shell(
f"curl -s -m 5 -o /dev/null -w 'HEALTH=%{{http_code}}' "
f"http://127.0.0.1:{OC_PORT}/global/health",
r"HEALTH=(200|401)", timeout=60, label="forwarder-ready",
)
self.results.assert_true(
"opencode-reachable-from-guest", ready is not None,
"the guest relay could not reach the OpenCode server",
)
# Launch the installer from the welcome action.
self.sendkey("ret")
opened = self.poll_shell(
"echo INST=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)",
r"INST=([1-9][0-9]*)", timeout=int(os.environ.get("INSTALLER_OPEN_TIMEOUT", "90")),
label="launcher-opens-installer",
)
self.results.assert_true("launcher-opens-installer", opened is not None,
"welcome action did not open the installer")
time.sleep(BACKEND_SETTLE)
self.shell(
"pkill -f 'quickshell.*phoebus-wel[c]ome' || true; sleep 2; echo CLOSED",
"CLOSED", timeout=30, label="close-welcome",
)
# Welcome -> language -> network -> AI.
self.sendkey("ret")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(2)
self.sendkey("ctrl-right")
time.sleep(3)
state = self._frontend_state()
self.results.assert_true("gui-install-ai-step", state is not None and state["step"] == 3,
f"AI step not reached: {state}")
self.shot("gi-01-ai", "AI step", "Return, Ctrl+Right twice", "AI connection step")
# Select OpenCode and connect through the UI.
for _ in range(OC_TAB_TO_CHIP):
self.sendkey("tab")
time.sleep(0.3)
self.sendkey("ret")
time.sleep(1)
self._tabs(1) # chip -> server
self._gui_type(f"http://127.0.0.1:{OC_PORT}")
self.sendkey("tab") # server -> password
self.sendkey("tab") # password -> reveal
self._tabs(1) # reveal -> provider
self._gui_type(OC_PROVIDER)
self._tabs(1) # provider -> model
self._gui_type(OC_MODEL)
self.sendkey("tab") # model -> load
self.sendkey("tab") # load -> Test
self.sendkey("ret")
tested = self.wait_state(lambda s: s["aiTested"], timeout=300)
self.results.assert_true("gui-install-ai-tested", tested is not None,
"Test connection did not succeed")
self.sendkey("tab") # Test -> Connect
self.sendkey("ret")
connected = self.wait_state(lambda s: s["aiConnected"], timeout=240)
self.results.assert_true("gui-install-ai-connected", connected is not None,
f"Connect and validate failed: {connected}")
applied = connected["aiApplied"] if connected else 0
self.results.assert_true(
"gui-install-ai-reviewed", self._accept_ai_review(applied),
"the AI review could not be accepted",
)
self.shot("gi-02-ai-reviewed", "AI reviewed", "Accept changes", "review accepted")
# Destination disk: pick the first selectable disk.
self.sendkey("ctrl-right")
time.sleep(3)
self.sendkey("tab")
time.sleep(0.5)
self.sendkey("ret")
time.sleep(1)
state = self._frontend_state()
self.results.assert_true(
"gui-install-disk-selected", state is not None and state["disk"] != "",
f"no destination disk was selected: {state}",
)
self.shot("gi-03-disk", "disk selected", "Tab and Return on the first disk",
"a destination disk is selected")
# Regression: re-checking network readiness from the network step must
# not reset the wizard or clear the chosen disk, and unrelated
# navigation must preserve the validated AI connection.
selected = state["disk"]
self.sendkey("ctrl-left") # disk -> AI
time.sleep(1.5)
self.sendkey("ctrl-left") # AI -> network
time.sleep(1.5)
before = self._frontend_state()
self.results.assert_true(
"back-nav-preserves-ai", before is not None and before["aiConnected"],
f"back-navigation lost the AI validation: {before}",
)
self.sendkey("ret") # Re-check (focused when the network step opens)
time.sleep(4)
after = self._frontend_state()
self.results.assert_true(
"readiness-refresh-preserves-wizard",
after is not None and after["step"] == 2 and after["disk"] == selected,
f"re-check reset the wizard or cleared the disk: before={before} after={after}",
)
# Walk forward again; the disk selection must still be present.
self.sendkey("ctrl-right") # network -> AI
time.sleep(2)
self.sendkey("ctrl-right") # AI -> disk
time.sleep(3)
state = self._frontend_state()
self.results.assert_true(
"disk-survives-backtrack",
state is not None and state["step"] == 4 and state["disk"] == selected,
f"the disk selection did not survive backtracking: {state}",
)
# Account and encryption.
self.sendkey("ctrl-right")
time.sleep(2)
state = self._frontend_state()
self.results.assert_true("gui-install-account-step", state is not None and state["step"] == 5,
f"account step not reached: {state}")
self._tabs(3) # full name -> username -> computer name -> password
self._gui_type(USER_PW)
self._tabs(2) # reveal -> confirm password
self._gui_type(USER_PW)
self._tabs(2) # reveal -> passphrase
self._gui_type(LUKS_PW)
self._tabs(2) # reveal -> confirm passphrase
self._gui_type(LUKS_PW)
self.shot("gi-04-account", "account and encryption", "typed credentials",
"password and passphrase entered")
# Review and ERASE. The review step focuses the ERASE field.
self.sendkey("ctrl-right")
time.sleep(4)
state = self._frontend_state()
self.results.assert_true("gui-install-review-step", state is not None and state["step"] == 6,
f"review step not reached: {state}")
self.shot("gi-05-review", "review and confirmation", "review shown",
"backend facts, plan and ERASE confirmation")
self._gui_type("ERASE")
self.sendkey("tab") # the confirmation toggle
time.sleep(0.4)
confirmed = self._frontend_state()
# The toggle responds to Return and Space; QEMU names Space `spc`.
for key in ("ret", "spc"):
if confirmed is not None and confirmed["confirm"]:
break
self.sendkey(key)
time.sleep(0.5)
confirmed = self._frontend_state()
if confirmed is None or not confirmed["confirm"]:
self.results.fail(
"gui-install-erase-confirmed",
f"the confirmation toggle was not ticked: {confirmed}",
)
return
self.results.pass_("gui-install-erase-confirmed")
self.sendkey("ctrl-right") # authorize and install
self.shot("gi-06-installing", "installing", "Ctrl+Right on review",
"the installation has started")
done = self.wait_state(
lambda s: s["phase"] in ("done", "failed"),
timeout=INSTALL_TIMEOUT,
)
if done is None:
self.results.fail("gui-install-completes", "the wizard did not report completion")
return
self.results.assert_true(
"gui-install-completes", done["phase"] == "done",
f"the installer reported failure: {done}",
)
self.shot("gi-07-complete", "completion", "installation finished",
"the completion screen is shown")
if done["phase"] == "done":
self.results.pass_("gui-install-journey")
# Power off cleanly so the installed disk is flushed for the boot mode.
self.shell("sudo -n systemctl poweroff >/dev/null 2>&1 || true; echo POW",
"POW", timeout=60, label="poweroff")
try:
self.child.expect(pexpect.EOF, timeout=300)
except (pexpect.TIMEOUT, pexpect.EOF):
pass
def _installer_alive(self) -> bool:
assert self.child is not None
self.child.sendline(
"echo ALIVE=$(pgrep -fc 'quickshell.*phoebus-install' 2>/dev/null || echo 0)"
)
try:
self.child.expect(r"ALIVE=(\d+)", timeout=30)
except (pexpect.TIMEOUT, pexpect.EOF):
return False
return int(self.child.match.group(1)) >= 1
def _bridge_has_no_install_start(self) -> bool:
# The installer log records storage_prepare only when a backend run
# actually starts; at this point it must not have completed it. The
# marker is built with command substitution so the echoed command cannot
# be mistaken for the result.
assert self.child is not None
self.child.sendline(
"echo NOSTART=$(grep -l 'stage complete: storage_prepare' "
"/run/phoebus-installer/install.log /tmp/phoebus-installer/install.log "
"2>/dev/null | wc -l)"
)
try:
self.child.expect(r"NOSTART=(\d+)", timeout=30)
except (pexpect.TIMEOUT, pexpect.EOF):
return False
return self.child.match.group(1).strip() == "0"
@staticmethod
def _first_int(text: str, key: str) -> int | None:
match = re.search(re.escape(key) + r"=(\d+)", text)
return int(match.group(1)) if match else None
def _assert_live_medium_protected(self, summary: str) -> None:
total = self._first_int(summary, "DISKS-COUNT")
live = self._first_int(summary, "LIVE-COUNT")
protected = self._first_int(summary, "LIVE-PROTECTED")
if total is None or live is None or protected is None:
self.results.fail(
"disks-probe",
f"could not read the disk summary (total={total} live={live} protected={protected})",
)
return
self.results.assert_true("disks-listed", total >= 1, "no disks reported")
if live >= 1:
self.results.assert_true(
"live-medium-protected",
protected == live,
f"{protected}/{live} live media were protected",
)
else:
self.results.skip("live-medium-protected", "no live medium in the probe")
# -- non-interactive install ------------------------------------------
def do_install(self) -> None:
if not self.disks:
self.results.blocked("install-disk", "no writable disk configured")
return
self.spawn(attach_iso=True, boot_disk=False)
self.login_live()
self.shell(
f"curl -fsSL {SERVE_URL}/appliance-guest-gui.sh -o /tmp/gi.sh && bash /tmp/gi.sh",
r"===INSTALL-RC=([0-9]+)===",
timeout=INSTALL_TIMEOUT,
label="install-completes",
)
rc = self.child.match.group(1) if self.child else "?"
self.results.assert_true("install-rc-zero", rc == "0", f"INSTALL-RC={rc}")
# The secret-leak marker is emitted by the guest script.
assert self.child is not None
try:
self.child.expect(r"===NO_SECRET_LEAK===", timeout=120)
self.results.pass_("no-secret-leak")
except (pexpect.TIMEOUT, pexpect.EOF):
self.results.fail("no-secret-leak", "the guest did not report NO_SECRET_LEAK")
try:
self.child.expect(["===POWEROFF===", pexpect.EOF], timeout=600)
except pexpect.TIMEOUT:
self.results.fail("poweroff", "the guest did not power off")
try:
self.child.expect(pexpect.EOF, timeout=300)
except pexpect.TIMEOUT:
self.results.fail("install-eof", "QEMU did not exit after poweroff")
# -- detached boot -----------------------------------------------------
def do_boot(self) -> None:
if not self.disks:
self.results.blocked("boot-disk", "no writable disk configured")
return
self.spawn(attach_iso=False, boot_disk=True)
checks = os.environ.get(
"BOOT_CHECKS",
"echo ===CHECKS-$(printf START)===; "
"cat /proc/1/comm; systemctl is-system-running; "
"systemctl --failed --no-pager; ip -brief addr; "
"lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS; echo ===CHECKS-$(printf END)===",
)
assert self.child is not None
idx = self.expect([r"[Pp]assphrase", r"login:"], timeout=BOOT_TIMEOUT, label="boot-prompt")
if idx == 0:
self.child.sendline(LUKS_PW)
logged_in = False
for _ in range(5):
try:
self.child.expect(r"phoebus login:", timeout=300)
except (pexpect.TIMEOUT, pexpect.EOF):
break
self.child.sendline(USER)
choice = self.child.expect(
[r"[Pp]assword:", r"phoebus login:", r"Login incorrect"], timeout=60
)
if choice == 0:
self.child.sendline(USER_PW)
if self.child.expect([r"[$#] $", r"Login incorrect", r"phoebus login:"],
timeout=120) == 0:
logged_in = True
break
self.results.assert_true("detached-boot-login", logged_in, "could not log in")
self.shell(checks, "===CHECKS-END===",
timeout=int(os.environ.get("CHECKS_TIMEOUT", "300")), label="boot-checks")
serial = self.paths.serial_log.read_text(errors="replace")
self.results.assert_true(
"boot-systemd-running", "running" in serial, "systemd did not report running"
)
def main() -> int:
mode = sys.argv[1] if len(sys.argv) > 1 else ""
if mode not in ("gui", "opencode", "gui-install", "install", "boot"):
print(__doc__)
return 2
if mode in ("install", "boot", "gui-install") and not DISKS:
print("error: DISK/DISKS must name a disposable qcow2 image", file=sys.stderr)
return 2
try:
return Driver(mode).run()
except HarnessError as exc:
print(f"harness error: {exc}", file=sys.stderr)
return 2
if __name__ == "__main__":
sys.exit(main())