Skip to content

Latest commit

 

History

History
766 lines (598 loc) · 37.6 KB

File metadata and controls

766 lines (598 loc) · 37.6 KB

HyperGery Validation

v0.8.0 — Remote Cluster Workflows (in development, overnight run 2026-06-05)

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-ubuntu OK.
  • bash -n on all 9 shell scripts OK.
  • docker compose config OK.
  • 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".

v0.7.0 — Visual Refresh & Hub Transfer close-out (2026-06-05)

  • QT_QPA_PLATFORM=offscreen ~/.venvs/hypergery/bin/python -m unittest discover -s tests ran 249 tests OK.
  • python3 -m unittest discover -s tests ran 249 tests OK with Qt tests skipped cleanly.
  • python3 -m compileall hypergery-ubuntu OK.
  • bash -n on all 9 shell scripts OK (including start-second-host.sh and install-agent-user-service.sh).
  • docker compose config OK.
  • 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
  • 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.

HyperGery Hub Docker

Validate the Docker deployment files without starting the service:

cd docker
docker compose config
docker compose build

When running on the NAS:

curl http://192.168.1.150:8765/health
curl http://192.168.1.150:8765/hosts

Agent 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:8765

Docker/Hub/Agent smoke on prepared host (2026-06-05):

  • docker compose config passed.
  • Initial Docker smoke exposed a real deployment issue: SQLite DB on ./data can lock when the repo is on a NAS/shared mount.
  • Docker Compose now persists /data in the Docker volume hypergery-hub-data; /hypergery remains the NAS data bind mount.
  • Docker image includes a /health healthcheck.
  • docker compose build completed.
  • docker compose up -d --force-recreate started hypergery-hub.
  • curl http://127.0.0.1:8765/health returned {"ok": true}.
  • curl http://127.0.0.1:8765/hosts returned an empty host list before agent registration.
  • curl http://127.0.0.1:8765/vms returned an empty VM list before agent inventory.
  • agent once registered ubuntu-hyperv with KVM/libvirt OK.
  • host list showed ubuntu-hyperv online.
  • hub vms returned the current VM inventory from the agent.
  • host test ubuntu-hyperv queued a ping command, and a second agent once completed it with pong=true.
  • Qt Remote Hosts offscreen smoke loaded ubuntu-hyperv from the real local Hub.
  • Qt Live Migration dialog offscreen smoke listed ubuntu-hyperv from the real local Hub and kept Start Migration disabled until preflight.
  • timeout 8s ./scripts/dev-run.sh --no-install reached 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-source and ubuntu-hyperv-target.
  • Hub Docker was running at http://127.0.0.1:8765.
  • NAS staging was writable at /home/gerard/NAS_Gerard/hypergery in 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, strategy nas_clone, source_will_be_deleted=false, no warnings, no errors.
  • Target agent processed import_vm_package command with status done.
  • 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 Source on gerard-MS-7E26).
  • Target host: hg-target (Lenovo Target on gery-Lenovo-ideapad-330S-14IKB).
  • Old offline hosts from previous smoke runs were ignored.
  • hg-target initially reported libvirt_ok=false because an old agent process was running with stale state; restarting the agent after libvirt/group setup fixed it.
  • host test commands initially printed pending because the CLI only queued commands; the agents did process them. host test now waits for terminal status by default.
  • hg-source and hg-target both reported online, kvm_ok=true, and libvirt_ok=true.
  • host test hg-source completed with status=done and pong=true.
  • host test hg-target completed with status=done and pong=true.
  • Hub VM inventory refreshed for hg-source and hg-target.
  • NAS staging path /mnt/hypergery-nas/hypergery was 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, MAC 52: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-target was 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, strategy nas_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-off after ACPI timeout, then delete-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):

  • develop was synchronized with origin/develop.
  • QT_QPA_PLATFORM=offscreen /home/gerard/.venvs/hypergery/bin/python -m unittest discover -s tests ran 214 tests OK.
  • python3 -m unittest discover -s tests ran 214 tests OK, skipped 15 Qt tests without PySide6.
  • python3 -m compileall hypergery-ubuntu passed.
  • bash -n passed for all deployment/acceptance scripts.
  • docker compose config, docker compose build, and docker compose up -d passed.
  • curl http://127.0.0.1:8765/health returned {"ok": true}.
  • agent once refreshed ubuntu-hyperv-source and ubuntu-hyperv-target.
  • host test ubuntu-hyperv-source was processed by the source agent with pong=true.
  • App settings added for Hub URL, host identity, NAS staging path, and default VM creation values.
  • doctor diagnostics added and smoke-tested against the local Hub.
  • Remote Hosts Hub status summary added.
  • docs/QUICK_START_V06.md added.
  • Real two-physical-host NAS Clone Migration smoke passed.
  • v0.6.0 release prerequisites were satisfied before final publication.

