Automated validation after implementing Fases 2–5 (Hub staging cleanup, Remote VM details + Command Queue UI, Labs workspace, Lab power actions + polish), on top of the already-validated Fase 1 (Remote VM Power Control, 260 tests, real PC ↔ Lenovo smoke):
-
QT_QPA_PLATFORM=offscreen ~/.venvs/hypergery/bin/python -m unittest discover -s tests— 315 tests OK. -
python3 -m unittest discover -s tests— 315 tests OK (Qt tests skipped cleanly without PySide6). -
python3 -m compileall hypergery-ubuntuOK. -
bash -non all 9 shell scripts OK. -
docker compose configOK. - Final audit grep: no secrets, passwords, private keys, TODO/FIXME, or stale "planned for v0.8" promises in code/docs (settings callouts re-worded; remaining "arrives in v0.8" mentions are historical v0.7 notes or refer to post-v0.8 features).
- Removed stale
MagicMock/test-pollution directory from the repo root; confirmed the current suite does not recreate it.
New v0.8 test coverage includes: staging cleanup rules (dry-run default,
active/recent/symlink protection, traversal), cleanup CLI confirm flow,
command listing filters/limits (store + HTTP + client), agent XML
interface parsing and inventory fallback, remote VM details panel with
staleness warning, Commands page rendering/filters/copy/read-only checks,
lab manifest vm_roles migration, lab workspace aggregation
(local + remote + manifest-only), lab power planning and role ordering, lab
action confirmations and partial-failure reporting, and Hub-offline /
empty-state rendering for every new page.
Pending for tomorrow (manual smoke, PC ↔ Lenovo, see §13.4 of the v0.8 plan): remote inventory/start/shutdown/force-off in real hardware, Command Queue with real commands, staging cleanup dry-run + confirm over a fake orphan package, Labs workspace with real VMs, Start/Shutdown Lab, console local VNC/SPICE, Diagnostics, Settings. No release, no tag, no merge to main until the user confirms "smoke OK".
-
QT_QPA_PLATFORM=offscreen ~/.venvs/hypergery/bin/python -m unittest discover -s testsran 249 tests OK. -
python3 -m unittest discover -s testsran 249 tests OK with Qt tests skipped cleanly. -
python3 -m compileall hypergery-ubuntuOK. -
bash -non all 9 shell scripts OK (includingstart-second-host.shandinstall-agent-user-service.sh). -
docker compose configOK. - Hub package staging endpoints smoke-tested against the NAS Hub (upload → list → delete).
- Real two-host Hub Transfer E2E migrations passed on physical hardware (source gerard-MS-7E26 → target gery-Lenovo-ideapad-330S-14IKB via Hub on the NAS):
- small-disk migration →
done - migration including a 2.8 GiB ISO →
done - migration with a ~5.8 GiB VM disk →
done, target started after import
- small-disk migration →
- In every E2E run: source VM untouched, target imported with regenerated UUID/MAC, Hub staging copy deleted after import (
hub_package_deleted: true), target temp directory cleaned. - True live RAM migration remains intentionally not included in v0.7.0.
Validate the Docker deployment files without starting the service:
cd docker
docker compose config
docker compose buildWhen running on the NAS:
curl http://192.168.1.150:8765/health
curl http://192.168.1.150:8765/hostsAgent smoke on Ubuntu:
export HYPERGERY_HUB_URL=http://192.168.1.150:8765
export HYPERGERY_HOST_ID=ubuntu-hyperv
export HYPERGERY_HOST_NAME="Ubuntu Hyper-V"
export HYPERGERY_NAS_STAGING_PATH=/mnt/hypergery-nas/hypergery
python -m hypergery_ubuntu.cli agent once
python -m hypergery_ubuntu.cli host list --hub-url http://192.168.1.150:8765
python -m hypergery_ubuntu.cli hub vms --hub-url http://192.168.1.150:8765Docker/Hub/Agent smoke on prepared host (2026-06-05):
-
docker compose configpassed. - Initial Docker smoke exposed a real deployment issue: SQLite DB on
./datacan lock when the repo is on a NAS/shared mount. - Docker Compose now persists
/datain the Docker volumehypergery-hub-data;/hypergeryremains the NAS data bind mount. - Docker image includes a
/healthhealthcheck. -
docker compose buildcompleted. -
docker compose up -d --force-recreatestartedhypergery-hub. -
curl http://127.0.0.1:8765/healthreturned{"ok": true}. -
curl http://127.0.0.1:8765/hostsreturned an empty host list before agent registration. -
curl http://127.0.0.1:8765/vmsreturned an empty VM list before agent inventory. -
agent onceregisteredubuntu-hypervwith KVM/libvirt OK. -
host listshowedubuntu-hypervonline. -
hub vmsreturned the current VM inventory from the agent. -
host test ubuntu-hypervqueued a ping command, and a secondagent oncecompleted it withpong=true. - Qt Remote Hosts offscreen smoke loaded
ubuntu-hypervfrom the real local Hub. - Qt Live Migration dialog offscreen smoke listed
ubuntu-hypervfrom the real local Hub and kept Start Migration disabled until preflight. -
timeout 8s ./scripts/dev-run.sh --no-installreached preflight OK without traceback; timeout was controlled because the GUI remains open.
NAS Clone Migration local E2E smoke on prepared host (2026-06-05):
- No second physical host was available in this environment; the E2E used two logical agent IDs on the same libvirt host:
ubuntu-hyperv-sourceandubuntu-hyperv-target. - Hub Docker was running at
http://127.0.0.1:8765. - NAS staging was writable at
/home/gerard/NAS_Gerard/hypergeryin this environment. - Created a shut off test source VM only:
hg-v06-e2e-source, VNC display, 1 GiB RAM, 1 vCPU, 2 GiB qcow2. - Registered source and target logical agents with KVM/libvirt OK.
- Ran CLI remote migration with
--source-host-id ubuntu-hyperv-source,--target-host-id ubuntu-hyperv-target,--target-vm-name hg-v06-e2e-target,--nas-path /home/gerard/NAS_Gerard/hypergery, and--no-snapshots. - Migration ID:
hg-v06-e2e-source-61900e7cec58. - Package path:
/home/gerard/NAS_Gerard/hypergery/migrations/hg-v06-e2e-source-61900e7cec58. - Package contains
manifest.json,domain.xml,logs/migration.log, disk asset, ISO asset, and lab metadata. - Hub migration status reached
done, strategynas_clone,source_will_be_deleted=false, no warnings, no errors. - Target agent processed
import_vm_packagecommand with statusdone. - Source VM remained defined and shut off after migration.
- Source disk remained present:
/home/gerard/.local/share/hypergery/vms/hg-v06-e2e-source/hg-v06-e2e-source.qcow2. - Target VM was imported as
hg-v06-e2e-target. - Target UUID differed from source UUID (
a847645b-261d-4ef1-9ab3-22d4947a34dd->73b093dd-955e-4c62-8921-c9ea6cb4f783). - Target MAC differed from source MAC (
52:54:00:dc:03:8e->52:54:1c:eb:af:72). - Target VM started successfully and reached
running. - Target VM was force-powered off after the start smoke and then cleaned up with
delete-vm hg-v06-e2e-target --delete-disks. - Qt Remote Hosts offscreen smoke showed source and target logical hosts.
- Qt Live Migration dialog offscreen smoke listed
ubuntu-hyperv-target; offline target state blocked migration, and a refreshed online target allowed preflight and enabled Start Migration. - A real two-physical-host NAS Clone Migration smoke passed before final release.
NAS Clone Migration two-physical-host smoke on prepared hosts (2026-06-05):
- Hub URL:
http://192.168.1.44:8765. - Source host:
hg-source(Gerard Sourceongerard-MS-7E26). - Target host:
hg-target(Lenovo Targetongery-Lenovo-ideapad-330S-14IKB). - Old offline hosts from previous smoke runs were ignored.
-
hg-targetinitially reportedlibvirt_ok=falsebecause an old agent process was running with stale state; restarting the agent after libvirt/group setup fixed it. -
host testcommands initially printedpendingbecause the CLI only queued commands; the agents did process them.host testnow waits for terminal status by default. -
hg-sourceandhg-targetboth reportedonline,kvm_ok=true, andlibvirt_ok=true. -
host test hg-sourcecompleted withstatus=doneandpong=true. -
host test hg-targetcompleted withstatus=doneandpong=true. - Hub VM inventory refreshed for
hg-sourceandhg-target. - NAS staging path
/mnt/hypergery-nas/hypergerywas writable from both hosts. - Created only the allowed smoke source VM:
hg-v06-2host-source. - Source VM before migration: UUID
9ede2302-fabf-4b3a-a6c0-67bd20e217fb, MAC52:54:00:cb:ed:8f, disk/home/gerard/.local/share/hypergery/vms/hg-v06-2host-source/hg-v06-2host-source.qcow2. - Target VM name
hg-v06-2host-targetwas absent before import. - Migration ID:
hg-v06-2host-source-f67154f7803b. - Package path:
/mnt/hypergery-nas/hypergery/migrations/hg-v06-2host-source-f67154f7803b. - Migration status reached
done, strategynas_clone, no warnings, no errors. - Package contains
manifest.json,domain.xml, disk asset, ISO asset, lab metadata, and migration log. - Source VM remained defined and shut off after migration.
- Source UUID and MAC remained unchanged.
- Target VM was imported as
hg-v06-2host-target. - Target UUID differed from source UUID:
113d0d29-1726-4a7e-a703-de84f81e2602. - Target MAC differed from source MAC:
52:54:a5:a1:4e:be. - Target disk existed at
/home/gery/.local/share/hypergery/vms/hg-v06-2host-target/hg-v06-2host-source.qcow2. - Target VM started and reached
running. - Target VM cleanup completed with
force-offafter ACPI timeout, thendelete-vm hg-v06-2host-target --delete-disks. - Target disk was removed by cleanup.
- Source VM and source disk were not deleted.
- NAS package was retained for audit.
- True live RAM migration remains intentionally not included in v0.6.0.
v0.6.0 close-out check on prepared host (2026-06-05):
-
developwas synchronized withorigin/develop. -
QT_QPA_PLATFORM=offscreen /home/gerard/.venvs/hypergery/bin/python -m unittest discover -s testsran 214 tests OK. -
python3 -m unittest discover -s testsran 214 tests OK, skipped 15 Qt tests without PySide6. -
python3 -m compileall hypergery-ubuntupassed. -
bash -npassed for all deployment/acceptance scripts. -
docker compose config,docker compose build, anddocker compose up -dpassed. -
curl http://127.0.0.1:8765/healthreturned{"ok": true}. -
agent oncerefreshedubuntu-hyperv-sourceandubuntu-hyperv-target. -
host test ubuntu-hyperv-sourcewas processed by the source agent withpong=true. - App settings added for Hub URL, host identity, NAS staging path, and default VM creation values.
-
doctordiagnostics added and smoke-tested against the local Hub. - Remote Hosts Hub status summary added.
-
docs/QUICK_START_V06.mdadded. - Real two-physical-host NAS Clone Migration smoke passed.
- v0.6.0 release prerequisites were satisfied before final publication.
v0.6.0 final validation proves NAS Clone Migration behavior without deleting the source VM or original disks.
Required automated checks:
cd hypergery-ubuntu && python3 -m unittest discover -s tests
cd hypergery-ubuntu && ~/.venvs/hypergery/bin/python -m unittest discover -s tests
python3 -m compileall hypergery-ubuntu
bash -n scripts/dev-run.sh scripts/bootstrap-ubuntu.sh scripts/preflight.sh scripts/acceptance-ubuntu.sh scripts/acceptance-real-host.sh scripts/install-ubuntu-deps.sh scripts/install-desktop-launcher.shFirst-run bootstrap smoke:
-
./scripts/dev-run.sh --check-onlyprints system/package/service/group/Python readiness and does not install. -
./scripts/dev-run.sh --no-installexits clearly if anything is missing. - On a prepared host,
./scripts/dev-run.sh --no-installruns preflight and starts the Qt app without reinstalling. - On a fresh Ubuntu laptop,
./scripts/dev-run.shasks before installing packages. -
./scripts/dev-run.sh --installinstalls/fixes missing items without the interactive question, while sudo/pkexec still prompts normally. - If
kvm/libvirtmembership changes, the script prints the logout/login warning. - The venv is created at
~/.venvs/hypergerywith--copies, not inside the repo.
Bootstrap smoke on prepared host (2026-06-04):
-
./scripts/dev-run.sh --check-onlyreported no missing system tools, no inactive services, no missing groups, and Python environment ready. -
timeout 8s ./scripts/dev-run.sh --no-installdid not reinstall anything, ran preflight successfully, and reached Qt app startup before the controlled timeout.
Required local smoke:
- Start local registry on port
8765:python -m hypergery_ubuntu.cli registry serve. - Start local HyperGery agent or run one cycle:
python -m hypergery_ubuntu.cli agent once. - Confirm local host registration and heartbeat with
python -m hypergery_ubuntu.cli host list. - List hosts from CLI and UI.
- Create a safe
pingcommand withpython -m hypergery_ubuntu.cli host test <host_id>and confirm the agent returns a result. - Start a remote migration with
python -m hypergery_ubuntu.cli migrate remote <vm_name> --nas-path /mnt/hypergery-nas --source-host-id <source> --target-host-id <target> --target-vm-name <target_name>. - Poll it with
python -m hypergery_ubuntu.cli migrate status --migration-id <migration_id>. - Run migration preflight with a fake/offline target and confirm a clear blocking error.
- Package an existing stopped test VM if available.
- Validate the migration package manifest and checksums.
- Import package locally in dry-run or isolated test mode if no second host is available.
- Confirm source VM still exists and source disks remain untouched.
- Create or edit a VM with display mode
vnc. - Start the VM and press Console.
- Confirm a separate HyperGery Console - <vm_name> window opens.
- Confirm it connects automatically for a running VNC VM.
- Confirm the full guest framebuffer is visible, centered, and scaled with Scale to Fit enabled.
- Resize the console window and confirm the image remains complete and centered.
- Toggle Scale to Fit off/on and confirm real-size scrolling and fitted view work.
- Click inside to capture input, and press Right Ctrl to release.
- Confirm External Console still opens
virt-viewerorremote-viewer. - Disconnect/close the console window and confirm the VM keeps running.
- Start or select a running SPICE VM and confirm the console window shows the VNC-required card, does not capture input, and offers Open External Viewer.
- Select a shut off SPICE VM and confirm Switch to VNC is enabled.
- Switch to VNC, start the VM, press Console, and confirm the integrated VNC console connects.
Registry/agent local smoke on prepared host (2026-06-04):
- Started local registry with a temporary SQLite DB on
127.0.0.1:18765. - Ran
agent oncewith a temporary config and registeredlocal-smoke. - Listed hosts through CLI and confirmed
local-smokewas present. - Queued a safe
pingcommand throughhost test local-smoke. - Ran
agent onceagain and confirmed command statusdonewithpong=true.
Migration package unit/CLI smoke on prepared host (2026-06-04):
-
migration_preflight()blocks a running VM withsource_will_be_deleted=false. -
export_vm_package()createsmanifest.json,domain.xml, copied disk/ISO assets, checksums, lab metadata, and migration log inmigrations/<migration_id>/. -
validate_vm_package()accepts a clean package and reports checksum mismatch after asset tampering. -
import_vm_package()rewrites target VM name, UUID, MAC address, disk paths, ISO paths, network metadata, and lab association using a simulated backend. - CLI
migrate preflightreturns JSON and preservessource_will_be_deleted=false. - Agent
preflightcommand runs VM migration preflight and fails safely for running VMs. - Agent
receive_vm_packagevalidates only packages inside configured NAS staging. - Agent
import_vm_packagecalls the package import flow and blocks paths outside staging. - Qt Live Migration dialog runs VM preflight and keeps package creation disabled for running VMs.
Recommended real NAS/two-host smoke:
- Run registry on the NAS or a machine acting as NAS.
- Configure shared staging path on source and target hosts.
- Start agent on source host and target host.
- Confirm CLI
host listand the Qt Remote Hosts panel show both hosts online with KVM/libvirt OK. - Queue
host test <target_host_id>, run the target agent, and confirm command statusdone. - Use a stopped test VM with a mounted ISO.
- Right-click VM -> Live Migration.
- Select target host and run preflight.
- Start migration using offline or paused NAS Clone strategy.
- Poll
migrate status --migration-id <migration_id>untildone. - Confirm package exists under
/mnt/hypergery-nas/migrations/<migration_id>. - Confirm source VM remains on the source host.
- Confirm target VM appears on destination with new UUID and MAC.
- Confirm disks, ISO, lab metadata, network metadata, templates used, and migration log are present.
- Start target VM.
- Clean up only the test target VM/package after confirmation.
Blocking conditions:
- Running VM copy must be blocked unless a real safe libvirt/QEMU strategy is implemented.
- Missing disks are critical errors.
- Missing ISO is an error when
include_iso=True. - Target host offline, missing staging path, insufficient space, and target name conflicts must block Start Migration.
- No v0.6.0 release may be created until this checklist is completed.
Run with system Python (PySide6 not required):
cd hypergery-ubuntu && python3 -m unittest discover -s tests
# Expected: Ran 131 tests — OK (skipped=4)Run inside the venv (all tests including Qt):
cd hypergery-ubuntu && ~/.venvs/hypergery/bin/python -m unittest discover -s tests
# Expected: Ran 131 tests — OKThe 4 skipped tests are Qt widget tests that require PySide6. They pass cleanly in the venv.
New in v0.5.0: 10 additional tests covering build_lab_topology (empty, live VMs, not-created VMs, cross-lab exclusion, deduplication, JSON export), CLI template update, CLI lab-topology, CLI lab-instantiate --dry-run, and libvirt KiB memory parsing.
Offscreen Qt smoke (2026-06-03):
QT_QPA_PLATFORM=offscreen python -c "
from PySide6.QtWidgets import QApplication; import sys
from hypergery_ubuntu.ui_qt.topology import LabTopologyWidget
from hypergery_ubuntu.ui_qt.lab_helpers import build_lab_topology
from hypergery_ubuntu.backend import VmSummary
app = QApplication(sys.argv)
w = LabTopologyWidget(); w.resize(500, 300)
lab = {'lab_id': 'asr-lab', 'name': 'ASR Lab', 'network_mode': 'isolated',
'network_id': 'hg-net-asr-lab-isolated', 'subnet': '192.168.30.0/24',
'bridge_name': 'hgbr1234567', 'vms': ['server', 'ghost']}
vms = [VmSummary(name='server', state='running', lab_id='asr-lab', ram_mib=4096, vcpus=2)]
w.set_topology(build_lab_topology(lab, vms)); w.show()
print(w.grab().width()) # should print 500
"Result: widget renders at 500×300 px, 2 VM nodes (server=live/running, ghost=not created). OK.
Validated on a real Ubuntu/KVM/libvirt host from develop. The UI-specific interactions were exercised with the real PySide6 widgets using Qt's test driver/offscreen rendering because the active desktop session was Wayland and no desktop automation/screenshot tools were available to the agent. Real libvirt resources were created, started, paused, force-powered-off, opened through the console flow, and cleaned up.
-
git switch develop -
git pull origin develop -
./scripts/preflight.sh - System Python tests:
Ran 131 tests — OK - Venv PySide6 tests:
Ran 131 tests — OK -
python3 -m compileall hypergery-ubuntu -
bash -nfor all release scripts -
./scripts/dev-run.shlaunched without immediate traceback; stopped by controlled timeout after startup.
- Created lab
hg-v05-topology-lab. - Created real VM
hg-v05-topology-vmfrom a local Ubuntu server ISO. - Started VM and confirmed
runningvia libvirt. - Suspended/resumed VM and confirmed
pausedtopology state. - Force-powered VM off and confirmed
shut off. - Rendered
LabTopologyWidgetwith network node on the left and VM nodes on the right. - Confirmed colors: running green, shutoff gray, paused amber, not-created slate.
- Clicked VM node via Qt test driver and confirmed the widget emitted selection for
hg-v05-topology-vm. - No traceback.
- Created lab template
hg-v05-asr-template. - Added planned VMs
hg-v05-ad-serverandhg-v05-client. - Opened planned VM edit dialog and edited name, RAM, vCPUs, disk, role,
template_id, and notes. - Duplicate planned VM name was blocked.
- Valid changes were saved and reflected in the table.
- Opened the instantiation wizard for
hg-v05-asr-template. - Confirmed missing ISO status label lists required VMs.
- Applied the same local Ubuntu server ISO once via "Apply same ISO to all VMs...".
- Confirmed all required ISO rows were filled and status label cleared.
- Instantiated
hg-v05-asr-labfromhg-v05-asr-template. - Created real VMs
hg-v05-ad-server-renamedandhg-v05-client. - Confirmed
templates_used = ["hg-v05-asr-template"]. - Confirmed backend activity log entries in
~/.local/state/hypergery/logs/hypergery.log. - Started
hg-v05-ad-server-renamed. - Opened console with
virt-viewerflow. - ACPI shutdown did not complete within the smoke timeout; force-off succeeded and VM returned to
shut off.
- Opened
CleanupPreviewDialog. - Confirmed it lists HyperGery VMs, labs, VM templates, and lab templates.
- Confirmed the dialog is read-only and does not mutate resource counts.
-
lab-topology hg-v05-topology-labreturned valid JSON. - Found and fixed a real issue:
ram_mibwas0because libvirt returns memory as KiB indumpxml. -
lab-topology hg-v05-topology-labthen returnedram_mib: 1024for the real test VM. -
lab-instantiate hg-v05-asr-template hg-v05-cli-dry-run --dry-runreturned JSON and created no lab/VM resources. It correctly reported missing ISO errors because that exact command does not provide ISO mappings. -
template update lab hg-v05-asr-template --set notes="v0.5 smoke test"updated the template.
- Deleted only VMs/labs/templates with prefix
hg-v05. - Deleted only HyperGery-managed disks through
delete-vm --delete-disks. - Removed test libvirt networks
hg-net-hg-v05-asr-labandhg-net-hg-v05-topology-lab. - Final
virsh --connect qemu:///system list --allshowed only the pre-existingubuntuVM. - No
hg-v05-*labs/templates/disks remained under~/.local/share/hypergery.
HyperGeryBackend.get_vm()now converts libvirt memory units to MiB. This fixes topology/CLI reporting for hosts wherevirsh dumpxmlnormalizes<memory>tounit="KiB".
Run from the Qt UI (python -m hypergery_ubuntu inside the venv). Requires a real Ubuntu KVM/libvirt host.
- Create or select a lab with at least one VM (e.g.
hg-v04-asr-labfrom v0.4.0 smoke) - Click the Topology sub-tab in the Lab Details panel
- Network node visible on the left with network name, mode, and subnet
- VM node(s) visible on the right, colour-coded by state
- Start a VM → topology refreshes after next Refresh → node turns green
- Click a VM node → VM selected in the main list, Details tab activates
- Select a lab template → Click Edit
- Planned VMs table shows columns: Name, Role, OS, RAM MiB, vCPUs, Disk GB, Display, ISO req.
- Double-click a VM row → Edit dialog opens with fields pre-filled
- Change RAM, click OK → table updates immediately
- Add a VM with the same name as an existing one → duplicate error shown
- Remove a VM row → VM count decreases
- Select a lab template with ≥2 planned VMs requiring ISO
- Click Create Lab from Template → Page 2 (ISO Mapping)
- Click Apply same ISO to all VMs… → browse once → all rows filled
- Status label disappears when all required ISOs are set
- Click Resources… button in toolbar
- Dialog shows all VMs, labs, VM templates, lab templates
- No delete buttons — read-only
- Close button works
python -m hypergery_ubuntu.cli template update vm hg-v04-ubuntu-template --set ram_mib=8192
# expected: JSON output with ram_mib=8192- JSON returned;
ram_mibupdated in the file
python -m hypergery_ubuntu.cli lab-topology hg-v04-asr-lab
# expected: JSON with lab_id, subnet, vms list- JSON returned;
vmslist present
python -m hypergery_ubuntu.cli lab-instantiate hg-v04-asr-template "ASR Test" \
--iso hg-v04-ad-server=/path/to/ubuntu.iso \
--iso hg-v04-client=/path/to/ubuntu.iso \
--dry-run
# expected: JSON with dry_run=true, errors=[], lab=null- dry_run=true in response; no lab created
- All topology-tab switches, resource overview open, template edits appear in log
- Topology node click on a real running VM
- Per-VM progress during lab instantiation (not yet implemented)
Run with system Python (PySide6 not required):
cd hypergery-ubuntu && python3 -m unittest discover -s tests
# Expected: Ran 121 tests — OK (skipped=4)Run inside the venv (all tests including Qt):
cd hypergery-ubuntu && ~/.venvs/hypergery/bin/python -m unittest discover -s tests
# Expected: Ran 121 tests — OKThe 4 skipped tests are Qt widget tests that require PySide6. They pass cleanly in the venv.
New in v0.4.0: 20 additional tests covering instantiate_lab_template (dry_run, ISO validation, rollback, iso_required=False), update_vm/lab_template, planned VM validation (duplicate names, empty names), and _resolve_planned_vm precedence.
Run from the Qt UI (python -m hypergery_ubuntu inside the venv). Validated on a real Ubuntu KVM/libvirt host.
- Create VM template
hg-v04-ubuntu-template(RAM=4096, vCPUs=2, Disk=40) - Create lab template
hg-v04-asr-template(Network=isolated) - Edit
hg-v04-asr-template→ Add planned VMhg-v04-ad-server(role=server, iso_required=true) - Edit
hg-v04-asr-template→ Add planned VMhg-v04-client(role=client, iso_required=true) - Lab template detail panel shows VMs count = 2
- Click Create Lab from Template
- Page 1: Enter name — preview shows lab_id and subnet
- Page 2: Browse ISO for both VMs; Next disabled without ISOs
- Page 3: Review shows both VMs with ISOs and resources
- Click Create Lab — activity log shows progress
- Instances tab shows lab with both VMs listed
- Lab details panel shows
templates_used = hg-v04-asr-template - Start
hg-v04-ad-server→ Open Console → installer appears - Shutdown / Force Off
- Select VM template → Click Edit → Change RAM, add note → Save
- Detail panel updates with new values
- Select
hg-v04-asr-template→ Click Edit → Add/remove planned VMs → Save - Detail panel reflects updated VM count
- Select lab with VMs → Click Duplicate Lab → Clone VMs checkbox is enabled
- Clone VMs with disk cloning (not completed in this smoke — requires all VMs shut off simultaneously; defer to extended test)
- Delete lab and VMs; delete both templates
- Activity log records all operations; no tracebacks
- CLI
template update/template instantiate(not yet implemented) - Rollback from partial VM creation failure with a real ISO
- Duplicate Lab with Clone VMs end-to-end (disk clone path)
Run from the Qt UI (python -m hypergery_ubuntu inside the venv).
- Create lab
hg-v03-asrwith network=isolated - Create lab
hg-v03-parwith network=nat - Confirm subnets differ in Lab Details panel
- Rename
hg-v03-pardisplay name (lab_id unchanged) - Export
hg-v03-asrto/tmp/hg-v03-asr.json - Import
/tmp/hg-v03-asr.jsonwith new idhg-v03-asr-copy - Verify
hg-v03-asr-copyappears in the lab list with a different subnet - Delete all temporary labs
- Create VM template
hg-v03-ubuntu-template(OS=linux, RAM=4096, vCPUs=2, Disk=40, Net=nat, Display=spice) - Verify detail panel shows all fields including Notes
- Create Lab template
hg-v03-asr-template(Network=isolated) - Verify planned VMs count = 0 (no VMs defined in this template)
- Export
hg-v03-ubuntu-templateto/tmp/hg-v03-ubuntu-template.json - Delete
hg-v03-ubuntu-template, then import it back from/tmp/ - Attempt import again with template present — error shown, no overwrite
- Select
hg-v03-ubuntu-template— Create VM from Template button activates - Click Create VM from Template — wizard opens with RAM/vCPUs/Disk/Net/Display pre-filled
- ISO/name validation works (wizard disables Finish without valid ISO)
- Select
hg-v03-asr-template— Create Lab from Template button activates - Click Create Lab from Template — dialog shows network=isolated, empty planned VMs list
- Enter name
ASR Instance 01— preview shows lab_id, bridge, subnet - Create the lab — appears in Instances tab with
templates_used = hg-v03-asr-template - Delete
ASR Instance 01,hg-v03-ubuntu-template,hg-v03-asr-template
- All above operations appear in the Activity Log panel
- Copy log to clipboard works
- Create VM from Template end-to-end with a real ISO
- Verify
templates_usedin the lab JSON after VM creation - Console, snapshots, clone on a real VM
- Lab ID validation and normalization.
- Lab create/list/show/rename/delete/export/import.
- Legacy lab manifest migration to schema version 2.
- Portable lab export without private disk/ISO paths.
- Lab bridge generation with Linux interface length limits.
- Lab subnet allocation avoiding
192.168.122.0/24and collisions. - VM template create/list/show/delete/export/import.
- Lab template create/list/show/delete/export/import.
- Template ID preview/normalization.
- Wizard defaults mapping (os_type, ram_mib, vcpus, disk_gb, network_mode, display).
- Import collision rejection (no silent overwrite).
- Delete non-existent template raises clear error.
- CLI coverage for
labandtemplatecommands.
- Lab preview helper generates
lab_id, network ID, bridge, and subnet before creation. - Preview validation rejects duplicate lab IDs.
- VM filter helper supports
All VMsandSelected Lab. - VM count combines live libvirt summaries and manifest entries.
- Auto-create planned VMs from lab template.
- Edit templates in place.
- Clone VM disks during lab duplicate.
- Delete Lab with VMs included.
v0.2.0 was manually validated from the PySide6/Qt UI on a real Ubuntu KVM/libvirt host.
Validated:
- PySide6/Qt UI starts from the venv/NAS setup.
- Host preflight reaches libvirt when the user has effective
libvirtgroup membership. - New VM wizard creates
hg-v02-qt-testfrom a real ISO. - Start works and the VM reaches
running. - Console opens through
virt-viewerand displays the installer. - Power-off path works through ACPI Shutdown or Force Off, depending on guest responsiveness.
- Snapshots create/list/revert/delete work from the UI.
- Clone to
hg-v02-qt-cloneworks. - Safe delete of test and clone works.
- No
hg-v02-qt-testorhg-v02-qt-cloneVMs/disks remain after validation. - VM state loading works with localized
virshoutput such asejecutando.
Use real names:
hg-v02-qt-test
hg-v02-qt-clone
Run:
git switch develop
git pull origin develop
source ~/.venvs/hypergery/bin/activate
./scripts/preflight.sh
./scripts/dev-run.shIf the current login session has not inherited the libvirt group yet, either log out and back in or run:
sg libvirt -c 'cd /path/to/miversiondevirtualbox && source ~/.venvs/hypergery/bin/activate && ./scripts/dev-run.sh'Checklist:
- Create VM
hg-v02-qt-testfrom a real Ubuntu/Debian ISO. - Confirm the VM appears in the list with correct state, lab, CPU, and RAM.
- Start
hg-v02-qt-test. - Open Console.
- Create snapshot
before-install. - List snapshots and confirm
before-installappears. - Revert snapshot
before-install. - Delete snapshot
before-install. - ACPI shutdown or Force Off, depending on guest responsiveness.
- Clone stopped VM to
hg-v02-qt-clone. - Start clone and confirm it is independent.
- Stop clone.
- Delete clone with disk deletion.
- Delete original with disk deletion.
HyperGery v0.1.0 was validated on a real Ubuntu KVM/libvirt host.
The validation covered:
- Real preflight against
/dev/kvm, libvirt, QEMU tools, and viewer tools. - Real VM creation from an Ubuntu ISO.
- Real qcow2 disk creation.
- Real libvirt network creation for
hg-net-default-lab. - Real SPICE console opened with
virt-viewer. - Real snapshots: create, list, revert, delete.
- Real clone of a stopped VM with an independent qcow2 disk.
- Safe delete of managed test VMs and disks.
Repeat CLI acceptance:
./scripts/preflight.sh
./scripts/acceptance-ubuntu.sh --iso /path/to/ubuntu-or-debian.iso --name hg-acceptance-ubuntu-testpython3 -m unittest discover -s hypergery-ubuntu/testsExpected: all non-Qt tests pass; test_qt_ui and test_qt_lab_helpers classes that require PySide6 are skipped (not errors). Overall result: OK (skipped=N).
~/.venvs/hypergery/bin/python -m unittest discover -s testsExpected: all tests pass including Qt UI tests.
Run this after starting the Qt UI (python -m hypergery_ubuntu inside the venv).
-
Open the Templates tab in the left panel.
-
Create VM template
- Click New VM Template.
- Enter Name:
HG v03 Ubuntu Template. - Verify Template ID preview shows
hg-v03-ubuntu-template. - Set OS=linux, RAM=4096, vCPUs=2, Disk=40, Network=nat, Display=spice.
- Click Create — template appears in the VM Templates table.
-
Create Lab template
- Click New Lab Template.
- Enter Name:
HG v03 ASR Template. - Verify Template ID preview shows
hg-v03-asr-template. - Set Network=isolated.
- Click Create — template appears in the Lab Templates table.
-
Select and inspect
- Click on
hg-v03-ubuntu-template— detail panel shows all fields, Create VM from Template button activates. - Click on
hg-v03-asr-template— detail panel updates, Create Lab from Template button activates.
- Click on
-
Create VM from Template
- Select
hg-v03-ubuntu-template. - Click Create VM from Template.
- Wizard opens with RAM=4096, vCPUs=2, Disk=40, Network=nat, Display=spice pre-filled.
- Enter a VM name and a valid local ISO path.
- Complete the wizard — VM is created; activity log shows "Creating VM … from template".
- Open the Instances tab — VM appears in the list.
- (Optional) Open the lab manifest JSON and verify
templates_usedcontainshg-v03-ubuntu-template.
- Select
-
Create Lab from Template
- Select
hg-v03-asr-template. - Click Create Lab from Template.
- Dialog opens with network=isolated pre-filled, preview shows lab_id/bridge/subnet.
- Enter a lab name (e.g.
ASR Instance 01). - Click Create Lab — lab appears in the Labs table; activity log shows "Created lab … from template".
- Verify
templates_usedin the lab manifest.
- Select
-
Export VM template
- Select
hg-v03-ubuntu-template. - Click Export — choose a path like
/tmp/hg-v03-ubuntu-template.json. - File is created with valid JSON.
- Select
-
Import VM template (collision)
- With
hg-v03-ubuntu-templatepresent, click Import and select the same file. - An error is shown: "VM template already exists" — no silent overwrite.
- With
-
Delete test artifacts
- Delete
hg-v03-ubuntu-templateandhg-v03-asr-templateby typing their IDs. - Delete the lab created in step 6.
- Tables are empty after deletion.
- Delete
Expected: no tracebacks, activity log records each operation, UI stays responsive.