v0.6.0 — NAS Clone Migration Validation Plan

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.sh

First-run bootstrap smoke:

  • ./scripts/dev-run.sh --check-only prints system/package/service/group/Python readiness and does not install.
  • ./scripts/dev-run.sh --no-install exits clearly if anything is missing.
  • On a prepared host, ./scripts/dev-run.sh --no-install runs preflight and starts the Qt app without reinstalling.
  • On a fresh Ubuntu laptop, ./scripts/dev-run.sh asks before installing packages.
  • ./scripts/dev-run.sh --install installs/fixes missing items without the interactive question, while sudo/pkexec still prompts normally.
  • If kvm/libvirt membership changes, the script prints the logout/login warning.
  • The venv is created at ~/.venvs/hypergery with --copies, not inside the repo.

Bootstrap smoke on prepared host (2026-06-04):

  • ./scripts/dev-run.sh --check-only reported no missing system tools, no inactive services, no missing groups, and Python environment ready.
  • timeout 8s ./scripts/dev-run.sh --no-install did 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 ping command with python -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-viewer or remote-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 once with a temporary config and registered local-smoke.
  • Listed hosts through CLI and confirmed local-smoke was present.
  • Queued a safe ping command through host test local-smoke.
  • Ran agent once again and confirmed command status done with pong=true.

Migration package unit/CLI smoke on prepared host (2026-06-04):

  • migration_preflight() blocks a running VM with source_will_be_deleted=false.
  • export_vm_package() creates manifest.json, domain.xml, copied disk/ISO assets, checksums, lab metadata, and migration log in migrations/<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 preflight returns JSON and preserves source_will_be_deleted=false.
  • Agent preflight command runs VM migration preflight and fails safely for running VMs.
  • Agent receive_vm_package validates only packages inside configured NAS staging.
  • Agent import_vm_package calls 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 list and 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 status done.
  • 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> until done.
  • 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.

v0.5.0 RC — Automated Tests Status

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 — OK

The 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.

v0.5.0 RC — Manual/Host Smoke Validated (2026-06-04)

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.

Preparation

  • 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 -n for all release scripts
  • ./scripts/dev-run.sh launched without immediate traceback; stopped by controlled timeout after startup.

Lab Topology View

  • Created lab hg-v05-topology-lab.
  • Created real VM hg-v05-topology-vm from a local Ubuntu server ISO.
  • Started VM and confirmed running via libvirt.
  • Suspended/resumed VM and confirmed paused topology state.
  • Force-powered VM off and confirmed shut off.
  • Rendered LabTopologyWidget with 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.

Planned VM Editor

  • Created lab template hg-v05-asr-template.
  • Added planned VMs hg-v05-ad-server and hg-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.

ISO Reuse

  • 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.

Instantiate Lab Template

  • Instantiated hg-v05-asr-lab from hg-v05-asr-template.
  • Created real VMs hg-v05-ad-server-renamed and hg-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-viewer flow.
  • ACPI shutdown did not complete within the smoke timeout; force-off succeeded and VM returned to shut off.

Cleanup Preview

  • 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.

CLI

  • lab-topology hg-v05-topology-lab returned valid JSON.
  • Found and fixed a real issue: ram_mib was 0 because libvirt returns memory as KiB in dumpxml.
  • lab-topology hg-v05-topology-lab then returned ram_mib: 1024 for the real test VM.
  • lab-instantiate hg-v05-asr-template hg-v05-cli-dry-run --dry-run returned 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.

Cleanup

  • 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-lab and hg-net-hg-v05-topology-lab.
  • Final virsh --connect qemu:///system list --all showed only the pre-existing ubuntu VM.
  • No hg-v05-* labs/templates/disks remained under ~/.local/share/hypergery.

Bug Fixed During Validation

  • HyperGeryBackend.get_vm() now converts libvirt memory units to MiB. This fixes topology/CLI reporting for hosts where virsh dumpxml normalizes <memory> to unit="KiB".

v0.5.0 RC — Manual Smoke Checklist

Run from the Qt UI (python -m hypergery_ubuntu inside the venv). Requires a real Ubuntu KVM/libvirt host.

Lab Topology

  • Create or select a lab with at least one VM (e.g. hg-v04-asr-lab from 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

Planned VM Editor (improved)

  • 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

ISO Reuse in Wizard

  • 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

Resource Overview

  • Click Resources… button in toolbar
  • Dialog shows all VMs, labs, VM templates, lab templates
  • No delete buttons — read-only
  • Close button works

CLI — template update

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_mib updated in the file

CLI — lab-topology

python -m hypergery_ubuntu.cli lab-topology hg-v04-asr-lab
# expected: JSON with lab_id, subnet, vms list
  • JSON returned; vms list present

CLI — lab-instantiate dry-run

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

Activity Log

  • All topology-tab switches, resource overview open, template edits appear in log

Not smoke-tested (requires extended setup)

  • Topology node click on a real running VM
  • Per-VM progress during lab instantiation (not yet implemented)

v0.4.0 — Automated Tests Status

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 — OK

The 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.

v0.4.0 — Manual Smoke Validated (2026-06-03)

Run from the Qt UI (python -m hypergery_ubuntu inside the venv). Validated on a real Ubuntu KVM/libvirt host.

Lab Template Instantiation

  • 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 VM hg-v04-ad-server (role=server, iso_required=true)
  • Edit hg-v04-asr-template → Add planned VM hg-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

Edit VM Template

  • Select VM template → Click Edit → Change RAM, add note → Save
  • Detail panel updates with new values

Edit Lab Template + Planned VMs

  • Select hg-v04-asr-template → Click Edit → Add/remove planned VMs → Save
  • Detail panel reflects updated VM count

Lab Duplicate with VM Cloning

  • 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)

Cleanup

  • Delete lab and VMs; delete both templates
  • Activity log records all operations; no tracebacks

Not smoke-tested (requires extended setup)

  • 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)

v0.3.0 — Manual Smoke Validated (2026-06-03)

Run from the Qt UI (python -m hypergery_ubuntu inside the venv).

Lab Manager

  • Create lab hg-v03-asr with network=isolated
  • Create lab hg-v03-par with network=nat
  • Confirm subnets differ in Lab Details panel
  • Rename hg-v03-par display name (lab_id unchanged)
  • Export hg-v03-asr to /tmp/hg-v03-asr.json
  • Import /tmp/hg-v03-asr.json with new id hg-v03-asr-copy
  • Verify hg-v03-asr-copy appears in the lab list with a different subnet
  • Delete all temporary labs

Templates Manager

  • 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-template to /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-templateCreate 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-templateCreate 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

Activity Log

  • All above operations appear in the Activity Log panel
  • Copy log to clipboard works

Not smoke-tested (requires real ISO or KVM host)

  • Create VM from Template end-to-end with a real ISO
  • Verify templates_used in the lab JSON after VM creation
  • Console, snapshots, clone on a real VM

v0.3.0 Backend — Already Validated by Tests

  • 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/24 and 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 lab and template commands.

v0.3.0 Qt Lab Manager — Validated by Unit Tests

  • Lab preview helper generates lab_id, network ID, bridge, and subnet before creation.
  • Preview validation rejects duplicate lab IDs.
  • VM filter helper supports All VMs and Selected Lab.
  • VM count combines live libvirt summaries and manifest entries.

Not yet implemented (v0.4 target)

  • 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 PySide6 UI Validation Status

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 libvirt group membership.
  • New VM wizard creates hg-v02-qt-test from a real ISO.
  • Start works and the VM reaches running.
  • Console opens through virt-viewer and 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-clone works.
  • Safe delete of test and clone works.
  • No hg-v02-qt-test or hg-v02-qt-clone VMs/disks remain after validation.
  • VM state loading works with localized virsh output such as ejecutando.

v0.2.0 Manual UI Checklist

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.sh

If 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-test from 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-install appears.
  • 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.

v0.1.0 Validation

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-test

Running tests

System Python (no PySide6)

python3 -m unittest discover -s hypergery-ubuntu/tests

Expected: 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).

Venv with PySide6

~/.venvs/hypergery/bin/python -m unittest discover -s tests

Expected: all tests pass including Qt UI tests.

Templates Manager smoke test (v0.3.0)

Run this after starting the Qt UI (python -m hypergery_ubuntu inside the venv).

  1. Open the Templates tab in the left panel.

  2. 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.
  3. 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.
  4. 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.
  5. 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_used contains hg-v03-ubuntu-template.
  6. 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_used in the lab manifest.
  7. 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.
  8. Import VM template (collision)

    • With hg-v03-ubuntu-template present, click Import and select the same file.
    • An error is shown: "VM template already exists" — no silent overwrite.
  9. Delete test artifacts

    • Delete hg-v03-ubuntu-template and hg-v03-asr-template by typing their IDs.
    • Delete the lab created in step 6.
    • Tables are empty after deletion.

Expected: no tracebacks, activity log records each operation, UI stays responsive.